curl --request POST \
  --url https://api.circle.com/v1/facilitator/x402/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "resource": {
      "url": "https://api.example.com/premium",
      "description": "Premium report",
      "mimeType": "application/json"
    },
    "accepted": {
      "scheme": "exact",
      "network": "eip155:5042002",
      "amount": "1000000",
      "asset": "0x3600000000000000000000000000000000000000",
      "payTo": "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A",
      "maxTimeoutSeconds": 12,
      "extra": {
        "name": "USDC",
        "version": "2",
        "assetTransferMethod": "eip3009"
      }
    },
    "payload": {
      "signature": "0x15e13cbd896cdf88f30cb826b2e79b97a35280b2ab459a1f50cd64ee48034e2849e7445b14feadcc3d1bb2868b41e8cf7997b623daa73872509c7027194765311b",
      "authorization": {
        "from": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
        "to": "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A",
        "value": "1000000",
        "validAfter": "0",
        "validBefore": "1791400000",
        "nonce": "0x4d3f8a2c9b1e7f60d5a4c3b2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2"
      }
    },
    "extensions": {
      "payment-identifier": {
        "info": {
          "required": true,
          "id": "pay_5f0d3c1a9b7e4d2c"
        }
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:5042002",
    "amount": "1000000",
    "asset": "0x3600000000000000000000000000000000000000",
    "payTo": "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A",
    "maxTimeoutSeconds": 12,
    "extra": {
      "name": "USDC",
      "version": "2",
      "assetTransferMethod": "eip3009"
    }
  }
}
'

{
  "success": true,
  "payer": "0x9aE2...",
  "transaction": "0x6f9e1d...",
  "network": "eip155:5042002",
  "amount": "1000000",
  "errorReason": "invalid_exact_evm_payload_signature",
  "extensions": {
    "settlement-status": {
      "status": "pending",
      "paymentId": "5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa",
      "statusUrl": "https://api.circle.com/v1/facilitator/x402/status/5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa"
    }
  }
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

Settle an x402 payment

Verifies the buyer’s signed authorization, screens both parties, records the payment, and submits the USDC transfer onchain. For exact, the transfer is an EIP-3009 authorization submitted through a Circle relayer. For upto, it is a Permit2 transfer submitted from witness.facilitator.

A settlement outcome always uses HTTP 200. There is no pending status code. 4xx and 5xx responses mean the request was rejected or failed before settlement, with no outcome. Pending is not failure: settlement continues, and Get payment status reconciles the outcome. Do not fulfill on pending.

Pass a payment-identifier extension to scope idempotency to your seller account. Without an identifier, each retry must reuse the exact signed buyer authorization, or it’s treated as a new charge.

For upto, paymentRequirements.amount is the actual charge, from 0 up to the maximum the buyer signed. Each authorization settles at most once, and a request for it from a different seller returns 409 credential_bound_elsewhere. The buyer grants Permit2 allowance either by approving Permit2 onchain or by signing an eip2612GasSponsoring permit the facilitator submits with the settlement.

Example signatures come from a public test key. Never fund it.

POST

facilitator

x402

settle

curl --request POST \
  --url https://api.circle.com/v1/facilitator/x402/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "resource": {
      "url": "https://api.example.com/premium",
      "description": "Premium report",
      "mimeType": "application/json"
    },
    "accepted": {
      "scheme": "exact",
      "network": "eip155:5042002",
      "amount": "1000000",
      "asset": "0x3600000000000000000000000000000000000000",
      "payTo": "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A",
      "maxTimeoutSeconds": 12,
      "extra": {
        "name": "USDC",
        "version": "2",
        "assetTransferMethod": "eip3009"
      }
    },
    "payload": {
      "signature": "0x15e13cbd896cdf88f30cb826b2e79b97a35280b2ab459a1f50cd64ee48034e2849e7445b14feadcc3d1bb2868b41e8cf7997b623daa73872509c7027194765311b",
      "authorization": {
        "from": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
        "to": "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A",
        "value": "1000000",
        "validAfter": "0",
        "validBefore": "1791400000",
        "nonce": "0x4d3f8a2c9b1e7f60d5a4c3b2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2"
      }
    },
    "extensions": {
      "payment-identifier": {
        "info": {
          "required": true,
          "id": "pay_5f0d3c1a9b7e4d2c"
        }
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:5042002",
    "amount": "1000000",
    "asset": "0x3600000000000000000000000000000000000000",
    "payTo": "0x7c3ea945Fc4253255d8260fc18c2dee3D8C5dD3A",
    "maxTimeoutSeconds": 12,
    "extra": {
      "name": "USDC",
      "version": "2",
      "assetTransferMethod": "eip3009"
    }
  }
}
'

