API Reference

REST API endpoints for direct integration with the X402 Facilitator.

Base URL

https://x402apes-production.up.railway.app

GET

/health

Check the health status of the facilitator service.

Response 200

{
  "status": "ok",
  "redis": "connected",
  "rpc": "connected",
  "openrouter": "connected",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

GET

/supported

Get information about supported networks, tokens, and payment schemes.

Response 200

{
  "networks": [
    {
      "id": 33139,
      "name": "ApeChain",
      "rpcUrl": "https://apechain.calderachain.xyz/http",
      "nativeCurrency": {
        "name": "ApeCoin",
        "symbol": "APE",
        "decimals": 18
      }
    }
  ],
  "schemes": ["eip2612-permit"],
  "tokens": ["*"]
}

GET

/stats

Get facilitator statistics including transaction counts and volume.

Response 200

{
  "totalTransactions": 150,
  "totalVolumeUSDC": 1500.50,
  "daily": {
    "2024-01-15": { "txs": 10, "volume": 100.00 }
  },
  "recent": [
    {
      "hash": "0x...",
      "timestamp": "2024-01-15T10:30:00.000Z",
      "value": "1000000",
      "token": "0xF1815bd50389c46847f0Bda824eC8da914045D14",
      "recipient": "0x..."
    }
  ]
}

POST

/verify

Verify a payment permit is valid before settlement. Checks signature, balance, nonce, and recipient.

Request Body

{
  "paymentPayload": {
    "scheme": "eip2612-permit",
    "network": "33139",
    "payload": {
      "owner": "0xPayerAddress...",
      "spender": "0xe24a8dbf205ee116c991f60686f778a2337a844f",
      "value": "1000000",
      "deadline": "1735689600",
      "nonce": "0",
      "v": 27,
      "r": "0x...",
      "s": "0x..."
    }
  },
  "paymentRequirements": {
    "tokenAddress": "0xF1815bd50389c46847f0Bda824eC8da914045D14",
    "recipient": "0xb913df2fefc5021d0636f4e9c04a59bdd2a19d8d",
    "amount": "1000000"
  }
}

Response 200 - Success

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

Status	Error	Description
400	Invalid request format	Request body validation failed
400	Invalid recipient	Recipient must be facilitator address
401	Signature verification failed	Invalid permit signature
402	Insufficient funds	Payer does not have enough balance
409	Nonce already used	Replay attack prevented

POST

/settle

Execute payment settlement on-chain. Submits the permit to the settlement contract.

Request Body

Same structure as /verify.

Response 200 - Success

{
  "success": true,
  "txHash": "0x1234567890abcdef...",
  "settledAt": "2024-01-15T10:30:00.000Z"
}

Error Responses

Same error codes as /verify, plus:

Status	Error	Description
500	Settlement failed	On-chain transaction reverted

Using cURL

Example requests using cURL:

Check Health

curl https://x402apes-production.up.railway.app/health

Get Supported Info

curl https://x402apes-production.up.railway.app/supported

Verify Payment

curl -X POST https://x402apes-production.up.railway.app/verify \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": { ... },
    "paymentRequirements": { ... }
  }'

Tip: Use the SDK

For most use cases, we recommend using the @x402apechain/sdk which handles permit signing, error handling, and type safety automatically.