PayAI Logo

PayAI Developer Portal

Everything needed to charge for a request, pay for one, or find something worth paying for. The API is public, unauthenticated for reads, and described in full at https://payai.network/openapi.json.

Base URL

https://facilitator.payai.network

Point x402 middleware or an x402 client at that host. There is no separate sandbox: testnet networks are served from the same endpoints, and the Echo Merchant is a live merchant that returns HTTP 402 so you can exercise a real payment for free.

Endpoints

MethodPathOperationWhat it does
GET/healthgetHealthLiveness probe
GET/supportedgetSupportedPaymentKindsList supported payment kinds
GET/verifydescribeVerifyEndpointDescribe the verify endpoint
POST/verifyverifyPaymentVerify a signed x402 payment
GET/settledescribeSettleEndpointDescribe the settle endpoint
POST/settlesettlePaymentSettle a verified x402 payment on-chain
GET/discovery/resourceslistDiscoveryResourcesList x402-payable resources in the PayAI Bazaar
GET/discovery/statsgetDiscoveryStatsGet aggregate PayAI Bazaar statistics

The full request and response schemas, including every documented failure reason, are in the OpenAPI 3.1 description.

Authentication

Read endpoints need none. POST /verify and POST /settle accept an optional bearer token:

Authorization: Bearer <api-key>

The key affects credit accounting, dedicated throughput lanes, and usage analytics — not access. Without one you are served on the free tier. Create a key at https://merchant.payai.network.

Error model

Errors are JSON on every status, including 4xx and 5xx, because a client that has already signed a payment needs to know precisely what happened.

  • POST /verify returns { isValid: false, invalidReason, invalidMessage }
  • POST /settle returns { success: false, errorReason, errorMessage, transaction, network, payer }

Branch on invalidReason / errorReason — these are stable across releases. The message is for humans and carries field-level validation detail.

One reason deserves special handling: settlement_pending means the settlement outran its response budget and is still in flight. It is not a failure. The response carries the broadcast transaction hash; re-submit the identical request to poll for the real outcome, and treat duplicate_settlement on that poll as "still working". Settlement is idempotent per payment, so retrying cannot double-charge.

Versioning and deprecation

The facilitator is versioned by the x402 protocol version it speaks, not by a URL path segment. Requests carry x402Version (1 or 2); both are served from the same endpoints, so you pin a version by what you send.

  • x402 v1 uses short network names — base, solana
  • x402 v2 uses CAIP-2 identifiers — eip155:8453, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp

Call GET https://facilitator.payai.network/supported to see which combinations are live. A payment kind is withdrawn from that list before the endpoints stop accepting it, so polling /supported gives advance notice of a removal. Breaking changes arrive as a new x402Version.

Rate limits

Throughput is limited per client at the edge; exceeding it returns HTTP 429. The facilitator does not currently emit RateLimit response headers, so back off on the status code rather than on a header budget.

Machine-readable surfaces

Every page on this site also serves Markdown — send Accept: text/markdown or append .md to the path.

Quickstarts

Accept payments:

Make payments:

Prefer no SDK? The manual flows spell out the raw HTTP exchange: TypeScript · Python.

Discovery

GET https://facilitator.payai.network/discovery/resources returns the PayAI Bazaar: every resource currently accepting x402 payments, with the payment terms needed to call it and, where the seller published them, input and output schemas. GET https://facilitator.payai.network/discovery/stats returns catalog size, settlement counts, and per-network volume.

More from PayAI