# 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](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](https://x402.payai.network) is a live merchant that returns HTTP 402 so you can exercise a real payment for free.

## 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 |

The full request and response schemas, including every documented failure reason, are in the [OpenAPI 3.1 description](https://payai.network/openapi.json).

## 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](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

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

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

## Quickstarts

Accept payments:

- [Express](https://docs.payai.network/x402/servers/typescript/express) · [Hono](https://docs.payai.network/x402/servers/typescript/hono) · [Next.js](https://docs.payai.network/x402/servers/typescript/nextjs)
- [FastAPI](https://docs.payai.network/x402/servers/python/fastapi) · [Flask](https://docs.payai.network/x402/servers/python/flask)
- [Gin](https://docs.payai.network/x402/servers/go/gin)

Make payments:

- [Axios](https://docs.payai.network/x402/clients/typescript/axios) · [Fetch](https://docs.payai.network/x402/clients/typescript/fetch)
- [httpx](https://docs.payai.network/x402/clients/python/httpx) · [requests](https://docs.payai.network/x402/clients/python/requests)
- [Go net/http](https://docs.payai.network/x402/clients/go/http)

Prefer no SDK? The manual flows spell out the raw HTTP exchange: [TypeScript](https://docs.payai.network/x402/clients/typescript/manual-flow) · [Python](https://docs.payai.network/x402/clients/python/manual-flow).

## 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

- Documentation: https://docs.payai.network
- OpenAPI description: https://payai.network/openapi.json
- Facilitator API: https://facilitator.payai.network
- Agent guide: https://payai.network/llms.txt
- Blog: https://blog.payai.network
- GitHub: https://github.com/PayAINetwork
- Support: info@payai.network