Verify an x402 payment

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

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.

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

Verification result

isValid

boolean

required

Whether the payload passed every check 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"