PATH Protocol

Why

An issuer may need a payment shown a set way: an amount in its customers' currency with the settlement asset not named, a stablecoin shown as such, an amount in EUR with its XOF equivalent beside it. The payer's wallet often belongs to another member. This PIP gives the issuer a field to state those rules, gives a wallet a profile to declare that it honours them, and sets what every wallet shows regardless.

The block

An optional display on path.address and path.request, inside the signed object. A path.checkout carries the display of its request.

{
  "type": "path.request",
  "amount": { "value": "12500", "asset_type": "fiat", "asset_code": "XOF" },
  "accepts": [ "…" ],
  "display": {
    "primary": "amount",
    "settlement": "hidden",
    "equivalence": "EUR"
  }
}

Field	Values	Rule
`primary`	`amount` · `quote`	The headline figure: what is owed (`12 500 XOF`), or what is sent on the chosen entry (`19.05 USDC`). Fixed amount only. Default `amount`. On an entry with no `quote`, `amount`.
`settlement`	`hidden` · `asset` · `asset_and_chain`	How far the asset that moves is named. Default `asset_and_chain`.
`equivalence`	an asset code, or `null`	A second figure in this asset, at the payer wallet's own rate, labelled indicative. Never the headline, never a term. Omitted when it is the headline's asset.
`entry`	`{ asset_code, locked }`	Open amount and address only. The asset the payer types in, which is the asset of an entry of `accepts`, and whether the payer may switch it.

Absent, the block reads with the defaults. A value a reader does not know is read as the default for that field. An entry whose asset is in no entry of accepts is ignored.

Which capabilities the payer may pick from is not display: it is accepts, whose order states preference (PIP-0008).

Open amounts across assets

On an open amount the payer chooses the figure, and no debt is stated. The payer types in the entry asset. On an entry in another asset, the wallet converts at its own rate and shows the figure that will be sent. The bounds that apply are those of the chosen entry, in its asset (PIP-0015). The receipt states what was received.

A quote signed by the issuer remains the rule for a fixed amount (PIP-0010).

The floor

Whatever display says, a wallet shows before the payer confirms:

What leaves the payer's own account, in that account's unit, fees included.
The verified name of the payee.

No issuer rule lifts the floor. settlement: hidden applies when the payer funds from an account in another asset. A payer drawing on an account in the asset that moves sees that asset named.

Signature and commitment

display is signed with the object that carries it. It is not a term: the address commitment does not cover it, and setting it on an address creates no new intent version. The terms — accepts, limits, the amount — are unchanged by any display rule.

Who must honour it

PATH defines the vocabulary and the floor. Whether a wallet must honour display is set by the network's rulebook.

A member whose wallet honours it declares PATH-INTEROP.Display in its discovery document.
A network may require the profile of its members.
An issuer that knows the payer's member reads its discovery document to learn whether the rules apply.

Mapping from an operator model

Operator rule	Here
Fiat amount, settlement asset not shown	`primary: amount`, `settlement: hidden`
Fiat amount with the settlement asset, chain shown or not	`primary: amount`, `settlement: asset` or `asset_and_chain`
Settlement asset shown as the amount	`primary: quote`, `settlement: asset_and_chain`
Choice among tokens and chains	`accepts` with several entries
Live FX beside the amount	`equivalence`
Entry currency locked	`entry.locked: true`
Amount locked	`amount` present
Minimum and maximum	`accepts[].limits` ([PIP-0015](/pips/0015))
Which balance a payer's own transfer draws from	Out of scope: it stays within one member

Interface

POST /requests takes display.
PUT /addresses/{id}/display sets or clears it on an address.
The SDK's resolveDisplay(object, { via, funding }) returns the rules with the defaults and the floor applied.

Compatibility

Additive. An object without display reads as before.

Display rules

Why