Docs
Capabilities and amounts
The shared vocabulary for what is accepted, what is owed and what arrived — Asset, Capability, Amount, Fee, RailReference, Party.
LIVE — PIP-0006, served on
Path-Version: 2026-10-04.genesis, signed protocol_version 0.2.0. Objects without grammar stay in the 0.3 shape, signed protocol_version 0.1.0, with amount a decimal string. See Versioning.
ADDRESS, REQUEST and SETTLEMENT describe value with the same types. A reader that parses a
capability in accepts parses the same capability in a receipt.
| Type | Used in |
|---|---|
| Asset | inside Capability and Amount, route.legs[] |
| Capability | accepts[] (ADDRESS, REQUEST), via (instruction, receipt) |
| Amount | amount (request, instruction), sent / received (receipt), limits, fees, quotes |
| Fee | accepts[].fees (request), fees (receipt) |
| RailReference | rail_references[] (receipt) |
| Party | payee, payer |
Capability
One rail and one asset. Several assets or several rails are several capabilities.
{
"rail": "blockchain",
"chain": { "slug": "base", "caip2": "eip155:8453", "evm": { "chain_id": 8453 } },
"asset_type": "token",
"asset_code": "USDC",
"standard": "erc20",
"contract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
}{ "rail": "sepa-inst", "asset_type": "fiat", "asset_code": "EUR" }An optional instrument names the real-world claim a representation stands for.
PIP-0012 defines it. This version omits the field.
| Field | Rule |
|---|---|
rail | Required. An identifier from the rail register. |
chain | Required when rail is blockchain, absent otherwise. At least one of slug, caip2, evm.chain_id; evm only on EVM chains. name is display only. |
asset_type | fiat or token. A reader ignores an entry with a value it does not know. |
asset_code | ISO 4217 for fiat, the token symbol otherwise. Upper case. |
standard | Tokens: native, erc20, spl, trc20, tip20, stellar-asset, sui-coin, jetton, or another value from the chain register. |
contract | Tokens, unless standard is native. Canonical form of the chain register. |
decimals | Tokens absent from the chain register only. |
fiat is valid only off-chain, token only on blockchain. On a single-currency rail,
asset_code is that rail's currency.
On an address, a capability may also carry limits (min_single, max_single, as Amounts) and
reference_required. On a request it may carry fees and a quote. See
PIP-0008 and PIP-0010.
Amount
{ "value": "5000", "asset_type": "fiat", "asset_code": "USD" }value is a decimal string in major units — no exponent, no leading zeros, no trailing zeros after
the point, never a JSON number. It has no more decimal places than the asset allows: "5000.001"
USD is invalid, because USD has two minor units.
Fee
{
"kind": "operator",
"amount": { "value": "25", "asset_type": "fiat", "asset_code": "USD" },
"paid_by": "payer"
}kind: network, operator, fx. paid_by: payer, payee.
RailReference
{ "type": "end_to_end_id", "value": "E1234567820260909100412abcdef" }type comes from the rail's rail_reference_types. index locates one transfer inside a
transaction that holds several.
Party
{ "member": "member-a", "address": "path:4a91c2f7e8d3" }Never a name, an account or a clear identifier.
References
| Field | Meaning |
|---|---|
reference | Public identifier of a PATH object |
order_reference | The merchant's reference |
payment_reference | What the payer attaches to the rail transfer, from a payment instruction |
rail_references | Identifiers issued by the rail |
account_ref | Internal to the member, never published |
Canonical form
Absent fields are omitted, never null. asset_code is upper case. EVM contracts are lower case.
chain.name is excluded from commitments. The order of accepts is the receiver's preference and
is never sorted. Serialisation is JCS (RFC 8785).
Objects in this grammar carry grammar: 2. An object without grammar is in the 0.3 shape.