API endpoints
Version 1 of Penni's public API at https://api.pennipay.eu: config, verify, settle, discovery and health.
All calls go to https://api.pennipay.eu. Calls that need a key authenticate with Authorization: Bearer <API key>. Bodies are JSON.
| Endpoint | Key | What it does |
|---|---|---|
GET /v1/sites/:id/config?path= | yes | Price and ready-made x402 accepts for one path. Without path: every price rule in routes. Includes mode, ready, problems and blocked. Cacheable for 60 seconds, with ETags. |
POST /v1/x402/verify | yes | Checks a signed payment without moving money. Body: { x402Version, paymentPayload, paymentRequirements }. Free. |
POST /v1/x402/settle | yes | Submits the payment on-chain and returns the transaction. Same body. Costs €0.002 in credits when it succeeds on a mainnet. |
GET /v1/x402/supported | no | Schemes, networks and tokens the facilitator handles, and its extensions. |
GET /v1/x402/discovery/resources | no | The x402 Bazaar catalog of opted-in sites. limit (1–100), offset, network, payTo. |
GET /v1/x402/discovery/search?query= | no | Searches the catalog. |
GET /v1/x402/discovery/price?url= | no | What one URL of an opted-in site costs, with its accepts. |
GET /v1/health | no | { "ok": true } while the API is up. |
Config response
| Field | Meaning |
|---|---|
mode | test, live or mixed: see test and live. |
ready, problems | Whether the site can take payments now, and if not, why: no wallet, no tokens, out of credits. |
blocked | Out of credits with the site set to block: answer 503. |
match | With ?path=: the matching rule's pattern, price and free. |
accepts | The payment options for the 402, ready to copy. |
extensions | With ?path=: the rule's discovery metadata, as bazaar. |
Versioning
New fields and endpoints are added within /v1, so ignore fields you don't know. A breaking change ships as /v2, and /v1 keeps working next to it until we announce its end well in advance.