PayAI Developer Portal

Start here to charge for a request, pay for one, or discover payment-enabled resources. Public read endpoints and core payment operations are described at https://payai.network/openapi.json; scheme-specific guides remain authoritative for channel operations.

Base URL

https://facilitator.payai.network

Configure compatible x402 middleware to use that host. Supported testnets use the same facilitator base URL; select the intended network explicitly. The Echo Merchant offers demo payment endpoints and advertises test-payment refunds. Start on a testnet and review its terms before using real funds.

Endpoints

Method	Path	Operation	What it does
GET	`/health`	`getHealth`	Liveness probe
GET	`/supported`	`getSupportedPaymentKinds`	List supported payment kinds
GET	`/verify`	`describeVerifyEndpoint`	Describe the verify endpoint
POST	`/verify`	`verifyPayment`	Verify a signed x402 payment
GET	`/settle`	`describeSettleEndpoint`	Describe the settle endpoint
POST	`/settle`	`settlePayment`	Settle a verified x402 payment on-chain
GET	`/discovery/resources`	`listDiscoveryResources`	List x402-payable resources in the PayAI Bazaar
GET	`/discovery/stats`	`getDiscoveryStats`	Get aggregate PayAI Bazaar statistics

Core request/response envelopes and example failure reasons are in the OpenAPI 3.1 description. Consult the selected scheme's guide for its complete lifecycle and validation rules.

Authentication

Ordinary exact payments can use the available free tier without merchant credentials. Every batch-settlement verification and settlement request requires merchant authentication, including the first request. Send Authorization: Bearer <jwt>, using a short-lived Ed25519 (EdDSA) JWT signed with your merchant API key secret; never send the raw secret as the bearer token. Keep the private key server-side. Public reads need no token; authenticating GET /supported can select an account-specific fee payer. See https://docs.payai.network/x402/facilitators/authentication and https://docs.payai.network/x402/facilitators/pricing.

Authorization: Bearer <jwt>

Create merchant credentials at https://merchant.payai.network. The API key ID and private key secret are inputs to signing, not a token to paste into an HTTP header.

Error model

Application verification errors use isValid, invalidReason and invalidMessage; settlement errors use success, errorReason and errorMessage, with transaction, network and payer when available. Edge failures, timeouts and lost responses may not contain this JSON shape. Check status, content type and body together, handle unknown reason codes, and do not infer a settlement verdict from HTTP status alone.

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

Branch on known invalidReason / errorReason values and retain unknown reasons for investigation. The message is for humans and may carry field-level validation detail.

settlement_pending means the outcome is unresolved, not a payment failure or success. The transaction field can be empty; an empty field is not proof that nothing was broadcast. Preserve the original payment payload, requirements, receipts and any transaction identifier. Reconcile the same operation with backoff, following the selected scheme's recovery rules; do not create a fresh authorization just because a response was lost. duplicate_settlement can indicate an in-flight operation or a replay marker. Recovery records have bounded, scheme-dependent retention, so keep your own evidence and check chain state if the record is unavailable. See https://docs.payai.network/x402/facilitators/capacity-and-limits and the batch recovery guide at https://docs.payai.network/x402/servers/batch-settlement.

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 the currently advertised combinations. This is capability discovery, not a promise of advance deprecation notice. Pin and test your SDK/protocol version and review the relevant scheme guide before changing it.

Rate limits

Edge admission limits and account-wide batch limits are distinct. Limiting can return 429 or 503; inspect the body and respect Retry-After when present. Back off rather than assuming a fixed header budget or treating configured limits as measured settlement throughput. See https://docs.payai.network/x402/facilitators/capacity-and-limits.

Machine-readable surfaces

OpenAPI 3.1 description
llms.txt — when to use PayAI and how to call it
llms-full.txt — the whole site as one document
MCP server — Streamable HTTP, no authentication, searches the PayAI docs corpus. Also at /.well-known/mcp.
MCP manifest and AI catalog
API catalog (RFC 9727)

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 Bazaar catalog, including last-recorded payment terms and seller-declared schemas when available. Entries can persist without refresh; a listing is not proof of current availability, successful settlement or service quality. Inspect lastUpdated, then obtain current requirements from the provider before paying. See https://docs.payai.network/x402/facilitators/bazaar.

GET https://facilitator.payai.network/discovery/stats returns cached catalog and settlement summaries. Preserve their definitions and windows; do not treat a catalog count as paying-customer attribution.