{
  "success": true,
  "payer": "0x9aE2...",
  "transaction": "0x6f9e1d...",
  "network": "eip155:5042002",
  "amount": "1000000",
  "errorReason": "invalid_exact_evm_payload_signature",
  "extensions": {
    "settlement-status": {
      "status": "pending",
      "paymentId": "5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa",
      "statusUrl": "https://api.circle.com/v1/facilitator/x402/status/5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa"
    }
  }
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer token authentication with a Circle API key. Use this for production settlement. Settling with an API key also binds the payTo to your Circle account, which ends the keyless trial allowance.

Body

application/json

x402Version

enum<integer>

required

x402 protocol version. Facilitator Service supports version 2.

Available options:

2

paymentPayload

object

required

x402 v2 payment payload. Includes the payment terms the buyer accepted and the signed authorization for the USDC transfer: an EIP-3009 authorization for exact, or a Permit2 authorization for upto.

For upto, the payload sent to /settle must match the payload sent to /verify. The seller can only vary paymentRequirements.amount between calls.

Show child attributes

paymentRequirements

object

required

Payment terms the seller advertises for an x402 resource. Facilitator Service validates that the buyer's authorization matches these requirements.

Show child attributes

Response

The settlement outcome.

A terminal result means settlement resolved within the HTTP wait window. An unresolved result returns success: false with errorReason: settlement_pending and a paymentId.

A repeat request from the same seller for the same upto authorization returns the original payment, even with a different amount, when the other request terms match (such as resource.url, maxTimeoutSeconds, extra.name, and extra.version). Otherwise it returns 409 payment_identifier_conflict.

success

boolean

required

Whether the transfer settled onchain within the wait window. Check the settlement-status extension to distinguish failed from pending.

Example:

true

payer

string

required

Buyer address recovered from the signed authorization.

Example:

"0x9aE2..."

transaction

string

required

Transaction hash on terminal success. Empty string when settlement is still pending or failed before submission. Also empty for an upto settlement of 0, which completes without an onchain transaction.

Example:

"0x6f9e1d..."

network

string

required

CAIP-2 network identifier for the settled payment.

Example:

"eip155:5042002"

amount

string

Amount in atomic USDC units. For upto, this is the amount actually settled, not the maximum the buyer signed.

Example:

"1000000"

errorReason

enum<string>

Reason code. Present whenever success is false, either because the payment failed terminally or because the outcome was unresolved at the wait deadline (settlement_pending).

Available options:

settlement_pending,

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,

invalid_permit2_spender,

invalid_permit2_recipient_mismatch,

permit2_token_mismatch,

invalid_upto_evm_payload_settlement_exceeds_amount,

permit2_not_yet_valid,

permit2_deadline_expired,

upto_facilitator_mismatch,

invalid_permit2_signature,

permit2_invalid_nonce,

invalid_eip2612_extension_format,

eip2612_from_mismatch,

eip2612_asset_mismatch,

eip2612_spender_not_permit2,

eip2612_deadline_expired,

permit2_2612_amount_mismatch,

permit2_simulation_failed

Example:

"invalid_exact_evm_payload_signature"

extensions

object

x402 extensions. Facilitator Service returns a settlement-status extension only after a payment has been recorded: on settlement_pending and on terminal failures that have a paymentId. When present, the extension carries status, paymentId, and statusUrl.

Pre-recording validation failures (invalid_x402_version, unsupported_scheme, invalid_network, invalid_payment_requirements, invalid_payload, and the other request-validation errorReason values) return success: false with an errorReason and no extension, because there is no paymentId to reconcile.

Settlement returns no poll hints.

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"
  }
}