API reference
API reference
The PATH HTTP surface — conventions, base URLs, headers, and every endpoint.
The reference implementation's HTTP surface. Any conforming operator exposes the same shapes at its own base URL, which you read from its discovery document.
Base URLs
Both mount the same routers. Use the second when a proxy between you and the operator strips unfamiliar headers and you need the train pinned in the path.
Headers
Sent
| Header | Required | Purpose |
|---|---|---|
Path-Version | Recommended | Pin the dated API version. Unpinned means latest |
Path-Protocol-Version | Optional | The protocol version you were built against |
Path-Idempotency-Key | On creation | Replaying with the same key returns the original |
Path-Key-Id | Authenticated calls | Your credential's key id |
Path-Timestamp | Authenticated calls | RFC 3339, inside the freshness window |
Path-Signature | Authenticated calls | See Authentication |
Returned
| Header | Meaning |
|---|---|
Path-Version | The version that served this response |
Path-Version-Pinned | false means you did not pin. In production, a defect waiting for a date |
Path-Protocol-Version | The protocol version of any signed object in the body |
Path-Request-Id | Quote this in support conversations |
Which routes need a credential
| Routes | |
|---|---|
| Public | Discovery, keys, GET /requests/{ref}, GET /receipts/{ref}, GET /resolver/{key}, POST /receipts/verify |
| Member credential | Everything else |
The public set is not an afterthought. A wallet with no relationship to an operator has to be able to read a payment request, verify a receipt and resolve a destination it was given — otherwise "any conforming wallet can pay this" is false.
Endpoints
| Method | Path | |
|---|---|---|
GET | /.well-known/path-configuration | Discovery |
GET | /.well-known/path-keys | Discovery |
POST | /sonar/lookup | SONAR |
POST | /sonar/lookup/batch | SONAR |
POST | /sonar/confirm | SONAR |
GET | /resolver/{key} | RESOLVER |
POST | /finder | FINDER |
POST | /subjects | Subjects |
POST | /identifiers | Subjects |
POST | /subjects/{id}/withdraw | Subjects |
POST GET | /addresses | Addresses |
POST | /addresses/{id}/rotate | Addresses |
POST | /addresses/{id}/revoke | Addresses |
PUT | /addresses/{id}/standing-intent | Addresses |
POST GET | /requests | Requests |
POST | /requests/{ref}/revoke · /paid | Requests |
POST GET | /checkout/sessions | Checkout |
POST GET | /receipts | Receipts |
POST | /receipts/verify | Receipts |
Conventions
Amounts are decimal strings: "5000", "12.50". Never floats — binary floats cannot represent
0.1, and a payment system that rounds loses money in a direction someone eventually notices.
Times are RFC 3339 in UTC.
Errors all share one envelope.
Unknown fields are preserved. Reserved fields round-trip untouched. Dropping unknown fields is the most common way to break forward compatibility, and it fails silently.