Accept Payments
Gateway overview
Understand the local payment gateway shape before writing a spec.
pay server start <spec.yml> loads a provider spec and starts an HTTP gateway.
You build a normal HTTP API. The pay gateway sits in front of it, returns HTTP 402 challenges for metered endpoints, verifies payment credentials, and forwards only verified paid traffic to the upstream API.
Agent summary
- Metered endpoints return 402 before payment.
- Paid retries are verified before the upstream response is delivered.
- Free endpoints pass through without payment.
- Requests not listed in
endpoints[]are not exposed by the gateway. - The YAML configures the gateway; it does not run the upstream API unless
routing.type: respondis used for a demo.
Components
| Component | Responsibility |
|---|---|
pay CLI or MCP server | Sends the user or agent request, handles HTTP 402 challenges, and retries with payment proof. |
| Payment gateway | Public paid surface started with pay server start <spec.yml>. |
| Provider spec | YAML source of truth for routing, endpoint allowlists, pricing, recipients, currencies, network, and signer settings. |
| Upstream API | Your existing HTTP service behind the gateway. |
| Pay Skills Registry | Provider metadata that lets agents discover the gateway URL and endpoints. |
Runtime shape
client -> pay gateway: request
gateway -> client: 402 Payment Required
client -> wallet: local authorization
client -> gateway: retry with proof
gateway -> upstream: allowed paid request
gateway -> client: responseCommands
pay server scaffold provider.yml
pay --sandbox server start provider.yml --debuggerDemo gateway
pay --sandbox server demoThe demo scaffolds ./pay-demo.yaml, starts a local sandbox gateway, and exposes several metered endpoints plus a free health endpoint. Call one metered endpoint from another terminal:
pay --sandbox curl -i http://127.0.0.1:1402/api/v1/reports/usageLook for the HTTP status and payment-receipt header in the response. Decode receipt fields only when the response actually includes them.