curl --request POST \
  --url https://api.circle.com/v1/facilitator/x402/verify \
  --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"
    }
  }
}
'

{
  "isValid": true,
  "payer": "0x9aE2...",
  "invalidReason": "invalid_exact_evm_payload_signature"
}

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

Verify an x402 payment

Validates an x402 payment payload without creating a payment, consuming keyless trial usage, or submitting anything onchain. Use this endpoint for verification purposes. To settle a payment, see Settle an x402 payment.

For the upto scheme, paymentRequirements.amount must equal the maximum the buyer signed, and Facilitator Service checks the buyer’s USDC balance and Permit2 allowance against that maximum. If the allowance is short, an eip2612GasSponsoring permit in paymentPayload.extensions can stand in for an onchain approval.

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

POST

facilitator

x402

verify

curl --request POST \
  --url https://api.circle.com/v1/facilitator/x402/verify \
  --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"
    }
  }
}
'

{
  "isValid": true,
  "payer": "0x9aE2...",
  "invalidReason": "invalid_exact_evm_payload_signature"
}

{
  "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.

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

Verification result

isValid

boolean

required

Whether the payload passed every check Facilitator Service runs before submission.

Example:

true

payer

string

required

Buyer address recovered from the signed authorization. Always rendered, including on invalid results, so callers can correlate.

Example:

"0x9aE2..."

invalidReason

enum<string>

Reason code. Present when isValid is false.

Available options:

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,

permit2_amount_mismatch,

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"