PATH ADDRESS
API reference
Payment instructions
Where to send one payment, on one capability — a short-lived ADDRESS object, not a claim and not a proof.
A resolver answer says what an address accepts. It does not give a
destination. POST /instructions does, for one capability, for a few minutes.
An instruction issued for a request needs no credential: the request is payable by whoever holds it. An instruction issued for an address alone takes a member credential, and the issuance records which member obtained it.
POST /instructions
{
"request": "7fk2m9pq3vx8",
"via": { "rail": "book", "asset_type": "fiat", "asset_code": "USD" }
}{
"type": "path.instruction",
"reference": "in_3k91c2f7e8d3",
"issuer": "example-member",
"payee": { "member": "example-member", "address": "path:4a91c2f7e8d3" },
"request": "7fk2m9pq3vx8",
"intent_version": 3,
"via": { "rail": "book", "asset_type": "fiat", "asset_code": "USD" },
"beneficiary": { "format": "path_address", "value": "path:4a91c2f7e8d3" },
"payment_reference": null,
"amount": { "value": "5000", "asset_type": "fiat", "asset_code": "USD" },
"single_use": false,
"status": "open",
"expires_at": "2026-09-09T10:30:00Z",
"grammar": 2,
"protocol_version": "0.2.0",
"signed_at": "2026-09-09T10:00:00Z",
"kid": "op_example_2026_01",
"signature": "…"
}| Field | Notes |
|---|---|
request or address | Exactly one. address is the opaque path:… value |
via | One entry of the accepts in force. A reserved rail has no beneficiary format, and no instruction is issued on it |
Lifecycle: open → used | expired | revoked.
GET /instructions/{reference}
Public. 410 once the instruction is no longer open.
| Code | Status | Meaning |
|---|---|---|
path.instruction.used | 410 | Already used |
path.instruction.expired | 410 | Past expires_at |
path.instruction.revoked | 410 | Withdrawn by the issuer |
path.core.not_found | 404 | No such reference |
POST /instructions/{reference}/revoke
Requires the issuer's credential.