T402 v2.8.0—Stellar support + 39 packages across 45 networks→
ReferenceOpenAPI Specification

OpenAPI Specification

The T402 Facilitator API follows the OpenAPI 3.1 specification for standardized API documentation.

Specification File

The OpenAPI specification is available at:

Using the Specification

Import into Postman

  1. Open Postman
  2. Click Import > Link
  3. Enter: https://docs.t402.io/api/openapi.yaml
  4. Click Import

Generate Client Code

Use OpenAPI Generator to generate client libraries:

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g
 
# Generate TypeScript client
openapi-generator-cli generate \
  -i https://docs.t402.io/api/openapi.yaml \
  -g typescript-fetch \
  -o ./generated/client
 
# Generate Python client
openapi-generator-cli generate \
  -i https://docs.t402.io/api/openapi.yaml \
  -g python \
  -o ./generated/python-client
 
# Generate Go client
openapi-generator-cli generate \
  -i https://docs.t402.io/api/openapi.yaml \
  -g go \
  -o ./generated/go-client

Swagger UI

You can view the interactive API documentation using Swagger UI:

# Using Docker
docker run -p 8080:8080 \
  -e SWAGGER_JSON_URL=https://docs.t402.io/api/openapi.yaml \
  swaggerapi/swagger-ui
 
# Open http://localhost:8080

API Overview

Base URL

https://facilitator.t402.io

Authentication

API key authentication is optional by default. When required, include the key in the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
  https://facilitator.t402.io/supported

Rate Limiting

EndpointLimit
/verify1000/min
/settle1000/min
/supported1000/min
/health, /readyUnlimited
/metricsUnlimited

Endpoints Summary

MethodPathDescription
GET/healthLiveness probe
GET/readyReadiness probe with dependency checks
GET/infoAPI information and available endpoints
GET/supportedList supported networks, schemes, and signers
POST/verifyVerify a payment authorization signature
POST/settleExecute on-chain payment settlement
GET/metricsPrometheus metrics

Advanced Endpoints (v1)

Streaming payments and intent-based routing require database configuration:

MethodPathDescription
POST/v1/stream/openOpen a payment stream
POST/v1/stream/updateUpdate stream with new amount
POST/v1/stream/closeClose and settle a stream
GET/v1/stream/:idGet stream status
POST/v1/intentCreate a payment intent
GET/v1/intent/:idGet intent status
POST/v1/intent/:id/routeSelect a route
POST/v1/intent/:id/executeExecute the intent

Request Examples

Verify Payment

curl -X POST https://facilitator.t402.io/verify \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {
      "t402Version": 2,
      "scheme": "exact",
      "network": "eip155:8453",
      "payload": {
        "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f5b1A1",
        "to": "0xC88f67e776f16DcFBf42e6bDda1B82604448899B",
        "value": "1000000",
        "validAfter": 0,
        "validBefore": 1735689600,
        "nonce": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "signature": "0x..."
      }
    },
    "paymentRequirements": {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xC88f67e776f16DcFBf42e6bDda1B82604448899B",
      "maxAmountRequired": "1000000"
    }
  }'

Settle Payment

curl -X POST https://facilitator.t402.io/settle \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{
    "paymentPayload": { ... },
    "paymentRequirements": { ... }
  }'

Get Supported Networks

curl https://facilitator.t402.io/supported

Response:

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

Error Codes

CodeDescription
INVALID_REQUESTRequest body is malformed or missing required fields
VERIFICATION_FAILEDPayment signature verification failed
SETTLEMENT_FAILEDOn-chain settlement transaction failed
REQUEST_IN_PROGRESSDuplicate request with same idempotency key is processing
PAYLOAD_MISMATCHPayload differs from previous request with same idempotency key
INVALID_IDEMPOTENCY_KEYIdempotency key format is invalid
IDEMPOTENCY_UNAVAILABLEIdempotency service is temporarily unavailable
PREVIOUS_REQUEST_FAILEDPrevious request with this key failed

Related

Facilitator API@t402/core