> ## Documentation Index > Fetch the complete documentation index at: https://developers.circle.com/llms.txt > Use this file to discover all available pages before exploring further. # Settle an x402 payment > Settles an x402 payment. Facilitator Service validates the buyer's EIP-3009 authorization, screens both parties, records the payment, and submits the USDC transfer through a Circle relayer. Returns a terminal result (HTTP 200) if settlement resolves within the HTTP wait window. Returns HTTP 202 with a `paymentId` when settlement is still in flight at the wait deadline. See [Get payment status](/api-reference/agent-stack/facilitator-service/get-payment-status) to poll a pending payment. Include a `payment-identifier` extension in the request body for idempotency scoped to your seller account. Retries with the same identifier converge on the same payment. Without an identifier, a retry must reuse the exact same signed buyer authorization or the retry is treated as a new charge. ## OpenAPI ````yaml openapi/facilitator-service.yaml post /v1/facilitator/x402/settle openapi: 3.0.3 info: title: Facilitator Service version: 1.0.0 description: > Facilitator Service is Circle's hosted x402 facilitator. Sellers call Facilitator Service to verify and settle x402 payments in USDC on Arc, Base, and Polygon PoS without operating their own relayer, gas wallet, or sanctions screening. Facilitator Service implements the x402 v2 `exact` scheme and settles USDC through EIP-3009 authorizations. servers: - url: https://api.circle.com description: Production - url: https://api-sandbox.circle.com description: Sandbox security: - CircleApiKey: [] - FacilitatorSellerProof: [] tags: - name: Payments description: | x402 payment verification, settlement, and status. - name: Seller accounts description: | Seller account binding to a Circle account for API key authentication. - name: Supported payment kinds description: | x402 payment kinds and extensions Facilitator Service accepts. paths: /v1/facilitator/x402/settle: post: tags: - Payments summary: Settle an x402 payment description: > Settles an x402 payment. Facilitator Service validates the buyer's EIP-3009 authorization, screens both parties, records the payment, and submits the USDC transfer through a Circle relayer. Returns a terminal result (HTTP 200) if settlement resolves within the HTTP wait window. Returns HTTP 202 with a `paymentId` when settlement is still in flight at the wait deadline. See [Get payment status](/api-reference/agent-stack/facilitator-service/get-payment-status) to poll a pending payment. Include a `payment-identifier` extension in the request body for idempotency scoped to your seller account. Retries with the same identifier converge on the same payment. Without an identifier, a retry must reuse the exact same signed buyer authorization or the retry is treated as a new charge. operationId: SettlePayment requestBody: required: true content: application/json: schema: type: object required: - x402Version - paymentPayload - paymentRequirements properties: x402Version: type: integer enum: - 2 description: >- x402 protocol version. Facilitator Service supports version 2. paymentPayload: $ref: '#/components/schemas/PaymentPayload' paymentRequirements: $ref: '#/components/schemas/PaymentRequirements' responses: '200': description: Terminal settlement result content: application/json: schema: $ref: '#/components/schemas/SettleResponse' '202': description: Pending settlement result content: application/json: schema: $ref: '#/components/schemas/SettleResponse' '400': description: Malformed request body or mixed authentication modes. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: | Missing or invalid authentication. Returned when neither a valid Circle API key nor a valid seller proof is present, when the seller proof does not match the payment's `network` and `payTo`, or when the seller proof's nonce has been replayed with a different digest. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: | Forbidden by policy. Returned when the keyless trial allowance is exhausted (`registration_required`) or the settlement amount is below the configured minimum. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: | Idempotency conflict. Returned when the buyer credential is already bound to another payment, when the supplied `payment-identifier` matches a payment whose request contents differ from the current request, or when a different payer reuses a credential to which it was originally bound. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '415': description: Unsupported content encoding. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: A required service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - CircleApiKey: [] - FacilitatorSellerProof: [] components: schemas: PaymentPayload: type: object description: > x402 v2 payment payload. Includes the payment terms the buyer accepted and the signed EIP-3009 authorization that authorizes the USDC transfer. required: - x402Version - accepted - payload properties: x402Version: type: integer enum: - 2 description: x402 protocol version. Facilitator Service supports version 2. resource: $ref: '#/components/schemas/ResourceInfo' accepted: $ref: '#/components/schemas/PaymentRequirements' payload: type: object required: - signature - authorization properties: signature: type: string description: | Buyer's EIP-3009 signature over the `TransferWithAuthorization` typed data. Recovered against the USDC contract's EIP-712 domain for the payment's network. example: 0x... authorization: $ref: '#/components/schemas/EIP3009Authorization' extensions: type: object description: > Optional x402 extensions. Facilitator Service recognizes `payment-identifier` for seller-scoped idempotency. The value carries an `info` object with `required` and `id` fields; `id` must be 16 to 128 characters from `[A-Za-z0-9_-]`. additionalProperties: true example: payment-identifier: info: required: true id: pay_5f0d3c1a9b7e4d2c PaymentRequirements: type: object description: > Payment terms the seller advertises for an x402 resource. Facilitator Service validates that the buyer's authorization matches these requirements. required: - scheme - network - amount - asset - payTo - maxTimeoutSeconds properties: scheme: type: string enum: - exact description: Payment scheme. Facilitator Service supports `exact`. network: type: string description: > CAIP-2 network identifier. Must match one of the blockchains Facilitator Service supports. See the Supported networks reference. example: eip155:5042002 amount: type: string description: | Payment amount in atomic USDC units. USDC uses 6 decimals, so `1000000` equals 1 USDC. example: '1000000' asset: type: string description: | USDC contract address on the target network. example: '0x3600000000000000000000000000000000000000' payTo: type: string description: The seller's payout address on the target network. example: '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a' maxTimeoutSeconds: type: integer description: > Maximum time in seconds Facilitator Service may wait for the settlement to reach a terminal state before returning a pending response. example: 12 extra: type: object description: > Scheme-specific parameters. For the `exact` scheme with EIP-3009, Facilitator Service expects `name`, `version`, and `assetTransferMethod`. additionalProperties: true example: name: USDC version: '2' assetTransferMethod: eip3009 SettleResponse: type: object required: - success - payer - transaction - network properties: success: type: boolean description: > Whether the transfer settled onchain within the wait window. Check the `settlement-status` extension to distinguish failed from pending. example: true payer: type: string description: | Buyer address recovered from the signed authorization. example: 0x9aE2... transaction: type: string description: > Transaction hash on terminal success. Empty string when settlement is still pending or failed before submission. example: 0x6f9e1d... network: type: string description: CAIP-2 network identifier for the settled payment. example: eip155:5042002 amount: type: string description: Amount in atomic USDC units. example: '1000000' errorReason: type: string description: > Terminal failure code. Present when `success` is false and the payment reached a terminal failed state. Omitted on pending responses. enum: - invalid_x402_version - unsupported_scheme - invalid_network - invalid_payment_requirements - invalid_payload - invalid_exact_evm_payload_recipient_mismatch - invalid_exact_evm_payload_authorization_value_mismatch - invalid_exact_evm_payload_authorization_valid_after - invalid_exact_evm_payload_authorization_valid_before - invalid_exact_evm_payload_signature - invalid_transaction_state - insufficient_funds example: invalid_exact_evm_payload_signature extensions: type: object description: | x402 extensions. On pending responses, Facilitator Service returns a `settlement-status` extension with `paymentId`, `statusUrl`, `retryAfterMs`, and `expiresAt`. additionalProperties: true example: settlement-status: status: pending paymentId: 5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa statusUrl: >- https://api.circle.com/v1/facilitator/x402/status/5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa retryAfterMs: 1000 expiresAt: '2026-06-11T22:31:07Z' ErrorResponse: type: object required: - code - message properties: code: type: integer description: HTTP status code echoed in the body for programmatic handling. example: 403 message: type: string description: >- Human-readable summary of the error, suitable for display to end users. example: Registration required to continue settling on this address errors: type: array description: Per-issue reason codes. items: type: object required: - reason properties: reason: type: string description: | Machine-readable reason code. enum: - registration_required - authorization_expired - payment_identifier_conflict - credential_bound_elsewhere - credential_payer_conflict example: registration_required ResourceInfo: type: object description: | Optional metadata about the resource the buyer is paying for. properties: url: type: string description: URL of the paid resource. example: https://api.example.com/premium description: type: string description: Human-readable description of the resource. example: Premium report mimeType: type: string description: MIME type the resource returns. example: application/json EIP3009Authorization: type: object description: > EIP-3009 `TransferWithAuthorization` message the buyer signed. Facilitator Service submits this authorization to the USDC contract to move funds from `from` to `to`. required: - from - to - value - validAfter - validBefore - nonce properties: from: type: string description: Buyer's address (source of the USDC transfer). example: 0x9aE2... to: type: string description: > Recipient address. Must equal `paymentRequirements.payTo` for Facilitator Service to accept the authorization. example: '0x7c3eA945Fc4253255D8260fC18C2deE3D8c5DD3a' value: type: string description: | Transfer amount in atomic USDC units. Must equal `paymentRequirements.amount`. example: '1000000' validAfter: type: string description: Unix timestamp before which the authorization is not valid. example: '0' validBefore: type: string description: Unix timestamp after which the authorization is no longer valid. example: '1781308800' nonce: type: string description: | Unique 32-byte value that binds this authorization to one specific transfer. Reusing a nonce that already settled returns `invalid_transaction_state`. example: 0x4d3f... securitySchemes: CircleApiKey: type: http scheme: bearer description: > Bearer token authentication with a Circle API key. Use this for production settlement after claiming your Facilitator Service seller account. FacilitatorSellerProof: type: apiKey in: header name: Facilitator-Seller-Proof description: | Base64url-encoded envelope carrying an EIP-712 signature that proves the caller controls the `payTo` address. Use this for the keyless trial before claiming your Facilitator Service seller account. ````