T402 v2.8.0—Stellar support + 39 packages across 45 networks→
ReferenceFacilitator API

Facilitator API Reference

The T402 Facilitator API provides payment verification and on-chain settlement services. The public facilitator is available at https://facilitator.t402.io.

Base URL

https://facilitator.t402.io

Authentication

The public facilitator does not require authentication for basic usage. For rate limit increases or enterprise features, contact the T402 team.

Endpoints

GET /health

Health check endpoint for liveness probes.

Response

{
  "status": "ok"
}

GET /ready

Readiness check endpoint. Returns 200 when the service is ready to accept requests.

Response

{
  "status": "ready",
  "checks": {
    "redis": "ok",
    "rpc": "ok"
  }
}

GET /metrics

Prometheus metrics endpoint for monitoring.

Response: Prometheus text format

GET /supported

Returns the supported networks, schemes, and signers.

Response

{
  "kinds": [
    {
      "t402Version": 2,
      "scheme": "exact",
      "network": "eip155:8453"
    },
    {
      "t402Version": 2,
      "scheme": "exact",
      "network": "ton:mainnet"
    }
  ],
  "extensions": [],
  "signers": {
    "eip155:*": ["0xC88f67e776f16DcFBf42e6bDda1B82604448899B"],
    "ton:*": ["EQDjv9CUEJ__D_3-3J4trQtqVklMBiNoGVSf3Fu6AaDGkEUe"]
  }
}

Response Fields

FieldTypeDescription
kindsarrayList of supported scheme/network combinations
kinds[].t402VersionnumberProtocol version supported (2 for v2)
kinds[].schemestringPayment scheme (e.g., exact, upto)
kinds[].networkstringCAIP-2 network identifier
extensionsarrayExtension identifiers the facilitator has implemented
signersobjectMap of CAIP-2 patterns (e.g., eip155:*) to signer addresses

POST /verify

Verify a signed payment authorization without executing settlement.

Request Body

{
  "paymentPayload": {
    "t402Version": 2,
    "resource": {
      "url": "https://api.example.com/premium",
      "description": "Premium API access",
      "mimeType": "application/json"
    },
    "accepted": {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "1000000",
      "asset": "0x6C96dE32CEa08842dcc4058c14d3aaAD7Fa41dee",
      "payTo": "0xRecipientAddress",
      "maxTimeoutSeconds": 600,
      "extra": {
        "name": "USDT0",
        "version": "2"
      }
    },
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0xPayerAddress",
        "to": "0xRecipientAddress",
        "value": "1000000",
        "validAfter": "0",
        "validBefore": "1706745600",
        "nonce": "0x..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "1000000",
    "asset": "0x6C96dE32CEa08842dcc4058c14d3aaAD7Fa41dee",
    "payTo": "0xRecipientAddress",
    "maxTimeoutSeconds": 600,
    "extra": {
      "name": "USDT0",
      "version": "2"
    }
  }
}

Response (Success)

{
  "isValid": true,
  "payer": "0xPayerAddress"
}

Response (Invalid)

{
  "isValid": false,
  "invalidReason": "Signature verification failed",
  "payer": "0xPayerAddress"
}

Response Fields

FieldTypeDescription
isValidbooleanWhether the payment authorization is valid
invalidReasonstringReason for invalidity (omitted if valid)
payerstringAddress of the payer’s wallet

POST /settle

Execute on-chain settlement for a verified payment.

Headers

HeaderRequiredDescription
Idempotency-KeyRecommendedUnique key (max 64 chars, alphanumeric/hyphens) to prevent duplicate settlements

Request Body

{
  "paymentPayload": {
    "t402Version": 2,
    "resource": {
      "url": "https://api.example.com/premium",
      "description": "Premium API access",
      "mimeType": "application/json"
    },
    "accepted": {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "1000000",
      "asset": "0x6C96dE32CEa08842dcc4058c14d3aaAD7Fa41dee",
      "payTo": "0xRecipientAddress",
      "maxTimeoutSeconds": 600,
      "extra": {
        "name": "USDT0",
        "version": "2"
      }
    },
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0xPayerAddress",
        "to": "0xRecipientAddress",
        "value": "1000000",
        "validAfter": "0",
        "validBefore": "1706745600",
        "nonce": "0x..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "1000000",
    "asset": "0x6C96dE32CEa08842dcc4058c14d3aaAD7Fa41dee",
    "payTo": "0xRecipientAddress",
    "maxTimeoutSeconds": 600,
    "extra": {
      "name": "USDT0",
      "version": "2"
    }
  }
}

