com.agentscore.payment.x402 v1

1. Introduction

x402, multi-chain. Today AgentScore merchants ship the EVM scheme (Base); x402 also publishes Solana and Stellar schemes which slot in as additional `networks` entries.

AgentScore binding for x402 in UCP. x402 is a multi-chain payment protocol: today AgentScore merchants ship `@x402/evm` (Base via signed EIP-3009 transferWithAuthorization). x402 itself also publishes `@x402/svm` (Solana) and `@x402/stellar`; an AgentScore merchant adopts those by adding the relevant network identifier to `networks`. A facilitator (merchant-side or hosted, e.g. Coinbase CDP for EVM) verifies and settles on-chain. The x402 protocol itself is specified at x402.org.

2. Configuration

The schema for the binding's `config` object lives at /schemas/payment-handlers/x402.json. The wrapper fields (id, version, spec, schema, config) are defined by UCP itself.

Fields:

• networks (array of object): Array of x402 networks the merchant accepts. One entry per network. Must contain at least one entry.
• networks[].network (string): Network identifier matching x402's convention. EVM uses `<chain>-<chain_id>` (e.g. `base-8453`, `base-84532`); Solana uses `solana-mainnet-beta` / `solana-devnet`; Stellar uses `stellar-pubnet` / `stellar-testnet`.
• networks[].recipient (string (optional)): Optional. Merchant's static settlement address on this network. When present, agents MAY cross-check the 402 challenge's `payTo` against this declared address as MITM protection. Omit if the merchant uses per-order recipients on this network; the authoritative recipient still ships in the 402 body. Symmetric with mpp's `chains[].recipient`.

Example config:

{
  "networks": [
    { "network": "base-8453", "recipient": "0xabc..." }
  ]
}

3. Payment protocol

End-to-end flow from the merchant's 402 challenge to settlement:

1. 402 emit. Merchant returns 402 with accepts[] including an x402 entry per accepted network: { scheme: "exact", network: "base-8453", maxAmountRequired, asset, payTo, extra: { name } }. For EVM, extra.name MUST come from the on-chain USDC contract's name() (per the registered scheme).
2. Agent prep. Agent constructs the chain-appropriate authorization: EVM uses EIP-3009 typed data (from = agent's wallet, to = merchant's payTo, value = maxAmountRequired); Solana uses an SPL TransferChecked instruction; Stellar uses a SEP-10 / Soroban payment.
3. Sign. Agent signs with the wallet's private key. The signature constitutes a transferable authorization for the chain.
4. Retry. Agent re-POSTs the original request with the encoded payment header.
5. Settle. Merchant verifies + submits via the facilitator. On success returns 200 + X-Payment-Response header carrying the base64 settle receipt.

4. Server processing

Merchant-side responsibilities once the agent's payment credential arrives on the retry leg:

1. Receive the X-Payment header (or Authorization: Payment ) from the agent's retry.
2. Decode and validate via the chain-appropriate scheme (verifyX402Request({acceptedNetwork}) for EVM): parse the payload, confirm the network + payTo + value match the 402 challenge.
3. Call the facilitator's settle endpoint (e.g. Coinbase CDP settle_payment for EVM) which co-signs and submits the transaction on-chain.
4. On confirmation, capture the transaction hash and return the original resource with the X-Payment-Response header carrying the base64 settle receipt.

5. Security considerations

• EIP-3009 transferWithAuthorization (EVM) is replay-resistant via a nonce; the merchant MUST track used nonces (or rely on the facilitator to do so) to prevent double-spend. Equivalent replay protection exists per chain on Solana and Stellar.
• extra.name in the EVM 402 challenge MUST match the on-chain USDC contract's name() exactly; clients reject signatures that don't. Hardcoding will break across networks (Base mainnet USD Coin vs other chains).
• Use a hosted facilitator (Coinbase CDP for EVM) for production: it handles settle gas + replay tracking + redundancy. Self-host only if your settlement volume justifies operating a chain node.

See also

• Reference agent client: agentscore-pay (npm: @agent-score/pay). See docs.agentscore.com/integrations/pay-cli
• Merchant SDKs: @agent-score/commerce (Node) and agentscore-commerce (Python)
• UCP payment-handler guide: ucp.dev/specification/payment-handler-guide