API reference
API reference
The PATH HTTP surface — conventions, base URLs, headers, and every endpoint.
The reference implementation's HTTP surface. The shapes are the protocol. The paths, except the three below, are the operator's, published as absolute URLs in its discovery document.
Fixed by the protocol: GET /.well-known/path-configuration, GET /.well-known/path-keys, and
GET /path/{reference}.
Reference implementation
This repository mounts the routes in the table at /api/path/v1. The same routers are mounted at
/api/path/genesis/v1 when the train is pinned in the path, for a proxy that strips unfamiliar
headers.
A client of another operator does not assume either prefix. It calls endpoints from discovery.
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 the client did not pin a version |
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 /instructions/{ref}, GET /resolver/{key}, GET /commitments/{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 |
GET | /commitments/{key} | RESOLVER |
POST | /finder | FINDER |
POST | /subjects | Subjects |
POST | /identifiers | Subjects |
POST | /subjects/{id}/withdraw | Subjects |
POST GET | /attestations | Subjects |
POST GET | /ownership-bindings | Subjects |
POST GET | /addresses | Addresses |
POST | /addresses/{id}/rotate · /revoke | Addresses |
PUT | /addresses/{id}/standing-intent | Addresses |
POST GET | /instructions | Instructions |
POST GET | /requests | Requests |
POST | /requests/{ref}/revoke · /paid | Requests |
POST GET | /checkout/sessions | Checkout |
POST | /checkout/sessions/{ref}/attempt · /complete · /revoke | Checkout |
POST GET | /connect/connections | Connections |
POST GET | /connect/delegations | Connections |
POST GET | /receipts | Receipts |
POST | /receipts/verify | Receipts |
Conventions
Amounts are Amount objects: { "value": "5000", "asset_type": "fiat", "asset_code": "USD" }.
value is a decimal string. Never a float — binary floats cannot represent 0.1.
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.