Skip to main content
Facilitator Service settles x402 payments in USDC after the buyer signs the authorization. It validates each signature, screens both parties, and submits the transfer through a Circle relayer.

​
Authentication

Facilitator Service requires a Circle API key to settle payments. If you don’t have one yet, create one in Circle Console. You can also start without an API key using the keyless trial, which authenticates with a seller proof instead. The trial covers fixed-amount payments only, with an allowance that applies until you settle with an API key. Usage-based payments always require an API key.

​
Roles

Every Facilitator Service payment involves three actors:
  • Buyer: an HTTP client, typically an AI agent, that signs a payment authorization to pay for a resource.
  • Seller: an HTTP resource server that asks for payment before returning a result, then calls Facilitator Service to settle the buyer’s authorization.
  • Facilitator: screens both parties, submits the USDC transfer through a Circle relayer, and pays settlement gas.

​
Supported buyer accounts

Facilitator Service accepts signatures from externally owned accounts (EOAs) and from deployed smart contract accounts through ERC-1271. Smart contract accounts that aren’t deployed yet (ERC-6492) are not supported. EOA signatures must use a v value of 27 or 28.

​
Payment schemes

Facilitator Service supports two x402 payment schemes:
  • exact payments charge a fixed amount per request. The buyer signs for that amount, and the seller settles it.
  • upto payments charge a variable amount per request. The buyer signs for a maximum, and the seller settles the actual amount after serving the request, from zero up to the maximum.

​
Comparison table

Use exact when every request has a fixed price. Use upto when you can’t know the price until the work is done, such as per-token LLM completions, metered compute, or bandwidth. For blockchain availability, see Supported networks.

​
Fixed-amount payments

Fixed-amount payments use the x402 exact scheme. The buyer signs an EIP-3009 authorization for a specific amount, and Facilitator Service submits a USDC transfer for that same amount.

​
Payment flow

  1. A buyer requests a paid resource from the seller’s API.
  2. The seller returns 402 Payment Required with the payment requirements.
  3. The buyer signs an EIP-3009 authorization offchain and retries the request.
  4. The seller sends the signed authorization to Facilitator Service using /settle.
  5. Facilitator Service screens both parties. If either fails, it refuses to settle. Otherwise, it submits the USDC transfer through a Circle relayer.
  6. Once confirmed, Facilitator Service returns the transaction hash to the seller, who fulfills the request.
Facilitator Service saves the payment record before broadcasting the transaction, so a retry with the same identifier always resolves to the same payment. This prevents double charges.

​
EIP-3009 authorization

Facilitator Service uses EIP-3009 as the payment primitive. The buyer signs a TransferWithAuthorization message offchain, and Facilitator Service submits it to the USDC contract on the payment’s blockchain to move USDC from buyer to seller. Before Facilitator Service submits the transaction, it validates the following:
  • That the buyer’s signature is valid
  • That the buyer has sufficient USDC balance
  • That the to address in the authorization matches the seller’s payTo
Then Facilitator Service calls transferWithAuthorization on the USDC contract.

​
Usage-based payments

Usage-based payments use the x402 upto scheme. The buyer signs a Permit2 authorization for a maximum amount, and the seller settles the actual amount after serving the request. Facilitator Service verifies the authorization against the maximum, then submits a USDC transfer for the actual charge.

​
Payment flow

  1. The seller returns 402 Payment Required with upto payment requirements. The amount is the most the seller may charge.
  2. The buyer signs a Permit2 authorization for that maximum and retries the request.
  3. The seller calls /verify with paymentRequirements.amount set to the maximum.
  4. The seller serves the request and works out the actual charge.
  5. The seller calls /settle with the same signed payload and paymentRequirements.amount set to the actual charge.
  6. Facilitator Service screens both parties and submits the transfer for the actual amount through the x402 Permit2 proxy contract.
Facilitator Service does not meter usage. It accepts the amount you send to /settle as long as it doesn’t exceed the signed maximum.

​
Buyer prerequisites

The Permit2 contract moves USDC on the buyer’s behalf, so the buyer must first grant Permit2 spending power over their USDC. The buyer can grant it with an onchain approval, or with a signed EIP-2612 permit that the seller attaches to each payment. For how to set this up, see Set up a Permit2 allowance.

​
Permit2 authorization

The buyer signs an EIP-712 PermitWitnessTransferFrom message under the Permit2 domain. The witness binds the authorization to the seller’s payTo and to a specific Circle facilitator wallet. Only that wallet can submit the settlement. To retrieve facilitator addresses, use the Get supported x402 payment kinds endpoint.

​
Repeat settlements

Each upto authorization settles at most once per Circle account. A repeat /settle call with the same authorization returns the original payment rather than a second charge, even if the amount differs. The only way to charge the buyer again is a new authorization. A /settle call conflicts with an existing payment when:
  • A different Circle account already settled the authorization.
  • The same account sends the authorization or payment-identifier again with different request details, such as resource.url or maxTimeoutSeconds.
  • A different buyer’s payment already uses the same payment-identifier.
  • A different signed authorization reuses the same Permit2 nonce for the same buyer.
For the specific HTTP 409 reason strings, see Facilitator Service errors.