Facilitator API
The x402 Facilitator API enables payment verification and settlement for your protected endpoints.
Base URL
https://facilitator.agentokratia.com
Authentication
| Endpoint | Auth Required |
|---|
GET /api/supported | None (public) |
POST /api/verify | API Key |
POST /api/settle | API Key |
Authorization: Bearer x402_xxx
Get your API key from the Dashboard. API keys are tied to your receiving wallet and work on all supported EVM networks. Endpoints
| Method | Endpoint | Description |
|---|
| GET | /api/supported | List supported payment schemes |
| POST | /api/verify | Verify a payment payload |
| POST | /api/settle | Execute payment settlement |
GET /api/supported
Returns supported payment schemes. No authentication required.
curl https://facilitator.agentokratia.com/api/supported
{
"kinds": [
{
"x402Version": 2,
"scheme": "exact",
"network": "eip155:8453",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"extra": { "name": "USD Coin", "version": "2" }
},
{
"x402Version": 2,
"scheme": "escrow",
"network": "eip155:8453",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"extra": {
"facilitator": "0x...",
"escrowContract": "0x...",
"tokenCollector": "0x...",
"minDeposit": "5000000",
"maxDeposit": "100000000"
}
}
],
"extensions": ["agentokratia"],
"signers": {
"eip155:8453": ["0x..."]
}
}
POST /api/verify
Verify a payment payload without executing it. Use this to validate before serving content.
curl -X POST https://facilitator.agentokratia.com/api/verify \
-H "Authorization: Bearer x402_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"paymentPayload": {
"x402Version": 2,
"accepted": {
"scheme": "escrow",
"network": "eip155:84532",
"amount": "10000",
"payTo": "0x1234..."
},
"payload": {
"session": { "id": "session-id", "token": "session-token" },
"requestId": "uuid",
"amount": "10000"
}
},
"paymentRequirements": {
"scheme": "escrow",
"network": "eip155:84532",
"amount": "10000",
"payTo": "0x1234..."
}
}'
{
"isValid": true,
"payer": "0xAbCdEf..."
}
{
"isValid": false,
"invalidReason": "insufficient_balance"
}
POST /api/settle
Execute a payment. Creates a new session or charges an existing one.
curl -X POST https://facilitator.agentokratia.com/api/settle \
-H "Authorization: Bearer x402_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"paymentPayload": { ... },
"paymentRequirements": { ... }
}'
{
"success": true,
"payer": "0xAbCdEf...",
"transaction": "0xabcd1234...",
"network": "eip155:84532",
"session": {
"id": "session-abc123",
"token": "secret-token-SAVE-THIS",
"balance": "9990000",
"expiresAt": 1735686000
}
}
session.token is only returned once when creating a new session. Store it immediately - it cannot be retrieved again.
{
"success": true,
"payer": "0xAbCdEf...",
"transaction": "session-abc123",
"network": "eip155:84532",
"session": {
"id": "session-abc123",
"balance": "9980000"
}
}
Rate Limits
| Endpoint | Limit |
|---|
/api/supported | 100/min per IP |
/api/verify, /api/settle | 1000/min per API key |
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000
Error Responses
{
"error": "Human-readable message",
"reason": "machine_readable_code"
}
| Code | HTTP | Description |
|---|
invalid_signature | 400 | ERC-3009 signature failed |
invalid_session_token | 400 | Session token mismatch |
session_expired | 400 | Session has expired |
insufficient_balance | 400 | Session balance too low |
unauthorized | 401 | Missing/invalid API key |
rate_limit_exceeded | 429 | Too many requests |
SDK
npm install @agentokratia/x402-escrow
