Best practices

• One MCP host, one terminal_id. Store operational_agent_id next to the workload key.
• Finish onboarding, including the handle and an ACTIVE grant, before the first 402.
• One orderRef, one payment idempotency key, including retries after X402_INTENT_EXPIRED and first-time merchant acceptance.
• Sign vouchers only with @sohopay/agent-signer and only on VOUCHER_ISSUED. Never put the borrower key in the host.
• Merchants fulfill on CONFIRMED only, unless they have explicitly accepted capture-then-deliver risk.
• Poll about every 2 seconds. Do not add a webhook listener. There is nothing to sign.
• Read the fee from the merchant you were provisioned with. Do not hard-code 5% or assume the payout equals the billed amount.
• Keep credentials on the staging hosts in Environment setup.

​

Next steps