Facilitator API Reference

Base URL: https://x402.agentstrail.ai

GET /health

Returns liveness status and fee payer SOL balance.

Response:

{
  "status": "ok",
  "feePayerAddress": "AbC123...",
  "feePayerBalance": "0.2341 SOL",
  "lowBalance": false,
  "networks": ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG"],
  "timestamp": "2026-04-06T12:00:00.000Z"
}

status is "degraded" when fee payer SOL is below the configured threshold.

GET /supported

Returns the payment kinds and networks this facilitator supports. Resource servers call this on startup to configure their middleware.

Response:

{
  "schemes": ["exact"],
  "networks": ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],
  "extensions": []
}

POST /verify

Verifies a signed client payment without submitting to the blockchain.

Request body:

{
  "paymentPayload": { ... },
  "paymentRequirements": { ... }
}

Response (success):

{ "valid": true }

Response (failure):

{ "valid": false, "reason": "policy:amount_below_min" }

POST /settle

Verifies and submits the Solana transaction. Returns a settlement proof.

Request body: same shape as /verify

Response (success):

{
  "success": true,
  "txid": "5KtPn1LGuxhFdmMVVS3yRJm6q5CqUVBfBPULFN7fjBW4..."
}

Rate limit: 30 requests/min per IP.

Policy Error Codes

Code	Meaning
`policy:network_not_allowed`	Network is not in the facilitator's allowlist
`policy:asset_not_allowed`	Token mint is not USDC
`policy:amount_below_min`	Payment is below the 0.01 USDC minimum
`policy:recipient_not_allowed`	`payTo` is not in the allowed recipients list
`policy:transaction_missing`	No transaction in payload
`policy:program_not_allowed`	Transaction calls an unknown Solana program
`policy:compute_units_exceeded`	Transaction CU limit too high
`policy:priority_fee_exceeded`	Priority fee too high
`policy:too_many_transfers`	More than one token transfer in tx
`policy:rate_limit_exceeded`	Too many requests from this IP