Accept agent payments over x402

payTo is the one value you must not hardcode. Read it from ProtocolAddressRegistry once at startup and cache it for the process.

export RPC=https://mainnet.base.org
export CHAIN_ID=$(cast chain-id --rpc-url "$RPC")
export PAR=<ProtocolAddressRegistry — no deployment yet, see the notice on /quickstart>
 
export SPLIT_ROUTER=$(cast call "$PAR" 'getAddress(bytes32)(address)' \
  "$(cast keccak SPLIT_ROUTER)" --rpc-url "$RPC")

getAddress reverts AddressNotSet rather than returning the zero address, so a boot against a registry that has no split contract fails loudly instead of quoting payments to nowhere.

Why this address has to be right. The buyer does not sign the payTo you quote — it signs an authorisation to the split contract named in its own attribution token, and the facilitator requires those two addresses to be equal before it settles. Quote any other address and every payment to that endpoint is rejected, even though your 402 was otherwise perfect.

Two requests arrive for one purchase, and the retry carries the signed payment and nothing else.

So the first thing your handler tests is PAYMENT-SIGNATURE; the attribution token is only consulted when that header is missing. Reversed, the retry falls through into your direct-mode branch and the buyer receives a second 402 in answer to a payment it already signed.

app.all('/v1/mainnet', async (req, res) => {
  const payment = req.header('PAYMENT-SIGNATURE')
  if (payment) return settleAndServe(req, res, payment)   // the retry
 
  const attributionToken = req.header('X-Referrer-Token')
  if (!attributionToken) return respondDirect402(res)     // ordinary traffic
 
  return respondReferral402(res, req)                     // the probe
})

Answer on POST and on GET for the same URL: the buyer's tooling POSTs both requests, but our readiness probe GETs, so a POST-only handler passes every real purchase and still reports as not ready.

The body is an x402 v2 PaymentRequired. Only three keys live at the top level — x402Version, accepts and extensions — and the payment terms all sit inside accepts[0].

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:…",
      "asset": "0x…",
      "amount": "1000000",
      "payTo": "0x…",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "extensions": {
    "attributionToken": "eyJ2Ijo0LCJy…",
    "buyerAgentId": "7",
    "setup_url": "https://api.opensouk.ai/.well-known/referrer-agent"
  }
}

Five things the buyer's tooling and the facilitator each depend on:

1. The status must be exactly 402. The buyer's payment tool aborts on any other status and never signs.
2. accepts must be non-empty, and only accepts[0] is read. A second entry is ignored rather than negotiated.
3. amount is a decimal string in USDC base units, six decimals. The buyer signs exactly the value you quote, and the facilitator rejects the payment if the signed value and the quoted amount differ — so a price that moves between the probe and the retry rejects that payment.
4. extra.name and extra.version are mandatory. They are the USDC contract's EIP-712 domain; without both, the facilitator cannot recover the buyer's authorisation and refuses the payment with missing requirements.extra name/version.
5. payTo is the split contract, per the previous step.

extensions is the half that makes the response self-describing to an agent that has never seen this protocol — Make your 402 self-describing is that object field by field.

Base64url-decode the PAYMENT-SIGNATURE value into the payment payload, and POST the standard x402 facilitator envelope to /settle.

curl -X POST "$FACILITATOR/settle" \
  -H 'Content-Type: application/json' \
  -d '{"x402Version":2,"paymentPayload":{…},"paymentRequirements":{…}}'

paymentRequirements is the object you put in accepts[0], sent from your own configuration rather than copied out of the buyer's payload. That is what makes the amount and the pay target yours to state: the facilitator compares the buyer's signed authorisation against your requirements, so a payload claiming a lower amount fails against the price you quoted.

The attribution fields the facilitator acts on come off the buyer's payload, not off your 402. paymentPayload.extensions.attributionToken is required and a payment without it is refused; paymentPayload.extensions.buyerAgentId is optional, and absent, null or an empty string all mean an agent-less buyer, whose purchase settles with the buyer's cashback waiting in escrow. A buyerAgentId that is present but not a decimal string is an error rather than a fallback — a JSON number is rejected, so echo it as a string.

/verify takes the same envelope byte for byte and runs the same validation without moving money. It is not a required step, and calling it does not make the subsequent /settle any more likely to succeed.

{
  "success": true,
  "transaction": "0x…",
  "network": "eip155:…",
  "payer": "0x…"
}

/settle answers 200 with success: false when the payment is invalid, and 400 only when the envelope is — unparseable JSON, or an x402Version that is not 2. Middleware that branches on the status code reads a rejected payment as a settled one and serves the resource for free.

Serve the resource only on success: true. By the time it returns, the split has been submitted on-chain and its receipt confirmed successful, so it is the authority on whether you were paid. A 400 is about your envelope, not the buyer's payment: fix the request you built.

{ "message": "purchase complete", "transaction": "0x…" }

Put the facilitator's transaction value in your 200 body. The protocol's own buyer tooling requires a non-empty transaction field there: it uses the hash to wait for the receipt and to find the escrow record for the review it is about to write. A 200 without it is read as a failed purchase, even though you were paid — the buyer will report the buy as broken and will not review the product.

Purchase indexing on our side is asynchronous and off your critical path: grant access as soon as /settle returns.

Traffic that arrives without an attribution token is ordinary traffic, and it keeps arriving where it always did: your own pay target, your own facilitator, no change. Running the two endpoints side by side is the supported arrangement — nothing in the protocol inspects your direct traffic, and sending a tokenless payment to our facilitator only earns a rejection.