API Reference

The facilitator exposes three endpoints:

POST /verify
POST /settle
GET /supported

POST /verify

Verifies a payment authorization without executing it on-chain.

Authentication: Optional API key, if configured.

Request body (v2 exact example):


{
  "x402Version": 2,
  "paymentPayload": {
    "accepted": {
      "scheme": "exact",
      "network": "eip155:11155111"
    },
    "payload": {
      "authorization": {
        "from": "0x354b5cBeEaE7751f2055BfC2d9d78556aD2E1c61",
        "to": "0x9a4e1A0BC77639Fdce69df88E1DF1D589e454811",
        "value": "1000",
        "validAfter": "1767140522",
        "validBefore": "1767141422",
        "nonce": "0x2454c8d9065ebdffd65226693448da75f3c1227fec5ed9c3d0043892cd593f84"
      },
      "signature": "0xdf3cac4be24a317e07b4374b5f1198fc9760c9849fe80f1383755c2d541c4e042b7b9f79aee3b67c236130127299609998a4b31be154963091dd1920a374b0201b"
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:11155111",
    "asset": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
    "payTo": "0x9a4e1A0BC77639Fdce69df88E1DF1D589e454811",
    "amount": "1000",
    "maxTimeoutSeconds": 300,
    "extra": {
      "name": "USDC",
      "version": "2"
    }
  }
}

Response (valid):


{
  "scheme": "exact",
  "network": "eip155:11155111",
  "isValid": true,
  "payer": "0x354b5cBeEaE7751f2055BfC2d9d78556aD2E1c61"
}

Response (invalid):


{
  "scheme": "exact",
  "network": "eip155:11155111",
  "isValid": false,
  "invalidReason": "invalid_authorization_signature"
}

Errors:

400 Bad Request: Invalid request body
401 Unauthorized: Missing or invalid API key
500 Internal Server Error: Server error during verification

POST /settle

Settles a payment authorization by executing it on-chain.

Authentication: Optional API key, if configured.

Request body is the same format as /verify.

Response (success):


{
  "scheme": "exact",
  "network": "eip155:11155111",
  "success": true,
  "transaction": "0xb6b3f3770f2a24ab064a0801922616886acd9058ace6a29be00bdf1d7b8289b6"
}

Response (failed):


{
  "scheme": "exact",
  "network": "eip155:11155111",
  "success": false,
  "errorReason": "invalid_authorization_signature"
}

Errors:

400 Bad Request: Invalid request body
401 Unauthorized: Missing or invalid API key
500 Internal Server Error: Server error during settlement

GET /supported

Returns supported x402 versions, schemes, and networks based on configuration.

Response:


{
  "kinds": [
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "sepolia"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:11155111"
    }
  ]
}