@piprail/sdk 2.15.0 → 2.16.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as Caip2, X as X402AcceptEntry, y as X402AnyAccept, B as X402ExactAcceptEntry, e as ExactPaymentPayloadAny, q as SignedReceipt, x as VerifyResult, I as X402UptoAcceptEntry, o as Permit2UptoPaymentPayload, w as SpendSummary, z as X402Challenge, F as X402Receipt, S as SettleOutcome, v as SpendStore, t as SpendLedger, u as SpendRecord, p as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-uFtXlIHY.cjs';
-export { E as EXT_OFFER_RECEIPT, b as EXT_PAYMENT_IDENTIFIER, c as ExactAuthorizationWire, d as ExactPaymentPayload, H as HEADER_REQUIRED, f as HEADER_RESPONSE, g as HEADER_RESPONSE_V1, h as HEADER_SIGNATURE, i as HEADER_SIGNATURE_V1, j as ParsedExactPayment, k as ParsedUptoPayment, l as Permit2Authorization, m as Permit2PaymentPayload, n as Permit2UptoAuthorization, r as SpendAssetTotal, s as SpendDenomTotal, D as X402PaymentSignature, G as X402ResourceObject, J as buildChallengeHeader, K as buildExactSignatureHeader, L as buildPaymentIdentifierAdvertisement, M as buildReceiptExtension, N as buildReceiptHeader, O as buildSignatureHeader, Q as buildUptoSignatureHeader, R as decodeBase64Json, T as memorySpendStore, U as parseChallenge, W as parseExactObject, Y as parseExactPaymentHeader, Z as parseReceipt, _ as parseReceiptExtension, $ as parseSettleResponse, a0 as parseSignatureHeader, a1 as parseSignatureObject, a2 as parseUptoObject, a3 as parseUptoPaymentHeader, a4 as pickAccept, a5 as readPaymentIdentifier } from './ledger-uFtXlIHY.cjs';
+import { C as Caip2, X as X402AcceptEntry, y as X402AnyAccept, B as X402ExactAcceptEntry, e as ExactPaymentPayloadAny, q as SignedReceipt, x as VerifyResult, J as X402UptoAcceptEntry, o as Permit2UptoPaymentPayload, w as SpendSummary, z as X402Challenge, G as X402Receipt, S as SettleOutcome, v as SpendStore, t as SpendLedger, u as SpendRecord, p as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-Crc1bZox.cjs';
+export { D as DEFAULT_EXACT_TRANSFER_METHOD, E as EXT_OFFER_RECEIPT, b as EXT_PAYMENT_IDENTIFIER, c as ExactAuthorizationWire, d as ExactPaymentPayload, H as HEADER_REQUIRED, f as HEADER_RESPONSE, g as HEADER_RESPONSE_V1, h as HEADER_SIGNATURE, i as HEADER_SIGNATURE_V1, K as KNOWN_EXACT_TRANSFER_METHODS, j as ParsedExactPayment, k as ParsedUptoPayment, l as Permit2Authorization, m as Permit2PaymentPayload, n as Permit2UptoAuthorization, r as SpendAssetTotal, s as SpendDenomTotal, F as X402PaymentSignature, I as X402ResourceObject, L as buildChallengeHeader, M as buildExactSignatureHeader, N as buildPaymentIdentifierAdvertisement, O as buildReceiptExtension, Q as buildReceiptHeader, R as buildSignatureHeader, T as buildUptoSignatureHeader, U as buildV1PaymentHeader, W as decodeBase64Json, Y as exactTransferMethod, Z as isSettleableExactMethod, _ as memorySpendStore, $ as normalizeV1Challenge, a0 as parseChallenge, a1 as parseExactObject, a2 as parseExactPaymentHeader, a3 as parseReceipt, a4 as parseReceiptExtension, a5 as parseSettleResponse, a6 as parseSignatureHeader, a7 as parseSignatureObject, a8 as parseUptoObject, a9 as parseUptoPaymentHeader, aa as pickAccept, ab as readPaymentIdentifier } from './ledger-Crc1bZox.cjs';
 import * as viem_zksync from 'viem/zksync';
 import * as abitype from 'abitype';
 import * as viem_chains from 'viem/chains';
@@ -3909,7 +3909,10 @@ interface ReceiptInput {
  * chain-agnostic — it never names a family, it just merges `extra`.
  */
 interface ExactRailInfo {
-    method: 'eip3009' | 'permit2' | 'svm' | 'algorand' | 'aptos' | 'near';
+    /** The wire `assetTransferMethod` this family advertises. XRPL's `'sequence'` is the odd one
+     *  out: it names how the transaction is SEQUENCED rather than a transfer mechanism, because the
+     *  ledger has only one way to move value. */
+    method: 'eip3009' | 'permit2' | 'svm' | 'algorand' | 'aptos' | 'near' | 'sequence';
     /** Family-specific `extra` keys merged into the exact accept (e.g. `{ name, version }`
      *  for EVM EIP-3009, `{ feePayer, tokenProgram }` for Solana, `{ feePayer }` for
      *  Algorand/Aptos/NEAR). */
@@ -4110,6 +4113,27 @@ interface ResolvedNetwork {
      * Permit2 fallback. Omitted (or `false`) ⇒ treat Permit2 as unavailable on this chain.
      */
     exactPermit2Supported?(): boolean;
+    /**
+     * OPTIONAL — can this family sign an `exact` payment for THIS asset? Omitted ⇒ the default rule
+     * applies: any recognised TOKEN yes, the NATIVE coin no (`exact` is a signed-authorization scheme
+     * a native coin can't carry on EVM/Solana/Algorand/Aptos/NEAR). A driver that declares this hook
+     * REPLACES that rule for itself and is authoritative for all of its assets.
+     *
+     * The buyer's gather calls it so an asset we cannot price safely is dropped *there* rather than
+     * planned `payable` and thrown at signing — the plan-vs-pay contract. Family-level capability is
+     * already covered by whether `payExact` exists at all; this is the per-ASSET refinement.
+     *
+     * XRPL is why it exists, and it inverts the default in both directions: native XRP IS
+     * exact-payable (863 of its 1,732 live rails are priced in XRP, and an `exact` payment there is
+     * just a signed `Payment`), while its issued currencies are NOT. On that ledger the two asset
+     * forms use DIFFERENT amount conventions on the wire — native XRP is an integer drops string (base units, e.g. `"10000"`), while an issued
+     * currency is a decimal `value` (e.g. `"0.01"`), both verified against live merchant challenges.
+     * The SDK prices and spend-caps every rail in base units, so reading an IOU's `"12"` as base
+     * units would understate a 12-RLUSD payment by 10^15 and let it slip under any policy cap while
+     * the buyer signed the real thing. Until that decimal path is threaded through quoting and the
+     * policy, XRPL declares only native XRP exact-payable.
+     */
+    exactPayableAsset?(asset: string): boolean;
     /**
      * OPTIONAL (EVM EIP-3009/Permit2 + Solana SVM + Algorand + Aptos) — verify a standard x402 `exact`
      * payment locally, then SELF-SETTLE it by broadcasting from the merchant's own `relayer`
@@ -5002,7 +5026,9 @@ declare function evaluatePolicy(intent: PaymentIntent, policy: PaymentPolicy | u
 
 /** The payment schemes a client can settle: PipRail's native `onchain-proof` (the
  *  default), the standard x402 `exact` rail (EVM EIP-3009/Permit2 + Solana SVM + Algorand
- *  + Aptos + NEAR, opt-in), and the standard x402 `upto` (metered) rail (EVM-Permit2, opt-in). */
+ *  + Aptos + NEAR + XRPL native XRP, opt-in), and the standard x402 `upto` (metered) rail
+ *  (EVM-Permit2, opt-in). NB exact is gasless on every family EXCEPT XRPL, where the fee is a
+ *  field inside the signed transaction and the payer therefore pays it. */
 type PaymentScheme = 'onchain-proof' | 'exact' | 'upto';
 
 /** Observability events. `ref` is the proof — a chain-specific id (EVM tx hash, Solana signature, TON locator, Stellar tx hash). */
@@ -5195,6 +5221,13 @@ interface PayOption {
     quote: PipRailQuote;
     /** Estimated native-coin gas to send it (cost.basis surfaced). */
     cost: CostEstimate;
+    /**
+     * For an `exact`/`upto` rail: the transfer method the buyer would actually sign, with
+     * `' (default)'` appended when the rail named none and the exact-EVM scheme's `eip3009`
+     * default applies. Absent on `onchain-proof`. Surfaced because an unnamed method used to be
+     * invisible — and invisibly unpayable; an agent debugging interop should see what we inferred.
+     */
+    method?: string;
     /** The verdict for THIS rail. 'unknown' = a read failed, so payability can't be confirmed. */
     state: 'payable' | 'blocked' | 'unknown';
     /** Hard reasons it's blocked (empty when payable). */
@@ -5792,7 +5825,7 @@ declare class PipRailClient {
      * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
      *   `onchain-proof` rails by default, and standard `exact` rails too once you opt in
      *   with `schemes: ['onchain-proof', 'exact']` (EVM EIP-3009/Permit2 + Solana SVM + Algorand
-     *   + Aptos + NEAR).
+     *   + Aptos + NEAR + XRPL native XRP).
      */
     discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
     /**
@@ -6287,7 +6320,7 @@ declare function describeChallenge(challenge: X402Challenge): string;
  * literally, so a wrong name or order actively misleads. A test pins the load-
  * bearing phrases.
  */
-declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## Landing cold \u2014 read the self-description\nEvery PipRail 402 self-describes. Read challenge.extensions.piprail for { name, what, pay[]\n(each rail's how-to-pay), sdk.install, mcp, docs } \u2014 never guess what an endpoint is. If your\ntooling can't pay a rail (e.g. a stock x402 client can't pay the onchain-proof scheme), the\nblock says how: install @piprail/sdk (npm i @piprail/sdk) or run the MCP (npx -y @piprail/mcp)\nand pay with the tools below.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to three rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM, Solana, Algorand, Aptos + NEAR, and the on-chain method (EIP-3009 / Permit2 / SVM /\n  Algorand fee-pooled group / Aptos fee-payer / NEAR SignedDelegateAction) is picked automatically.\n- upto (the metered/variable x402 rail, opt-in, EVM): the amount you see is a MAXIMUM \u2014 you sign\n  a ceiling, the server meters real usage and settles the ACTUAL (<= the max). BUDGET AGAINST THE MAX:\n  the plan/policy treat the ceiling as the spend (a server may charge up to it), so a payable plan\n  means the MAX fits your budget; the settled actual is recorded for reconciliation.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact/upto schemes are OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact,upto);\nyou can't enable them yourself, but you can report when a 402 needs one (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left: per (network,\nasset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much\nUSD you can still spend across every stablecoin and chain), the payment-count\nleash, the session time envelope, your spend so far, and the configured policy\nread back. Read-only; moves no funds. Use it in Mode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Per-payment + per-(network, asset) caps always apply. A cross-token GRAND TOTAL per\n  denomination (maxTotalPerDenom, e.g. \"$20 across every USD stablecoin + chain\") is\n  OPTIONAL \u2014 it sums tokens declared as one unit, each 1:1; it is NOT a price oracle and\n  never prices a volatile native coin. Payment-COUNT caps (maxPayments / per-window) also\n  span every chain + token.\n- The time envelope lives IN-MEMORY for THIS process (resets on restart). The money + count\n  totals also reset on restart UNLESS a durable spend store is configured \u2014 then they resume.\n- A refusal arrives as declined:true with a reasonCode; 'BUDGET' covers the lifetime, denom,\n  and count caps; 'OUTSIDE_WINDOW' covers both the rolling money and rolling count windows.\n";
+declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## Landing cold \u2014 read the self-description\nEvery PipRail 402 self-describes. Read challenge.extensions.piprail for { name, what, pay[]\n(each rail's how-to-pay), sdk.install, mcp, docs } \u2014 never guess what an endpoint is. If your\ntooling can't pay a rail (e.g. a stock x402 client can't pay the onchain-proof scheme), the\nblock says how: install @piprail/sdk (npm i @piprail/sdk) or run the MCP (npx -y @piprail/mcp)\nand pay with the tools below.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to three rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM, Solana, Algorand, Aptos + NEAR, and the on-chain method (EIP-3009 / Permit2 / SVM /\n  Algorand fee-pooled group / Aptos fee-payer / NEAR SignedDelegateAction) is picked automatically.\n  XRPL also supports exact (native XRP), with ONE difference that matters to your budget: there the\n  PAYER pays the network fee, because on the XRP Ledger the fee lives inside the signed transaction.\n  So keep a little XRP for fees on that chain \u2014 everywhere else exact means you need no native coin.\n- upto (the metered/variable x402 rail, opt-in, EVM): the amount you see is a MAXIMUM \u2014 you sign\n  a ceiling, the server meters real usage and settles the ACTUAL (<= the max). BUDGET AGAINST THE MAX:\n  the plan/policy treat the ceiling as the spend (a server may charge up to it), so a payable plan\n  means the MAX fits your budget; the settled actual is recorded for reconciliation.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact/upto schemes are OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact,upto);\nyou can't enable them yourself, but you can report when a 402 needs one (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left: per (network,\nasset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much\nUSD you can still spend across every stablecoin and chain), the payment-count\nleash, the session time envelope, your spend so far, and the configured policy\nread back. Read-only; moves no funds. Use it in Mode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Per-payment + per-(network, asset) caps always apply. A cross-token GRAND TOTAL per\n  denomination (maxTotalPerDenom, e.g. \"$20 across every USD stablecoin + chain\") is\n  OPTIONAL \u2014 it sums tokens declared as one unit, each 1:1; it is NOT a price oracle and\n  never prices a volatile native coin. Payment-COUNT caps (maxPayments / per-window) also\n  span every chain + token.\n- The time envelope lives IN-MEMORY for THIS process (resets on restart). The money + count\n  totals also reset on restart UNLESS a durable spend store is configured \u2014 then they resume.\n- A refusal arrives as declined:true with a reasonCode; 'BUDGET' covers the lifetime, denom,\n  and count caps; 'OUTSIDE_WINDOW' covers both the rolling money and rolling count windows.\n";
 /** Returns {@link PIPRAIL_AGENT_GUIDE} (a parity accessor for callers that prefer a function). */
 declare function agentGuide(): string;
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as Caip2, X as X402AcceptEntry, y as X402AnyAccept, B as X402ExactAcceptEntry, e as ExactPaymentPayloadAny, q as SignedReceipt, x as VerifyResult, I as X402UptoAcceptEntry, o as Permit2UptoPaymentPayload, w as SpendSummary, z as X402Challenge, F as X402Receipt, S as SettleOutcome, v as SpendStore, t as SpendLedger, u as SpendRecord, p as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-uFtXlIHY.js';
-export { E as EXT_OFFER_RECEIPT, b as EXT_PAYMENT_IDENTIFIER, c as ExactAuthorizationWire, d as ExactPaymentPayload, H as HEADER_REQUIRED, f as HEADER_RESPONSE, g as HEADER_RESPONSE_V1, h as HEADER_SIGNATURE, i as HEADER_SIGNATURE_V1, j as ParsedExactPayment, k as ParsedUptoPayment, l as Permit2Authorization, m as Permit2PaymentPayload, n as Permit2UptoAuthorization, r as SpendAssetTotal, s as SpendDenomTotal, D as X402PaymentSignature, G as X402ResourceObject, J as buildChallengeHeader, K as buildExactSignatureHeader, L as buildPaymentIdentifierAdvertisement, M as buildReceiptExtension, N as buildReceiptHeader, O as buildSignatureHeader, Q as buildUptoSignatureHeader, R as decodeBase64Json, T as memorySpendStore, U as parseChallenge, W as parseExactObject, Y as parseExactPaymentHeader, Z as parseReceipt, _ as parseReceiptExtension, $ as parseSettleResponse, a0 as parseSignatureHeader, a1 as parseSignatureObject, a2 as parseUptoObject, a3 as parseUptoPaymentHeader, a4 as pickAccept, a5 as readPaymentIdentifier } from './ledger-uFtXlIHY.js';
+import { C as Caip2, X as X402AcceptEntry, y as X402AnyAccept, B as X402ExactAcceptEntry, e as ExactPaymentPayloadAny, q as SignedReceipt, x as VerifyResult, J as X402UptoAcceptEntry, o as Permit2UptoPaymentPayload, w as SpendSummary, z as X402Challenge, G as X402Receipt, S as SettleOutcome, v as SpendStore, t as SpendLedger, u as SpendRecord, p as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-Crc1bZox.js';
+export { D as DEFAULT_EXACT_TRANSFER_METHOD, E as EXT_OFFER_RECEIPT, b as EXT_PAYMENT_IDENTIFIER, c as ExactAuthorizationWire, d as ExactPaymentPayload, H as HEADER_REQUIRED, f as HEADER_RESPONSE, g as HEADER_RESPONSE_V1, h as HEADER_SIGNATURE, i as HEADER_SIGNATURE_V1, K as KNOWN_EXACT_TRANSFER_METHODS, j as ParsedExactPayment, k as ParsedUptoPayment, l as Permit2Authorization, m as Permit2PaymentPayload, n as Permit2UptoAuthorization, r as SpendAssetTotal, s as SpendDenomTotal, F as X402PaymentSignature, I as X402ResourceObject, L as buildChallengeHeader, M as buildExactSignatureHeader, N as buildPaymentIdentifierAdvertisement, O as buildReceiptExtension, Q as buildReceiptHeader, R as buildSignatureHeader, T as buildUptoSignatureHeader, U as buildV1PaymentHeader, W as decodeBase64Json, Y as exactTransferMethod, Z as isSettleableExactMethod, _ as memorySpendStore, $ as normalizeV1Challenge, a0 as parseChallenge, a1 as parseExactObject, a2 as parseExactPaymentHeader, a3 as parseReceipt, a4 as parseReceiptExtension, a5 as parseSettleResponse, a6 as parseSignatureHeader, a7 as parseSignatureObject, a8 as parseUptoObject, a9 as parseUptoPaymentHeader, aa as pickAccept, ab as readPaymentIdentifier } from './ledger-Crc1bZox.js';
 import * as viem_zksync from 'viem/zksync';
 import * as abitype from 'abitype';
 import * as viem_chains from 'viem/chains';
@@ -3909,7 +3909,10 @@ interface ReceiptInput {
  * chain-agnostic — it never names a family, it just merges `extra`.
  */
 interface ExactRailInfo {
-    method: 'eip3009' | 'permit2' | 'svm' | 'algorand' | 'aptos' | 'near';
+    /** The wire `assetTransferMethod` this family advertises. XRPL's `'sequence'` is the odd one
+     *  out: it names how the transaction is SEQUENCED rather than a transfer mechanism, because the
+     *  ledger has only one way to move value. */
+    method: 'eip3009' | 'permit2' | 'svm' | 'algorand' | 'aptos' | 'near' | 'sequence';
     /** Family-specific `extra` keys merged into the exact accept (e.g. `{ name, version }`
      *  for EVM EIP-3009, `{ feePayer, tokenProgram }` for Solana, `{ feePayer }` for
      *  Algorand/Aptos/NEAR). */
@@ -4110,6 +4113,27 @@ interface ResolvedNetwork {
      * Permit2 fallback. Omitted (or `false`) ⇒ treat Permit2 as unavailable on this chain.
      */
     exactPermit2Supported?(): boolean;
+    /**
+     * OPTIONAL — can this family sign an `exact` payment for THIS asset? Omitted ⇒ the default rule
+     * applies: any recognised TOKEN yes, the NATIVE coin no (`exact` is a signed-authorization scheme
+     * a native coin can't carry on EVM/Solana/Algorand/Aptos/NEAR). A driver that declares this hook
+     * REPLACES that rule for itself and is authoritative for all of its assets.
+     *
+     * The buyer's gather calls it so an asset we cannot price safely is dropped *there* rather than
+     * planned `payable` and thrown at signing — the plan-vs-pay contract. Family-level capability is
+     * already covered by whether `payExact` exists at all; this is the per-ASSET refinement.
+     *
+     * XRPL is why it exists, and it inverts the default in both directions: native XRP IS
+     * exact-payable (863 of its 1,732 live rails are priced in XRP, and an `exact` payment there is
+     * just a signed `Payment`), while its issued currencies are NOT. On that ledger the two asset
+     * forms use DIFFERENT amount conventions on the wire — native XRP is an integer drops string (base units, e.g. `"10000"`), while an issued
+     * currency is a decimal `value` (e.g. `"0.01"`), both verified against live merchant challenges.
+     * The SDK prices and spend-caps every rail in base units, so reading an IOU's `"12"` as base
+     * units would understate a 12-RLUSD payment by 10^15 and let it slip under any policy cap while
+     * the buyer signed the real thing. Until that decimal path is threaded through quoting and the
+     * policy, XRPL declares only native XRP exact-payable.
+     */
+    exactPayableAsset?(asset: string): boolean;
     /**
      * OPTIONAL (EVM EIP-3009/Permit2 + Solana SVM + Algorand + Aptos) — verify a standard x402 `exact`
      * payment locally, then SELF-SETTLE it by broadcasting from the merchant's own `relayer`
@@ -5002,7 +5026,9 @@ declare function evaluatePolicy(intent: PaymentIntent, policy: PaymentPolicy | u
 
 /** The payment schemes a client can settle: PipRail's native `onchain-proof` (the
  *  default), the standard x402 `exact` rail (EVM EIP-3009/Permit2 + Solana SVM + Algorand
- *  + Aptos + NEAR, opt-in), and the standard x402 `upto` (metered) rail (EVM-Permit2, opt-in). */
+ *  + Aptos + NEAR + XRPL native XRP, opt-in), and the standard x402 `upto` (metered) rail
+ *  (EVM-Permit2, opt-in). NB exact is gasless on every family EXCEPT XRPL, where the fee is a
+ *  field inside the signed transaction and the payer therefore pays it. */
 type PaymentScheme = 'onchain-proof' | 'exact' | 'upto';
 
 /** Observability events. `ref` is the proof — a chain-specific id (EVM tx hash, Solana signature, TON locator, Stellar tx hash). */
@@ -5195,6 +5221,13 @@ interface PayOption {
     quote: PipRailQuote;
     /** Estimated native-coin gas to send it (cost.basis surfaced). */
     cost: CostEstimate;
+    /**
+     * For an `exact`/`upto` rail: the transfer method the buyer would actually sign, with
+     * `' (default)'` appended when the rail named none and the exact-EVM scheme's `eip3009`
+     * default applies. Absent on `onchain-proof`. Surfaced because an unnamed method used to be
+     * invisible — and invisibly unpayable; an agent debugging interop should see what we inferred.
+     */
+    method?: string;
     /** The verdict for THIS rail. 'unknown' = a read failed, so payability can't be confirmed. */
     state: 'payable' | 'blocked' | 'unknown';
     /** Hard reasons it's blocked (empty when payable). */
@@ -5792,7 +5825,7 @@ declare class PipRailClient {
      * - Results are cross-scheme (mostly the mainstream `exact` scheme); `fetch()` pays
      *   `onchain-proof` rails by default, and standard `exact` rails too once you opt in
      *   with `schemes: ['onchain-proof', 'exact']` (EVM EIP-3009/Permit2 + Solana SVM + Algorand
-     *   + Aptos + NEAR).
+     *   + Aptos + NEAR + XRPL native XRP).
      */
     discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>;
     /**
@@ -6287,7 +6320,7 @@ declare function describeChallenge(challenge: X402Challenge): string;
  * literally, so a wrong name or order actively misleads. A test pins the load-
  * bearing phrases.
  */
-declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## Landing cold \u2014 read the self-description\nEvery PipRail 402 self-describes. Read challenge.extensions.piprail for { name, what, pay[]\n(each rail's how-to-pay), sdk.install, mcp, docs } \u2014 never guess what an endpoint is. If your\ntooling can't pay a rail (e.g. a stock x402 client can't pay the onchain-proof scheme), the\nblock says how: install @piprail/sdk (npm i @piprail/sdk) or run the MCP (npx -y @piprail/mcp)\nand pay with the tools below.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to three rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM, Solana, Algorand, Aptos + NEAR, and the on-chain method (EIP-3009 / Permit2 / SVM /\n  Algorand fee-pooled group / Aptos fee-payer / NEAR SignedDelegateAction) is picked automatically.\n- upto (the metered/variable x402 rail, opt-in, EVM): the amount you see is a MAXIMUM \u2014 you sign\n  a ceiling, the server meters real usage and settles the ACTUAL (<= the max). BUDGET AGAINST THE MAX:\n  the plan/policy treat the ceiling as the spend (a server may charge up to it), so a payable plan\n  means the MAX fits your budget; the settled actual is recorded for reconciliation.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact/upto schemes are OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact,upto);\nyou can't enable them yourself, but you can report when a 402 needs one (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left: per (network,\nasset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much\nUSD you can still spend across every stablecoin and chain), the payment-count\nleash, the session time envelope, your spend so far, and the configured policy\nread back. Read-only; moves no funds. Use it in Mode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Per-payment + per-(network, asset) caps always apply. A cross-token GRAND TOTAL per\n  denomination (maxTotalPerDenom, e.g. \"$20 across every USD stablecoin + chain\") is\n  OPTIONAL \u2014 it sums tokens declared as one unit, each 1:1; it is NOT a price oracle and\n  never prices a volatile native coin. Payment-COUNT caps (maxPayments / per-window) also\n  span every chain + token.\n- The time envelope lives IN-MEMORY for THIS process (resets on restart). The money + count\n  totals also reset on restart UNLESS a durable spend store is configured \u2014 then they resume.\n- A refusal arrives as declined:true with a reasonCode; 'BUDGET' covers the lifetime, denom,\n  and count caps; 'OUTSIDE_WINDOW' covers both the rolling money and rolling count windows.\n";
+declare const PIPRAIL_AGENT_GUIDE = "# Paying with PipRail \u2014 the agent contract\n\nYou can pay for x402 \"402 Payment Required\" resources autonomously. Money moves\nstraight from your wallet to the server; PipRail custodies nothing. Follow this.\n\n## Landing cold \u2014 read the self-description\nEvery PipRail 402 self-describes. Read challenge.extensions.piprail for { name, what, pay[]\n(each rail's how-to-pay), sdk.install, mcp, docs } \u2014 never guess what an endpoint is. If your\ntooling can't pay a rail (e.g. a stock x402 client can't pay the onchain-proof scheme), the\nblock says how: install @piprail/sdk (npm i @piprail/sdk) or run the MCP (npx -y @piprail/mcp)\nand pay with the tools below.\n\n## The loop: quote \u2192 plan \u2192 pay\n1. piprail_quote_payment(url) \u2014 PRICE it. Returns the amount, token, chain, and\n   whether it is within your spend policy. No funds move. Use it to decide if a\n   resource is worth buying.\n2. piprail_plan_payment(url) \u2014 can I afford it NOW? Reads your balance, native gas,\n   and recipient-readiness across every rail, and returns { payable, best,\n   fundingHint, session? }. If payable is false, do NOT attempt the payment \u2014\n   fundingHint says exactly what to fix.\n3. piprail_pay_request(url, method?, body?) \u2014 PAY (only if the plan was payable)\n   and return the result.\nAlways plan before you pay so you never commit to a payment you cannot finish.\n\n## Gasless \u2014 the exact rail (zero gas for you)\nA 402 may offer up to three rails; you don't choose per payment \u2014 the client does, automatically:\n- onchain-proof (PipRail's default): you broadcast the payment yourself and pay the network gas\n  (the native coin \u2014 ETH/SOL/\u2026). Works on every chain.\n- exact (the ratified x402 rail, opt-in): you only SIGN; the server \u2014 or a facilitator it chose\n  (e.g. PayAI) \u2014 broadcasts it, so you pay ZERO gas (you need only the token, no native coin). It\n  works on EVM, Solana, Algorand, Aptos + NEAR, and the on-chain method (EIP-3009 / Permit2 / SVM /\n  Algorand fee-pooled group / Aptos fee-payer / NEAR SignedDelegateAction) is picked automatically.\n  XRPL also supports exact (native XRP), with ONE difference that matters to your budget: there the\n  PAYER pays the network fee, because on the XRP Ledger the fee lives inside the signed transaction.\n  So keep a little XRP for fees on that chain \u2014 everywhere else exact means you need no native coin.\n- upto (the metered/variable x402 rail, opt-in, EVM): the amount you see is a MAXIMUM \u2014 you sign\n  a ceiling, the server meters real usage and settles the ACTUAL (<= the max). BUDGET AGAINST THE MAX:\n  the plan/policy treat the ceiling as the spend (a server may charge up to it), so a payable plan\n  means the MAX fits your budget; the settled actual is recorded for reconciliation.\nWhen the exact scheme is enabled AND balance-aware routing is on, paying picks the cheapest\nsettleable rail \u2014 i.e. the gasless exact one. Nothing changes in your loop: quote \u2192 plan \u2192 pay is\nidentical. The exact/upto schemes are OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact,upto);\nyou can't enable them yourself, but you can report when a 402 needs one (see UNSUPPORTED_SCHEME below).\n\n## Reading a refusal \u2014 never crash, never double-spend\nA failed pay returns a STRUCTURED object, never a thrown error you must catch:\n  { ok:false, code, reason, explain, ref?, reasonCode?, declined? }\nBranch on `code` (always reliable). Key cases:\n- declined:true with reasonCode:'SESSION_EXPIRED' \u2014 your time budget is over. This\n  is TERMINAL: STOP. Do not retry ANY payment this process; it cannot be undone\n  without a restart / a longer TTL.\n- declined:true with reasonCode:'APPROVAL' \u2014 a human (or hook) declined this\n  payment. Terminal for this pay: do NOT auto-retry \u2014 they said no, or no one\n  answered.\n- declined:true with reasonCode:'OUTSIDE_WINDOW' \u2014 your rolling rate-limit is\n  exhausted. Wait for it to free, then retry; do not raise the amount.\n- declined:true with reasonCode:'POLICY' or 'BUDGET' \u2014 a spend cap or allowlist\n  refused it. Don't retry the same payment; pick a cheaper/allowed one.\n- code:'INSUFFICIENT_FUNDS' \u2014 top up the wallet (token and/or native gas), retry.\n- code:'PAYMENT_TIMEOUT' / 'MAX_RETRIES_EXCEEDED' / 'CONFIRMATION_TIMEOUT' \u2014 the\n  payment may ALREADY be on-chain. Recover using the proof on `.ref` (re-verify\n  or re-submit it); never re-pay \u2014 a fresh payment would double-spend. On a gasless\n  exact rail `.ref` is the authorization NONCE, not a tx hash: re-present the SAME\n  signed authorization, never sign a fresh one (that would risk a double-spend).\n- code:'NO_COMPATIBLE_ACCEPT' / 'UNSUPPORTED_SCHEME' \u2014 the 402 isn't payable on\n  your chain/scheme; `explain` says whether it's the wrong chain or a scheme to enable.\n  If it's a standard x402 server offering an exact rail, that's a config fix the operator makes\n  once (enable the exact scheme); report it, don't retry the same call blindly.\n\n## Knowing your leash \u2014 call piprail_budget\npiprail_budget tells you how much budget and time you have left: per (network,\nasset) remaining, the cross-token GRAND TOTAL per denomination (e.g. how much\nUSD you can still spend across every stablecoin and chain), the payment-count\nleash, the session time envelope, your spend so far, and the configured policy\nread back. Read-only; moves no funds. Use it in Mode A to self-check before paying.\n\n## Two modes\n- Mode A (headless, default): you run FREE inside a pre-set budget + time\n  envelope. The policy IS the consent \u2014 there is no per-payment prompt. Stay\n  inside it; piprail_budget shows what's left.\n- Mode B (supervised): the host may ask a human to approve each payment. A\n  decline/cancel/timeout comes back as declined:true (reasonCode:'APPROVAL') \u2014\n  do NOT retry it as if it were a transient error.\n\n## Hard facts\n- Per-payment + per-(network, asset) caps always apply. A cross-token GRAND TOTAL per\n  denomination (maxTotalPerDenom, e.g. \"$20 across every USD stablecoin + chain\") is\n  OPTIONAL \u2014 it sums tokens declared as one unit, each 1:1; it is NOT a price oracle and\n  never prices a volatile native coin. Payment-COUNT caps (maxPayments / per-window) also\n  span every chain + token.\n- The time envelope lives IN-MEMORY for THIS process (resets on restart). The money + count\n  totals also reset on restart UNLESS a durable spend store is configured \u2014 then they resume.\n- A refusal arrives as declined:true with a reasonCode; 'BUDGET' covers the lifetime, denom,\n  and count caps; 'OUTSIDE_WINDOW' covers both the rolling money and rolling count windows.\n";
 /** Returns {@link PIPRAIL_AGENT_GUIDE} (a parity accessor for callers that prefer a function). */
 declare function agentGuide(): string;