PATH Protocol

Why

A payment request is a claim: what is owed, to whom, until when. In 0.3 its amount is a bare string beside currency, its accepts is free-form and independent of the payee's address, its fees is one block for every capability, and paid names no receipt. This PIP restates the request in the vocabulary of PIP-0006.

The object

{
  "type": "path.request",
  "reference": "7fk2m9pq3vx8",
  "issuer": "member-a",
  "payee": { "member": "member-a", "address": "path:4a91c2f7e8d3" },
  "amount": { "value": "5000", "asset_type": "fiat", "asset_code": "USD" },
  "accepts": [
    {
      "rail": "book",
      "asset_type": "fiat",
      "asset_code": "USD",
      "fees": []
    },
    {
      "rail": "blockchain",
      "chain": { "slug": "base", "caip2": "eip155:8453" },
      "asset_type": "token",
      "asset_code": "USDC",
      "standard": "erc20",
      "contract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "quote": {
        "amount": { "value": "7.62", "asset_type": "token", "asset_code": "USDC" },
        "rate": "0.001524",
        "source": "operator_quote",
        "expires_at": "2026-10-04T18:05:00Z"
      },
      "fees": [
        {
          "kind": "network",
          "amount": { "value": "0.01", "asset_type": "token", "asset_code": "USDC" },
          "paid_by": "payer"
        }
      ]
    }
  ],
  "intent_version": 4,
  "order_reference": "ord_10482",
  "status": "created",
  "settled_by": [],
  "expires_at": "2026-10-10T10:00:00Z",
  "grammar": 2
}

Rules

Field	Rule
`payee`	Present. `payee.address` is present when the request is issued against an address.
`amount`	An Amount, or `null` when the payer chooses. `currency` is not part of this grammar.
`accepts[]`	Capabilities, frozen at issue. When `payee.address` is present, each entry exists in the standing intent named by `intent_version`. Otherwise each entry is checked against the registers ([PIP-0007](/pips/0007)).
`accepts[].fees`	Fees on this capability, as Fee objects. The request-level `fees` is not part of this grammar.
`accepts[].quote`	Required when the capability's asset differs from `amount`'s. States what the payer sends on this capability, at what rate, until `expires_at`. Without a valid quote, a wallet does not show an amount for that capability.
`status`	`created`, `paid`, `expired`, `revoked`. Unchanged.
`settled_by`	References of receipts in `settled` that cover this request. `paid` requires at least one.

A request carries no title, description or memo. The issuer's verified name comes from the member register.

Amounts received

Partial payments remain reserved. Until a PIP specifies them:

The amounts of receipts in settled_by are compared in the asset of amount, using each receipt's received.
A request moves to paid when the receipts it lists cover amount. Below that, it stays created, and settled_by lists what arrived.
An amount above amount moves the request to paid. Refund of the excess is reserved.
A request with amount: null moves to paid on its first settled receipt.

Checkout sessions

A session carries the request's amount and accepts in this grammar.

Change	From	To
Withdrawn by the merchant	`cancelled`	`revoked`
Attempts	a counter and the last `payer_member`	one record per attempt: member, time, capability chosen, instruction obtained

completed still means the wallet handed the payer back. It is not paid, and it does not move the request.

Payment

A wallet that pays a request obtains a payment instruction for one entry of accepts, sends, and receives or retrieves the receipt. The request lists that receipt in settled_by.

Compatibility

Breaking for readers of amount, currency, accepts and fees on path.request and path.checkout, and for readers of checkout cancelled. Requests signed in the 0.3 shape are served as signed.