Response (Success)

{
  "success": true,
  "transaction": "0x...",
  "network": "eip155:8453",
  "payer": "0xPayerAddress"
}

Response (Failure)

{
  "success": false,
  "errorReason": "Insufficient balance",
  "transaction": "",
  "network": "eip155:8453",
  "payer": "0xPayerAddress"
}

Response Fields

FieldTypeDescription
successbooleanWhether settlement was successful
transactionstringBlockchain transaction hash (empty string if failed)
networkstringNetwork where settlement occurred
payerstringAddress of the payer’s wallet
errorReasonstringReason for failure (omitted if successful)
⚠️

Idempotency: Always use the Idempotency-Key header for settlement requests to prevent double payments in case of network errors or retries.

Error Responses

All endpoints return structured error responses:

{
  "code": "INVALID_REQUEST",
  "message": "Invalid request body"
}

Error Codes

CodeHTTP StatusDescription
INVALID_REQUEST400Malformed request body
INVALID_IDEMPOTENCY_KEY400Invalid idempotency key format
VERIFICATION_FAILED500Payment verification failed
SETTLEMENT_FAILED500On-chain settlement failed
REQUEST_IN_PROGRESS409Duplicate request still processing
PAYLOAD_MISMATCH409Payload doesn’t match previous request with same idempotency key
PREVIOUS_REQUEST_FAILED409Previous request with this key failed
IDEMPOTENCY_UNAVAILABLE503Idempotency service unavailable

Rate Limiting

The public facilitator implements rate limiting:

TierRequests/MinuteDescription
Default60Standard public access
Authenticated1000With API key

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1706745660

Supported Networks

EVM Networks

NetworkChain IDCAIP-2Facilitator Address
Ethereum1eip155:10xC88f67e776f16DcFBf42e6bDda1B82604448899B
Base8453eip155:84530xC88f67e776f16DcFBf42e6bDda1B82604448899B
Arbitrum42161eip155:421610xC88f67e776f16DcFBf42e6bDda1B82604448899B
Optimism10eip155:100xC88f67e776f16DcFBf42e6bDda1B82604448899B
Ink57073eip155:570730xC88f67e776f16DcFBf42e6bDda1B82604448899B
Berachain80094eip155:800940xC88f67e776f16DcFBf42e6bDda1B82604448899B

Non-EVM Networks

NetworkCAIP-2Facilitator Address
Solanasolana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp8GGtWHRQ1wz5gDKE2KXZLktqzcfV1CBqSbeUZjA7hoWL
TONton:mainnetEQDjv9CUEJ__D_3-3J4trQtqVklMBiNoGVSf3Fu6AaDGkEUe
TRONtron:mainnetTT1MqNNj2k5qdGA6nrrCodW6oyHbbAreQ5
NEARnear:mainnetfacilitator.t402.near
Stacksstacks:1SP36B1B191JTQAZTRKKWRN7J0YHHM41W9P9P7EPR5
Cosmos (Noble)cosmos:noble-1noble1ejc2c2gvk46h7kyulx9fus85vdpq0zdjwkfav0
Aptosaptos:1Verification only (exact-direct)
Tezostezos:NetXdQprcVkpaWUVerification only (exact-direct)
Polkadotpolkadot:68d56f15f85d3136970ec16946040bc1Verification only (exact-direct)

Code Examples

# Check supported networks
curl https://facilitator.t402.io/supported
 
# Verify payment
curl -X POST https://facilitator.t402.io/verify \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {...},
    "paymentRequirements": {...}
  }'
 
# Settle payment
curl -X POST https://facilitator.t402.io/settle \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "paymentPayload": {...},
    "paymentRequirements": {...}
  }'

Self-Hosting

You can run your own facilitator for greater control and privacy. See the Deployment Guide for instructions.

# Docker
docker run -p 8080:8080 ghcr.io/t402-io/facilitator:latest
 
# Environment variables
export EVM_PRIVATE_KEY=0x...
export TON_MNEMONIC="word1 word2 ..."
export REDIS_URL=redis://localhost:6379

Related

OverviewOpenAPI Specification