@piprail/sdk 2.9.0 → 2.11.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as Caip2, X as X402AcceptEntry, r as X402AnyAccept, t as X402ExactAcceptEntry, c as ExactPaymentPayloadAny, q as VerifyResult, p as SpendSummary, s as X402Challenge, v as X402Receipt, S as SettleOutcome, o as SpendStore, m as SpendLedger, n as SpendRecord, a as AssetId, A as AddressId, V as VerifyErrorCode, P as PaidReceipt } from './ledger-BtzrfO-3.cjs';
-export { E as ExactAuthorizationWire, b as ExactPaymentPayload, H as HEADER_REQUIRED, d as HEADER_RESPONSE, e as HEADER_RESPONSE_V1, f as HEADER_SIGNATURE, g as HEADER_SIGNATURE_V1, h as ParsedExactPayment, i as Permit2Authorization, j as Permit2PaymentPayload, k as SpendAssetTotal, l as SpendDenomTotal, u as X402PaymentSignature, w as X402ResourceObject, x as buildChallengeHeader, y as buildExactSignatureHeader, z as buildReceiptHeader, B as buildSignatureHeader, D as memorySpendStore, F as parseChallenge, G as parseExactPaymentHeader, I as parseReceipt, J as parseSettleResponse, K as parseSignatureHeader, L as pickAccept } from './ledger-BtzrfO-3.cjs';
+import { C as Caip2, X as X402AcceptEntry, x as X402AnyAccept, z as X402ExactAcceptEntry, d as ExactPaymentPayloadAny, p as SignedReceipt, w as VerifyResult, G as X402UptoAcceptEntry, n as Permit2UptoPaymentPayload, v as SpendSummary, y as X402Challenge, D as X402Receipt, S as SettleOutcome, u as SpendStore, s as SpendLedger, t as SpendRecord, o as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-OQos-tmj.cjs';
+export { E as EXT_OFFER_RECEIPT, b as ExactAuthorizationWire, c as ExactPaymentPayload, H as HEADER_REQUIRED, e as HEADER_RESPONSE, f as HEADER_RESPONSE_V1, g as HEADER_SIGNATURE, h as HEADER_SIGNATURE_V1, i as ParsedExactPayment, j as ParsedUptoPayment, k as Permit2Authorization, l as Permit2PaymentPayload, m as Permit2UptoAuthorization, q as SpendAssetTotal, r as SpendDenomTotal, B as X402PaymentSignature, F as X402ResourceObject, I as buildChallengeHeader, J as buildExactSignatureHeader, K as buildReceiptExtension, L as buildReceiptHeader, M as buildSignatureHeader, N as buildUptoSignatureHeader, O as decodeBase64Json, Q as memorySpendStore, R as parseChallenge, T as parseExactObject, U as parseExactPaymentHeader, W as parseReceipt, Y as parseReceiptExtension, Z as parseSettleResponse, _ as parseSignatureHeader, $ as parseSignatureObject, a0 as parseUptoObject, a1 as parseUptoPaymentHeader, a2 as pickAccept } from './ledger-OQos-tmj.cjs';
 import * as viem_zksync from 'viem/zksync';
 import * as abitype from 'abitype';
 import * as viem_chains from 'viem/chains';
@@ -3863,6 +3863,32 @@ interface DiscoverySigner {
     /** Sign an arbitrary UTF-8 message (EVM: eip191) — for proofs/SIWX only. */
     signMessage(message: string): Promise<string>;
 }
+/**
+ * The official x402 `offer-receipt` §5.2 signed-field set a merchant attests over in
+ * Tier-2 — the SMALLER official payload (NOT PipRail's full {@link X402Receipt}),
+ * consumed by the optional EVM-only {@link ResolvedNetwork.signReceipt}. The gate
+ * maps PipRail's settlement data into it. `payTo` rides ALONGSIDE the signed fields
+ * purely so a verifier knows the expected signer (`recover === payTo`); it is NOT
+ * part of the EIP-712 message.
+ */
+interface ReceiptInput {
+    /** The merchant `payTo` wallet — the signer a verifier checks `recover ===` against. NOT signed. */
+    payTo: string;
+    /** CAIP-2 network the settlement happened on (signed `network`). */
+    network: string;
+    /** The paid resource URL (signed `resourceUrl`). */
+    resourceUrl: string;
+    /** The payer identifier — the on-chain sender (signed `payer`). */
+    payer: string;
+    /** Unix SECONDS the receipt was issued (signed `issuedAt`). */
+    issuedAt: number;
+    /**
+     * The settlement tx hash, or the empty string `''` when suppressed
+     * (`includeTxHash:false`). §5.3: the signed EIP-712 message MUST carry `''`,
+     * NEVER an omitted key — a verifier treats `''` as absence. Default `''`.
+     */
+    transaction?: string;
+}
 /**
  * How a family advertises a standard `exact` rail for one asset — returned by
  * {@link ResolvedNetwork.resolveExactRail} and consumed by the gate to build the
@@ -3880,6 +3906,21 @@ interface ExactRailInfo {
      *  Algorand/Aptos/NEAR). */
     extra?: Record<string, unknown>;
 }
+/**
+ * How a family advertises a standard `upto` (metered) rail for one asset — the metered
+ * sibling of {@link ExactRailInfo}, returned by {@link ResolvedNetwork.resolveUptoRail}
+ * and consumed by the gate to build the `X402UptoAcceptEntry`. The `method` is always the
+ * PipRail-internal `'permit2-upto'` (upto is EVM-Permit2 only); `extra` is merged VERBATIM
+ * into the accept's `extra`, carrying `{ facilitatorAddress, name?, version? }` — the
+ * relayer address the buyer signs into `witness.facilitator` plus the token's EIP-712
+ * domain bits. Keeping the chain-specific shape behind this descriptor is what lets
+ * `server.ts` stay chain-agnostic — it never names a family, it just merges `extra`.
+ */
+interface UptoRailInfo {
+    method: 'permit2-upto';
+    /** Family-specific `extra` keys merged into the upto accept: `{ facilitatorAddress, name?, version? }`. */
+    extra?: Record<string, unknown>;
+}
 /**
  * A driver bound to one concrete network — what the gate and client hold. Each
  * method's error behaviour is fixed by the SDK error standard (see ERRORS.md §5):
@@ -3996,6 +4037,20 @@ interface ResolvedNetwork {
      * REQUIRED methods. Returns `null` if the bound wallet can't sign.
      */
     discoverySigner?(wallet: WalletHandle): DiscoverySigner | null;
+    /**
+     * OPTIONAL (EVM-only today) — Tier-2 service-delivery attestation. Sign the
+     * official x402 `offer-receipt` EIP-712 `RECEIPT_TYPES` (the SMALLER official
+     * §5.2 payload) with the bound wallet — typically the merchant's existing `payTo`
+     * key — so a buyer can prove the resource was SERVED, the one thing the chain
+     * can't attest. A verifier ({@link PipRailClient.verifyAttestation}) re-recovers
+     * and checks `recover === payTo`. The signed domain is hardcoded `chainId:1` for
+     * EVERY network (uniform signing), so this is chain-independent and EVM-only by
+     * the optional `?` gate — non-EVM families omit it (no all-families mirror),
+     * exactly like {@link discoverySigner}/{@link payExact}. The gate calls it after
+     * settle when `receipts.attest` is set + the rail is EVM; the result rides in
+     * `extensions['offer-receipt'].info.attestation`. NEVER part of the payment path.
+     */
+    signReceipt?(wallet: WalletHandle, input: ReceiptInput): Promise<SignedReceipt>;
     /** Verify `ref` satisfies `accept`, RPC-only, in-process. */
     verify(ref: string, accept: X402AcceptEntry): Promise<VerifyResult>;
     /**
@@ -4066,6 +4121,54 @@ interface ResolvedNetwork {
         payload: ExactPaymentPayloadAny;
         accept: X402ExactAcceptEntry;
     }): Promise<VerifyResult>;
+    /**
+     * OPTIONAL (EVM-Permit2 ONLY) — advertise a standard `upto` (metered) rail for `asset`,
+     * or `null` when this asset/chain can't carry one (a native coin, a non-Permit2-proxy
+     * chain, a non-Permit2 token). The gate's rail-advertisement SPI for the metered rail —
+     * the parallel of {@link resolveExactRail}. The `relayer` becomes the bound
+     * `witness.facilitator` (upto is self-settle only in v1, no facilitator mode), so the
+     * returned `extra.facilitatorAddress` is the relayer's own address. The optional `?` IS
+     * the EVM-only gate — every non-EVM family omits it, so the gate never offers upto there.
+     * RPC-read (EVM reads the token's EIP-712 domain); never throws for a transient read.
+     */
+    resolveUptoRail?(input: {
+        asset: string;
+        relayer: WalletHandle;
+    }): Promise<UptoRailInfo | null>;
+    /**
+     * OPTIONAL (EVM-Permit2 ONLY) — BUYER side: sign a Permit2 `PermitWitnessTransferFrom`
+     * authorization for the MAX (`accept.amount`), binding `witness.facilitator =
+     * accept.extra.facilitatorAddress` as the MIDDLE witness field. Re-derives the proxy +
+     * witness types internally; never trusts a server-supplied domain. The metered counterpart
+     * to {@link payExact}. The client frames the returned `payload` + `accepted` echo into the
+     * `PAYMENT-SIGNATURE` header; the merchant self-settles the actual. Returns the signed
+     * payload, the chosen-rail echo, the payer address, and the Permit2 nonce. THROWS a typed
+     * `PipRailError` when the signer is a contract / EIP-1271 / EIP-7702 account.
+     */
+    payUpto?(wallet: WalletHandle, accept: X402UptoAcceptEntry): Promise<{
+        payload: Permit2UptoPaymentPayload;
+        accepted: X402UptoAcceptEntry;
+        payerFrom: string;
+        nonce: string;
+    }>;
+    /**
+     * OPTIONAL (EVM-Permit2 ONLY) — SELLER side: verify a standard x402 `upto` payment
+     * locally, then SELF-SETTLE the ACTUAL (`settleAmount`, ≤ the signed max) through the upto
+     * proxy from the merchant's `relayer`. The metered counterpart to {@link settleExactSelf}.
+     * Re-verifies the signature against `permitted.amount` (the signed MAX, NEVER the metered
+     * actual — verifying against the actual would reject every partial settle); guards
+     * `witness.facilitator === relayer.address`; clamps/rejects `settleAmount > max` with
+     * `upto_settle_exceeds_max`; SKIPS the on-chain tx when `settleAmount === 0n` (a synthetic
+     * zero-charge receipt with `transaction: ""`). RETURNS a `VerifyResult` for a client-fixable
+     * fault; THROWS {@link SettlementError} on a broadcast failure of a valid auth. Re-derives
+     * every checked field from the trusted `accept`, never the client echo.
+     */
+    settleUptoSelf?(input: {
+        relayer: WalletHandle;
+        payload: Permit2UptoPaymentPayload;
+        accept: X402UptoAcceptEntry;
+        settleAmount: bigint;
+    }): Promise<VerifyResult>;
 }
 interface ResolveOptions {
     /** The developer-supplied `chain` selector. */
@@ -4705,7 +4808,11 @@ interface PaymentPolicy {
     /** Lifetime ceiling for this client, PER DISTINCT ASSET (network+asset).
      *  Summing across different tokens is unit-meaningless without a price
      *  oracle (which the SDK deliberately doesn't add), so each token gets its
-     *  own running cap. Pair with `tokens: ['USDC']` for a single-currency budget. */
+     *  own running cap. Pair with `tokens: ['USDC']` for a single-currency budget.
+     *  NOTE — the metered `upto` rail debits this (and `maxTotalPerDenom`/`windowTotal`)
+     *  by the authorized **MAX**, not the merchant's claimed settled actual, so an
+     *  under-reporting merchant can never loosen the leash; the settled actual is
+     *  surfaced on each spend record's `settledBase` for reconciliation. */
     maxTotal?: string;
     /** Allowlist of chains the agent may pay on. A 402 on any other chain is
      *  declined. Strings match the configured selector; objects match by id. */
@@ -4874,8 +4981,9 @@ interface PolicyContext {
 declare function evaluatePolicy(intent: PaymentIntent, policy: PaymentPolicy | undefined, spentForAssetBase: bigint, ctx?: PolicyContext): PolicyDecision;
 
 /** The payment schemes a client can settle: PipRail's native `onchain-proof` (the
- *  default) and the standard x402 `exact` rail (EVM EIP-3009/Permit2 + Solana SVM + Algorand, opt-in). */
-type PaymentScheme = 'onchain-proof' | 'exact';
+ *  default), the standard x402 `exact` rail (EVM EIP-3009/Permit2 + Solana SVM + Algorand,
+ *  opt-in), and the standard x402 `upto` (metered) rail (EVM-Permit2, opt-in). */
+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). */
 type PipRailEvent = {
@@ -5421,6 +5529,39 @@ interface PayingClient {
      *  without hitting a decline). `undefined` when no policy is set. */
     policy(): PaymentPolicy | undefined;
 }
+/**
+ * The verdict from {@link PipRailClient.verifyReceipt} — a {@link PipRailReceipt}
+ * re-verified against the chain, never trusting the receipt's claims. `ok` is the
+ * chain's confirmation that the settlement is real (≥`amount` of `asset` moved to
+ * `payTo`); `onChain` is RE-DERIVED from the tx (`payer` genuinely so; `amount` is a
+ * VERIFIED LOWER BOUND — drivers threshold-check `paid >= required` then echo the
+ * accept amount); `matchesClaims` is whether the re-derived `payer` equals the
+ * receipt's claimed `payer` (a forged payer → `false` even when `ok` is `true`).
+ *
+ * Re-verification is **durable** for digest-bound (Template-B) families (EVM, Solana,
+ * Tron, Sui, Aptos, native coins — the driver reads the tx by hash/digest) and
+ * **recency-bounded / best-effort** for the account-watch families (Stellar, XRPL,
+ * Algorand, TON), whose drivers scan only recent merchant-account history — an old
+ * receipt there can return `transfer_not_found` even though it once settled.
+ */
+interface ReceiptVerification {
+    /** The chain confirms the settlement (≥`amount` moved to `payTo`). */
+    ok: boolean;
+    /** Fields RE-DERIVED from the on-chain tx. `payer` is genuinely re-derived; `amount`
+     *  is a verified LOWER BOUND (the chain confirms at least this much moved). */
+    onChain: {
+        payTo: string;
+        asset: string;
+        amount: string;
+        payer: string;
+    };
+    /** Does the re-derived on-chain `payer` match the receipt's claimed `payer`? */
+    matchesClaims: boolean;
+    /** Informational age of the receipt (seconds since `verifiedAt`); NOT a validity gate. */
+    ageSeconds: number;
+    /** The closed verification code when `ok` is false (reuses the driver vocabulary). */
+    error?: VerifyErrorCode;
+}
 declare class PipRailClient {
     private readonly opts;
     private readonly maxRetries;
@@ -5428,6 +5569,7 @@ declare class PipRailClient {
     private readonly onEvent;
     private readonly ledger;
     private bound?;
+    private lastReceiptValue;
     constructor(opts: PipRailClientOptions);
     /**
      * Fail LOUDLY at construction on a malformed amount cap — a security boundary
@@ -5458,6 +5600,55 @@ declare class PipRailClient {
     /** Emit an observability event, never letting a throwing handler break the
      * payment flow (mirrors the server gate's `onPaid` isolation). */
     private safeEmit;
+    /**
+     * Capture the verifiable receipt from a settled response (pure — no chain read), stamping
+     * the resource URL this client actually fetched (authoritative over the gate's default ''). A
+     * settled fetch with no receipt extension sets it to `null` so {@link lastReceipt} reflects the
+     * latest fetch. Never throws — a malformed header just yields `null`.
+     */
+    private captureReceipt;
+    /**
+     * The verifiable {@link PipRailReceipt} from the most recent settled `fetch` — the
+     * self-contained record the buyer KEEPS and anyone re-verifies against the chain
+     * (see {@link PipRailClient.verifyReceipt}). `null` when the last settled fetch carried
+     * no receipt (the gate's `receipts` option was off) or no payment has settled yet. Pure.
+     */
+    lastReceipt(): PipRailReceipt | null;
+    /**
+     * Re-verify ANY {@link PipRailReceipt} against the chain — the anyone-can-run primitive.
+     * Re-reads `receipt.transaction` via the receipt's own network driver and re-derives
+     * `payTo`/`asset`/`payer` from the tx, **never trusting the receipt's claims**: a forged
+     * `payTo`/`asset`/over-stated `amount` makes the driver's `verify()` fail (`ok:false`); a
+     * forged `payer` surfaces as `matchesClaims:false`. Static + WALLET-FREE — a third party
+     * verifies with only a chain + RPC, no PipRail account. **Never throws** (an RPC error or a
+     * malformed receipt → `{ ok:false, error }`). Viem-free here — the chain read happens inside
+     * the lazily-mounted family driver (the protocol layer pulls no chain libs). Durable for
+     * digest-bound families; recency-bounded for the account-watch families (see
+     * {@link ReceiptVerification}).
+     */
+    static verifyReceipt(receipt: PipRailReceipt, opts?: {
+        rpcUrl?: string;
+    }): Promise<ReceiptVerification>;
+    /**
+     * Verify the OPTIONAL Tier-2 service-delivery attestation on a {@link PipRailReceipt}
+     * — the merchant's signed proof that the resource was actually SERVED (the one thing
+     * the chain can't attest). For an EVM EIP-712 attestation this re-recovers the signer
+     * from the signature over the official `offer-receipt` typed data and checks
+     * `recover === receipt.payTo` (spec §4.5.1 / §5.5) — the classic EIP-712 footgun made
+     * safe (`recoverTypedDataAddress` returns a WRONG address rather than throwing on a bad
+     * signature, so the equality check is the real verification). A tampered signature →
+     * `{ ok:false }`, never a throw.
+     *
+     * Static + wallet-free. **Never throws** (a malformed/absent attestation, an unsupported
+     * format, or a recovery fault → `{ ok:false, reason }`). Viem-free HERE — the recover runs
+     * inside the lazily-imported EVM receipt driver (a lazy chunk), so the protocol layer pulls
+     * no chain libs. The JWS format defers to R3 (`{ ok:false, reason:'jws-not-loaded' }`).
+     */
+    static verifyAttestation(receipt: PipRailReceipt): Promise<{
+        ok: boolean;
+        signer?: string;
+        reason?: string;
+    }>;
     /** Auto-mount the chain's driver, resolve the network, and bind the wallet — once. */
     private ensure;
     /** Resolve the effective scheme set: a per-call override, else the constructor's
@@ -5698,7 +5889,17 @@ declare class PipRailClient {
      *  denomination it counts toward in the grand total). Then fire the `onSpend` callback
      *  with the record + the post-payment budget, and emit any `warnAtFraction` thresholds
      *  this payment just crossed. All observability is isolated — a throwing hook never
-     *  affects the (already-settled) payment. */
+     *  affects the (already-settled) payment.
+     *
+     *  `settledAmountBase` is the SINGLE upto ledger-reconciliation seam: the quote (and thus
+     *  the policy/budget) gates on the MAX, and for the metered `upto` rail the budgeted amount
+     *  RECORDED is ALSO the authorized MAX — the only buyer-provable bound. The merchant's
+     *  claimed actual is UNTRUSTED (a malicious merchant can settle the MAX on-chain yet report
+     *  a tiny `SettleOutcome.amount`); recording it would let an under-report silently loosen a
+     *  cumulative cap (`maxTotal`/`maxTotalPerDenom`/`windowTotal`) past the buyer's real on-chain
+     *  spend (POL-1). So the cap-bearing `amountBase` is the MAX; the clamped actual is surfaced
+     *  separately on `settledBase`/`settledFormatted` for transparency (it equals the receipt's
+     *  amount). When absent (onchain-proof/exact) this is byte-identical to before. */
     private recordSpend;
     /**
      * Emit a `budget-threshold` event for each cap whose used-fraction just reached
@@ -5728,6 +5929,16 @@ declare class PipRailClient {
      *   • the spend is recorded EXACTLY ONCE, on an affirmative settlement only.
      */
     private payExactRail;
+    /**
+     * The standard `upto` (metered) buyer path — a near-clone of {@link payExactRail} with TWO
+     * deltas: (1) it signs a Permit2-upto authorization for the MAX via `payUpto` + frames it
+     * with `buildUptoSignatureHeader`; (2) it records the ACTUAL settled amount (read off the
+     * SettleResponse's required `amount` field, via `recordSpend(quote, ref, settle.amount)`) in
+     * the ledger — the budget gated on the MAX, the ledger records the ACTUAL. A server that omits
+     * `settle.amount` FAILS SAFE to the MAX (over-counts, never under-counts). The buyer SIGNS, the
+     * merchant self-settles — the buyer never broadcasts.
+     */
+    private payUptoRail;
 }
 /**
  * Plan a payment ACROSS several single-chain clients — the cross-chain brain.
@@ -5988,7 +6199,7 @@ interface AgentTool {
     invoke: (args: Record<string, unknown>) => Promise<unknown>;
 }
 /**
- * Seven tools wrapping a configured {@link PipRailClient}:
+ * Eight tools wrapping a configured {@link PipRailClient}:
  *   - `piprail_discover(query?)` — FIND payable resources on the open x402
  *     indexes, WITHOUT paying (the phone book — solves "what can I buy?").
  *   - `piprail_quote_payment(url)` — price a gated URL WITHOUT paying.
@@ -5999,8 +6210,10 @@ interface AgentTool {
  *     other agents can find it (402 Index, no signature).
  *   - `piprail_budget()` — read the remaining spend budget + time leash (Mode A self-check).
  *   - `piprail_guide()` — read the agent contract (how to quote/plan/pay + read a refusal).
+ *   - `piprail_verify_receipt(receipt, rpcUrl?)` — re-verify a verifiable receipt against the
+ *     chain WITHOUT a wallet (anyone-verifiable; never throws — returns a structured verdict).
  *
- * The first five are byte-identical in name + order to before; the two read-only
+ * The first five are byte-identical in name + order to before; the three read-only
  * tools are appended LAST. EVERY failure the pay tool sees comes back as a
  * STRUCTURED object (`{ ok:false, code, reason, explain, ref?, reasonCode?,
  * declined? }`) — never a thrown error — so the model reasons about it (and never
@@ -6053,7 +6266,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 two 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, and the on-chain method (EIP-3009 / Permit2 / SVM / Algorand\n  fee-pooled group) is picked automatically.\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 scheme is OPT-IN by the operator (MCP: PIPRAIL_SCHEMES=onchain-proof,exact);\nyou can't enable it yourself, but you can report when a 402 needs it (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, and the on-chain method (EIP-3009 / Permit2 / SVM / Algorand\n  fee-pooled group) 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";
 /** Returns {@link PIPRAIL_AGENT_GUIDE} (a parity accessor for callers that prefer a function). */
 declare function agentGuide(): string;
 
@@ -6134,7 +6347,7 @@ declare const BRAND: {
  * human-readable view of an `accepts[]` entry (no nonce; this is long-lived metadata).
  */
 interface SelfDescribeRail {
-    scheme: 'onchain-proof' | 'exact';
+    scheme: 'onchain-proof' | 'exact' | 'upto';
     network: string;
     asset: string;
     payTo: string;
@@ -6201,6 +6414,10 @@ interface SelfDescription {
         openapi: string;
         wellKnown: string;
     };
+    /** Present (and `true`) ONLY when this gate issues verifiable receipts (`receipts` on) —
+     *  so a crawler/agent reading the 402 knows the 200 will carry a self-verifiable
+     *  `extensions['offer-receipt']` receipt. Absent by default (byte-identical). */
+    verifiableReceipts?: true;
     /** A one-line human summary (the gate sets it from `describeChallenge`). */
     instruction?: string;
 }
@@ -6217,6 +6434,9 @@ declare function buildSelfDescription(input: {
      *  byte-identical). Built from the gate's `description`/`mimeType`/`discovery` descriptor
      *  via {@link buildEndpointInfo}. */
     endpoint?: SelfDescribeEndpoint;
+    /** True when the gate's `receipts` option is on — stamps the additive `verifiableReceipts`
+     *  flag so a reader knows the 200 will carry a self-verifiable receipt. */
+    verifiableReceipts?: boolean;
 }): SelfDescription;
 /**
  * Assemble a {@link SelfDescribeEndpoint} from the pieces a gate knows — its
@@ -6269,8 +6489,9 @@ declare function buildEndpointInfo(input: {
  * consumed by every emitter below.
  */
 interface PaymentRail {
-    /** `onchain-proof` (PipRail's default) or the standard `exact` rail (dual-advertise). */
-    scheme: 'onchain-proof' | 'exact';
+    /** `onchain-proof` (PipRail's default), the standard `exact` rail, or the standard `upto`
+     *  (metered) rail (dual-advertise). */
+    scheme: 'onchain-proof' | 'exact' | 'upto';
     network: Caip2;
     asset: AssetId;
     payTo: AddressId;
@@ -6281,6 +6502,11 @@ interface PaymentRail {
     decimals: number;
     symbol?: string;
     maxTimeoutSeconds: number;
+    /** Rail-IDENTITY extra a discoverer needs to reconstruct/route the rail, mirrored from the
+     *  live 402's `accept.extra` — the `upto` rail's MANDATORY `facilitatorAddress`, the `exact`
+     *  rail's EIP-712 domain (`name`/`version`), and the `assetTransferMethod`. Omitted for the
+     *  `onchain-proof` rail (it needs none). The base pricing fields stay top-level on the rail. */
+    extra?: Record<string, unknown>;
 }
 /** One discoverable resource: its URL, how to call it, and how to pay it. */
 interface ResourceDescription {
@@ -6542,6 +6768,43 @@ interface ExactRailOption {
      *  "just works". Force `'eip3009'` or `'permit2'` to pin one. Ignored on Solana (always SVM). */
     method?: 'eip3009' | 'permit2' | 'auto';
 }
+/**
+ * Opt into ALSO advertising a standard x402 `upto` (metered / variable-amount) rail beside the
+ * default `onchain-proof` rail — for usage-billed APIs (pay-per-LLM-token, per-byte, per-query).
+ * The buyer signs a Permit2 authorization for `amount` as a **MAXIMUM**; the merchant serves the
+ * resource, meters the **actual** usage, then **self-settles** `actual ≤ max` through the
+ * canonical `x402UptoPermit2Proxy` from its own `relayer` (which IS the bound `witness.facilitator`
+ * — backendless, no third-party facilitator). **EVM-Permit2 ONLY** (the upto spec bans EIP-3009 and
+ * has no non-EVM variant); native coins and non-Permit2 chains never carry it. Self-settle ONLY in
+ * v1 (no facilitator mode). Omitting `upto` leaves the gate byte-identical to today.
+ *
+ * **⚠ UNSUPPORTED through the Express `requirePayment` middleware** — it settles BEFORE the route
+ * handler serves, so the metered usage isn't known yet; constructing `requirePayment({ upto })`
+ * THROWS. The supported handler shape is a **direct `gate.verify(header)` call** where the metering
+ * happens INSIDE the `settleAmount` callback: serve/compute enough to know usage → `await
+ * gate.verify(header)` whose `settleAmount` returns that usage → write the body + the receipt header.
+ */
+interface UptoRailOption {
+    /** REQUIRED — the gas-paying relayer wallet that settles AND is the bound `witness.facilitator`
+     *  (a `{ key }` or a bring-your-own EVM `{ walletClient }`). Distinct from `payTo`, the receive
+     *  address — though here they MAY be the same key (the proxy binds `witness.to` separately). */
+    relayer: unknown;
+    /**
+     * REQUIRED — the merchant callback that picks the ACTUAL charge AFTER serving (the
+     * deferred-settle lifecycle). Called with the metered context; return a `bigint` (base units),
+     * or a string in the x402 SettlementOverrides forms — raw atomic (`"1858"`), `"NN%"` of the max
+     * (floored), or `"$X"` (rounded to the token's decimals). `"0"`/`0n` ⇒ a zero-charge receipt with
+     * NO on-chain tx. The gate clamps to ≤ the advertised max and rejects-over-max defensively
+     * (`upto_settle_exceeds_max`). On the direct `gate.verify()` path this is where you meter usage.
+     */
+    settleAmount: (ctx: {
+        maxAmount: bigint;
+        asset: string;
+        network: Caip2;
+        decimals: number;
+        request?: unknown;
+    }) => bigint | string | Promise<bigint | string>;
+}
 /**
  * The merchant-side mirror of {@link PaidReceipt}: what an {@link RequirePaymentOptions.onFailed}
  * hook receives when a SUBMITTED payment proof is REJECTED. It carries the SAME machine-readable
@@ -6681,6 +6944,15 @@ interface RequirePaymentOptions {
      * byte-identical).
      */
     exact?: boolean | ExactRailOption;
+    /**
+     * ALSO advertise a standard x402 `upto` (metered / variable-amount) rail — for usage-billed
+     * APIs (pay-per-LLM-token, per-byte, …). Opt-in, EVM-Permit2 ONLY, self-settle ONLY. See
+     * {@link UptoRailOption}. The buyer signs for a MAX; you meter + settle the ACTUAL after serving
+     * via the `settleAmount` callback. **UNSUPPORTED through `requirePayment` (the Express middleware
+     * settles before the route handler serves) — constructing `requirePayment({ upto })` THROWS;** use
+     * a direct `gate.verify()` call and meter inside `settleAmount`. Omitted ⇒ byte-identical to today.
+     */
+    upto?: UptoRailOption;
     /**
      * Make this gate's 402 self-describing for the open indexes — **x402scan REQUIRES
      * an input schema or it won't list the resource.** Set `true` for a no-input GET,
@@ -6700,6 +6972,65 @@ interface RequirePaymentOptions {
      * byte-identical default of before this feature). See {@link buildSelfDescription}.
      */
     selfDescribe?: boolean;
+    /**
+     * Emit a **verifiable receipt** on every settled payment — a self-contained
+     * {@link PipRailReceipt} that the buyer keeps and **anyone** re-verifies against the
+     * chain with only an RPC (no key, no backend, no PipRail account). It rides in an
+     * `extensions['offer-receipt'].info` block on the `PAYMENT-RESPONSE` header (the
+     * chain-grounded record at `info.settlement`; the optional Tier-2 SignedReceipt at the
+     * spec's `info.receipt` slot) and stamps the challenge `nonce` onto the receipt so the five Template-A
+     * (memo/nonce-bound) families re-verify off-chain. **Default off → byte-identical.**
+     *
+     * - `true` / `{}`        → Tier-1 chain-grounded receipt (the settlement tx is the
+     *                          authority — re-verified via the driver's own `verify()`).
+     * - `{ includeTxHash }`  → see {@link ReceiptOption}. Default `true` (PipRail inverts
+     *                          the official privacy-default; the open chain is the pitch).
+     *
+     * Purely additive metadata a standard x402 client ignores; the `accepts[]`, status,
+     * and pay path are unchanged. {@link PipRailClient.verifyReceipt} re-verifies it.
+     */
+    receipts?: boolean | ReceiptOption;
+}
+/** Tuning for the {@link RequirePaymentOptions.receipts} verifiable-receipt emission. */
+interface ReceiptOption {
+    /**
+     * Put the settlement tx hash in the receipt. **Default `true`** — PipRail inverts the
+     * official x402 privacy-default (which omits it) because the whole pitch is the open,
+     * self-verifiable chain. Set `false` for a privacy-minded merchant: the wire
+     * `transaction` becomes the empty string `''` (per spec §5.3, never a missing key) and
+     * the Tier-1 receipt is no longer third-party on-chain-verifiable (it carries no tx to
+     * re-read) — use Tier-2 attestation for that case.
+     */
+    includeTxHash?: boolean;
+    /**
+     * The canonical resource URL to embed in the merchant-emitted receipt (what was paid
+     * for). The buyer's {@link PipRailClient.lastReceipt} also fills this from the URL it
+     * fetched, so set it here only to ground the raw header a third party reads directly.
+     * Default `''` (the buyer's client fills it).
+     */
+    resource?: string;
+    /**
+     * **Tier-2 — service-delivery attestation (OPTIONAL, EVM-only).** When set, the gate
+     * ALSO signs the official x402 `offer-receipt` EIP-712 receipt with the merchant's own
+     * wallet, attesting the one thing the chain can't: that the resource was actually
+     * **served**. A verifier checks `recover(sig) === payTo` — zero new infra, the
+     * merchant's existing `payTo` key. The {@link SignedReceipt} rides at the official
+     * spec slot `extensions['offer-receipt'].info.receipt` (so a stock `@x402/extensions`
+     * reader reads it unchanged); verify with {@link PipRailClient.verifyAttestation}.
+     *
+     * - `{ wallet }` → the merchant's existing payTo key (EIP-712). EVM-only: on a non-EVM
+     *   rail it **degrades to Tier-1 + a one-time warning**, never throws.
+     * - `{ jws }`    → a managed JWS signer (did:web/key) — **R3, not yet implemented**
+     *   (the type slot is reserved). Supplying it today degrades to Tier-1 + a warning.
+     *
+     * Signing failures degrade to the unsigned Tier-1 receipt (isolated exactly like
+     * `onPaid`) — they never fail the 200.
+     */
+    attest?: {
+        wallet: unknown;
+    } | {
+        jws: unknown;
+    };
 }
 type VerifyPaymentResult = {
     kind: 'paid';
@@ -6754,6 +7085,16 @@ interface PaymentGate {
     }>;
     /** Verify an incoming `payment-signature` header value. */
     verify(paymentSignature: string | string[] | undefined): Promise<VerifyPaymentResult>;
+    /**
+     * Verify an already-decoded PaymentPayload OBJECT (raw JSON, not base64) — the
+     * additive seam for non-HTTP transports (A2A carries the payload as raw JSON
+     * `metadata`, never a base64 header). Runs the EXACT SAME dispatch as {@link verify}
+     * (upto → exact → onchain-proof), reading `sig.payload.nonce` from the object exactly
+     * as the HTTP path does — so it adds ZERO new verification state and shares the gate's
+     * one replay set. `verify(b64)` is the base64 path and stays byte-identical; this only
+     * skips the decode. The same `onPaid`/`onFailed` hooks fire.
+     */
+    verifyObject(payload: unknown): Promise<VerifyPaymentResult>;
     /**
      * Describe this gate's payment options as static, nonce-free discovery
      * metadata — feed it to the emitters in `discovery.ts` (`buildOpenApi` /
@@ -7364,6 +7705,101 @@ declare const PERMIT2_WITNESS_TYPES: {
     }];
 };
 
+/**
+ * ── EVM SECTION: x402 `upto` scheme (Permit2) — BUYER + SELLER ────────────────
+ *
+ * The metered / variable-amount counterpart to `permit2.ts`. The x402 `upto` scheme lets
+ * a buyer authorize a MAXIMUM (sign a Permit2 `PermitWitnessTransferFrom` for the ceiling),
+ * and the merchant settle the ACTUAL (≤ max) AFTER serving — billing exactly what was
+ * consumed (LLM tokens, bytes, compute). EVM-Permit2 ONLY (the spec bans EIP-3009, which
+ * fixes the amount at sign time, and has no non-EVM variant).
+ *
+ *   • The payer signs an EIP-712 `PermitWitnessTransferFrom` over the canonical **Permit2**
+ *     contract, with `spender` = the canonical **x402UptoPermit2Proxy** and a **witness**
+ *     `{ to, facilitator, validAfter }` — `facilitator` is the **MIDDLE** field, the one
+ *     delta from the exact Permit2 witness. The buyer never broadcasts (and, after a
+ *     one-time Permit2 approval, spends ~0 gas) — the merchant broadcasts.
+ *   • The merchant SELF-SETTLES by calling the proxy's `settle(permit, amount, owner,
+ *     witness, signature)` — `amount` (position 1) is the ACTUAL (≤ the signed max), and the
+ *     proxy enforces `msg.sender == witness.facilitator` on-chain (`UnauthorizedFacilitator`)
+ *     PLUS `amount <= permit.permitted.amount` (`AmountExceedsPermitted`). So the merchant's
+ *     own relayer IS the bound facilitator — backendless, no third-party facilitator.
+ *
+ * Spec: `specs/schemes/upto/scheme_upto_evm.md` + `contracts/evm/src/x402UptoPermit2Proxy.sol`
+ * (witness type string `Witness(address to,address facilitator,uint256 validAfter)` and the
+ * `settle(...)` arg order both verdict-confirmed against the cloned source). This module
+ * mirrors `permit2.ts` file-for-file (buyer {@link payUptoEvm}; seller
+ * {@link verifyAndSettleUptoEvm}); the EVM driver routes to it via the new upto SPI trio.
+ *
+ * One-time setup is identical to the exact Permit2 rail — the payer `approve(Permit2, max)`
+ * ONCE ({@link ensurePermit2Allowance}, re-used from `permit2.ts`).
+ *
+ * NOT the sponsor-fee-drain class (the relayer broadcasts on EVM and sets gas at broadcast;
+ * the buyer's signed witness carries NO fee field) — add NO MAX_FEE cap, exactly like the
+ * exact-EIP-3009 / exact-Permit2 rails.
+ */
+
+/** Canonical x402UptoPermit2Proxy — the SAME CREATE2 address on every chain where it's been
+ *  deployed (see {@link UPTO_PROXY_CHAIN_IDS}; vanity `…0002`, vs the exact proxy's `…0001`).
+ *  It is the `spender` the buyer signs over and the contract the seller settles through; it
+ *  enforces `transferDetails.to == witness.to`, `msg.sender == witness.facilitator`, and
+ *  `amount <= permit.permitted.amount` on-chain. */
+declare const X402_UPTO_PERMIT2_PROXY: "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002";
+/** EVM chain ids where BOTH the canonical Permit2 AND the x402UptoPermit2Proxy are deployed —
+ *  i.e. where the `upto` scheme can actually settle. Verdict-confirmed on-chain (`eth_getCode`,
+ *  ~3142-byte byte-identical code, 2026-06-20): Ethereum / Base / Arbitrum / Optimism / Polygon
+ *  / BNB. **Avalanche (43114) is NOT deployed (`0x`)** — deliberately OUT. This is INDEPENDENT of
+ *  the exact `PERMIT2_PROXY_CHAIN_IDS` (a separate proxy). The proxy is a permissionless CREATE2
+ *  deploy, so extend this as it lands on more chains (re-verify each with `eth_getCode` first). */
+declare const UPTO_PROXY_CHAIN_IDS: ReadonlySet<number>;
+/** Whether a chain has the x402UptoPermit2Proxy deployed (→ can settle the `upto` scheme). */
+declare function isUptoProxyChain(chainId: number): boolean;
+/**
+ * EIP-712 type set for the x402 `upto` scheme. Identical to {@link PERMIT2_WITNESS_TYPES}
+ * (the exact Permit2 rail) EXCEPT the `Witness` struct carries a `facilitator` field as its
+ * **MIDDLE** member. MUST encode to exactly the type string the proxy reconstructs:
+ *   `PermitWitnessTransferFrom(TokenPermissions permitted,address spender,uint256 nonce,uint256 deadline,Witness witness)TokenPermissions(address token,uint256 amount)Witness(address to,address facilitator,uint256 validAfter)`
+ * (viem orders referenced structs alphabetically → TokenPermissions before Witness ✓.)
+ * **`facilitator` is the MIDDLE field** — get the order wrong and `recoverTypedDataAddress`
+ * silently returns the wrong address → every signature rejects. Verdict-confirmed against
+ * `x402UptoPermit2Proxy.sol` WITNESS_TYPEHASH + the reference `uptoPermit2WitnessTypes`.
+ */
+declare const PERMIT2_UPTO_WITNESS_TYPES: {
+    readonly PermitWitnessTransferFrom: readonly [{
+        readonly name: "permitted";
+        readonly type: "TokenPermissions";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "witness";
+        readonly type: "Witness";
+    }];
+    readonly TokenPermissions: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly Witness: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "facilitator";
+        readonly type: "address";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }];
+};
+
 /**
  * Landing page — a tiny, self-contained HTML representation of a 402, for the HUMAN
  * who opens a gated URL in a browser (agents/crawlers still get the unchanged JSON 402).
@@ -7388,4 +7824,278 @@ declare const PERMIT2_WITNESS_TYPES: {
  */
 declare function renderLandingPage(sd: SelfDescription): string;
 
-export { type AcceptOption, AddressId, type AgentTool, type AlgorandToken, type AptosToken, AssetId, BRAND, BUILTIN_DENOMS, type BazaarExtension, type BuildExactParams, CHAINS, Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type CountStatus, DENOM_PRECISION, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DenomRemaining, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, PaidReceipt, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, SpendLedger, SpendRecord, type SpendRemaining, SpendStore, SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, VerifyErrorCode, type VerifyPaymentResult, VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, X402AcceptEntry, X402AnyAccept, X402Challenge, type X402DnsRecord, X402ExactAcceptEntry, type X402InvalidBody, X402Receipt, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildEndpointInfo, buildExactAuthorization, buildOpenApi, buildSelfDescription, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, denomOf, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseExactRequirements, parseFacilitatorSupported, paymentTools, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+/**
+ * Minimal, DUCK-TYPED Google Agent2Agent (A2A) shapes — the structural surface the
+ * PipRail A2A transport reads/writes, and NOTHING more. Like `ExpressLikeRequest` in
+ * `server.ts`, these declare only the fields the adapter touches, so any A2A runtime's
+ * objects (the official `@a2a-js/sdk`, ADK, or a hand-rolled JSON-RPC handler) satisfy
+ * them structurally — **with ZERO `@a2a` dependency**.
+ *
+ * x402-over-A2A carries PipRail's existing `PaymentRequired`/`PaymentPayload`/
+ * `SettlementResponse` envelopes inside A2A `Task`/`Message` `metadata`, keyed off five
+ * namespaced keys (`x402.payment.{status,required,payload,receipts,error}`), so a
+ * standard A2A reader ignores them and they coexist with any other metadata.
+ *
+ * Verified verbatim against the upstream reference `x402_a2a/types/state.py` and the
+ * x402-foundation `specs/transports-v2/a2a.md` mapping table.
+ */
+
+/** The coarse A2A Task state (the A2A framework's own lifecycle). */
+type A2ATaskState = 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled';
+/** The granular `x402.payment.status` lifecycle field (the payment state machine atop the
+ *  Task state). Per `transports-v2/a2a.md:217-224` + the reference `PaymentStatus` enum. */
+type A2APaymentStatus = 'payment-required' | 'payment-submitted' | 'payment-verified' | 'payment-completed' | 'payment-failed' | 'payment-rejected';
+/** A part of an A2A Message — text, data, or file. Only the fields the adapter reads/writes. */
+interface A2APart {
+    kind?: 'text' | 'data' | 'file' | string;
+    text?: string;
+    data?: unknown;
+    [extra: string]: unknown;
+}
+/** An A2A Artifact — the merchant's served work attached to a completed Task. The adapter
+ *  attaches `fulfill()`'s output here, plus (B7) an optional post-settle error annotation. */
+interface A2AArtifact {
+    artifactId?: string;
+    name?: string;
+    parts?: A2APart[];
+    /** Free-form annotation bag. The B7 fulfill-throws-after-settle edge stamps a post-settle
+     *  error here (NEVER re-challenge / failed) so the buyer sees the work failed AFTER paying. */
+    metadata?: Record<string, unknown>;
+    [extra: string]: unknown;
+}
+/**
+ * The five canonical x402 metadata keys (namespaced `x402.payment.*`) plus structural
+ * tolerance for any other A2A metadata. The shapes are PipRail's EXISTING wire objects —
+ * `x402.payment.required` is a raw `X402Challenge` (NOT base64), `x402.payment.payload` is
+ * a raw PaymentPayload object (fed to the tolerant object-cores via `gate.verifyObject`),
+ * and `x402.payment.receipts` is the append-only history.
+ */
+interface A2AMetadata {
+    'x402.payment.status'?: A2APaymentStatus;
+    'x402.payment.required'?: X402Challenge;
+    /** A raw `X402PaymentSignature` / exact / upto payload object — fed straight into
+     *  `gate.verifyObject` (the tolerant object-cores absorb v1+v2). */
+    'x402.payment.payload'?: unknown;
+    /**
+     * B7: append-only settlement history. The element type is the UNION because the array
+     * MUST include FAILED attempts (`spec v0.1:281`) — and `X402Receipt.success` is the literal
+     * `true`, so a failed entry can only be a `SettleOutcome { success:false, errorReason }`.
+     */
+    'x402.payment.receipts'?: (X402Receipt | SettleOutcome)[];
+    /** The error code on a settlement-side failure (`x402.payment.error`). */
+    'x402.payment.error'?: string;
+    [extra: string]: unknown;
+}
+/** An inbound/outbound A2A Message. The submission carries the payload + the original
+ *  `taskId` for correlation (`v0.1 spec.md:163`). Only the fields the adapter touches. */
+interface A2AMessage {
+    kind?: 'message';
+    role?: string;
+    /** Correlates a follow-up payment submission to its in-flight payment Task. */
+    taskId?: string;
+    messageId?: string;
+    parts?: A2APart[];
+    metadata?: A2AMetadata;
+    [extra: string]: unknown;
+}
+/** An A2A Task — the merchant's response carrying the payment state in `status.message.metadata`. */
+interface A2ATask {
+    kind?: 'task';
+    id: string;
+    status: {
+        state: A2ATaskState;
+        message?: A2AMessage;
+    };
+    artifacts?: A2AArtifact[];
+    [extra: string]: unknown;
+}
+/**
+ * An AgentCard extension declaration — what the merchant stamps into its
+ * `AgentCard.capabilities.extensions[]` to advertise the x402 extension (§2.4). A client
+ * opts in by sending `X-A2A-Extensions: <uri>`; `required: true` rejects un-activated callers.
+ */
+interface A2AExtensionDeclaration {
+    uri: string;
+    description?: string;
+    required?: boolean;
+    params?: Record<string, unknown>;
+}
+/**
+ * A bounded, pluggable TRANSPORT-LIFECYCLE store — NOT a backend, NOT on the verification
+ * path, holds NO security state (B4). It correlates a follow-up `message/send` to its
+ * in-flight Task and accumulates the append-only `receipts[]` history. The buyer carries
+ * the challenge nonce in its payload; `gate.verify`/`gate.verifyObject` re-derive every
+ * trusted field from the merchant's own config (`server.ts` client-echoed nonce), so even
+ * a poisoned/empty store can never redirect funds or reject a valid payment. Same posture
+ * as the gate's in-memory replay set — a bounded Map inside the merchant's own process.
+ */
+interface A2ATaskStore {
+    get(taskId: string): A2ATaskRecord | undefined;
+    set(taskId: string, value: A2ATaskRecord, ttlMs: number): void;
+}
+/** What a {@link A2ATaskStore} holds per task — the receipt history ONLY (no nonce-as-security). */
+interface A2ATaskRecord {
+    receipts?: (X402Receipt | SettleOutcome)[];
+}
+
+/**
+ * x402-over-A2A — the SELLER-side transport adapter (Google Agent2Agent).
+ *
+ * A2A is x402's third official transport (alongside HTTP and MCP). It carries PipRail's
+ * BYTE-IDENTICAL `PaymentRequired`/`PaymentPayload`/`SettlementResponse` envelopes inside
+ * A2A `Task`/`Message` JSON-RPC `metadata` (five namespaced `x402.payment.*` keys) keyed
+ * off a coarse A2A Task state — instead of base64 HTTP headers. It is a thin codec + adapter
+ * ABOVE the `PaymentDriver` boundary: ZERO driver changes, ZERO scheme changes, ZERO chain
+ * changes — all 10 chain families work over A2A for free, exactly as they work over HTTP.
+ *
+ * This module imports ONLY `server.ts`/`x402.ts` types + `errors.ts` (the same surface as
+ * the Express adapter) — NO `viem`, NO chain SDK. It never touches a chain.
+ *
+ * ── Charter-critical invariants ───────────────────────────────────────────────
+ *  • Defaults byte-identical: a root install that never imports A2A loads nothing extra.
+ *  • B4 — NO new verification state: the buyer carries the challenge nonce in its payload;
+ *    `gate.verifyObject` reads `sig.payload.nonce` exactly as HTTP does, and the gate
+ *    re-derives every trusted field from the merchant's own config. The `A2ATaskStore` is
+ *    transport task-lifecycle ONLY (receipt history), never on the verification path.
+ *  • B5 — HTTP and A2A MUST share ONE replay set: `createA2APaymentHandler` takes an
+ *    EXISTING `PaymentGate` (the primary, ergonomic form). A co-resident HTTP gate that
+ *    builds a SEPARATE gate must share `isUsed`/`markUsed`, or a proof settled over one
+ *    transport can be replayed over the other.
+ *  • B7 — `receipts[]` is the UNION `(X402Receipt | SettleOutcome)[]` (it carries FAILED
+ *    attempts); a fulfill-throws-AFTER-settle ends the Task `completed` with the successful
+ *    receipt + an error annotation (NEVER re-challenge / failed — the money already moved).
+ *  • Emit `x402Version: 2` — RESOLVED 2026-06-21: v2 IS the live x402 standard. A live cross-check
+ *    against Google's official libs (reproducible harness in `examples/a2a-interop/`) showed the canonical
+ *    `x402` lib (2.13.1, V2: `amount` / CAIP-2 / nested `accepted`) parses our PaymentRequired +
+ *    PaymentPayload byte-identically, while the legacy v0.1 `x402_a2a` package (x402Version 1,
+ *    `maxAmountRequired`, chain slugs) is bitrotted. Inbound v1 object-cores are absorbed for the
+ *    standard `exact` scheme; PipRail-native `onchain-proof` is always v2 (never sent v1-flat).
+ *  • Merchant statuses are spec-bounded: `payment-required` (incl. a retryable re-challenge of a
+ *    rejected proof) / `payment-completed` / `payment-failed`. `payment-rejected` + `payment-submitted`
+ *    are CLIENT→merchant statuses we never emit.
+ *
+ * ── DEFERRED (NOT built here — see the x402-parity/03-a2a-transport plan) ──────
+ *  • Phase 4 — the A2A BUYER (`A2APayer`): the HTTP buyer mints the payload that rides A2A today.
+ *  • Phase 5 — AP2 `CartMandate`/`PaymentMandate` carriage (the Embedded Flow; no mandate-trust machinery).
+ *  • B8 ship-gate — RESOLVED at the wire level (above). A live `adk-demo` AGENT run is blocked by that
+ *    package's dependency bitrot (won't import on current `x402`/`a2a-sdk`), not by PipRail.
+ */
+
+/** The x402 A2A extension URI the x402-foundation doc + ALL Google reference code cite
+ *  (`config.py:23`, `version="0.1"`). The seller's default — activation is exact-string match. */
+declare const A2A_X402_EXTENSION_URI_V01 = "https://github.com/google-a2a/a2a-x402/v0.1";
+/** The newer v0.2 URI (`spec/v0.2/spec.md:11`) — for AP2 Embedded-Flow targets (Phase 5, deferred). */
+declare const A2A_X402_EXTENSION_URI_V02 = "https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2";
+/** The five canonical metadata keys (verbatim from `x402_a2a/types/state.py:33-37`). */
+declare const A2A_STATUS_KEY = "x402.payment.status";
+declare const A2A_REQUIRED_KEY = "x402.payment.required";
+declare const A2A_PAYLOAD_KEY = "x402.payment.payload";
+declare const A2A_RECEIPTS_KEY = "x402.payment.receipts";
+declare const A2A_ERROR_KEY = "x402.payment.error";
+/** The HTTP activation header a client sends to opt into the extension (§2.4). */
+declare const A2A_EXTENSIONS_HEADER = "X-A2A-Extensions";
+/**
+ * Map PipRail's lowercase {@link VerifyErrorCode} to the spec's screaming-snake error enum
+ * (`errors.py:148-157` / spec §8.1) for `x402.payment.error`. We ALSO emit the raw PipRail
+ * code (in the re-challenge's `extensions.piprail`), so nothing is lost and a buyer agent
+ * branches identically across transports. Codes with no spec analogue map to `SETTLEMENT_FAILED`
+ * only when they're settlement-side; rejection codes keep their nearest enum member.
+ */
+declare const VERIFY_CODE_TO_A2A_ERROR: Record<string, string>;
+/** Translate a PipRail verify/settle code to the A2A error enum (falls back to the raw code). */
+declare function toA2AErrorCode(code: string): string;
+/**
+ * Build the `input-required` payment-request Task carrying the challenge as RAW JSON
+ * (NOT base64) in `x402.payment.required` + `x402.payment.status = 'payment-required'`.
+ * `parts` are any human-readable message parts the merchant wants alongside it.
+ */
+declare function toA2APaymentRequired(taskId: string, challenge: X402Challenge, parts?: A2APart[]): A2ATask;
+/** Build the `x402.payment.receipts` metadata block (an ARRAY, append-only, B7 union). */
+declare function toA2APaymentReceipts(receipts: (X402Receipt | SettleOutcome)[]): A2AMetadata;
+/**
+ * Build the `payment-failed` metadata for a SETTLEMENT-side failure (the money never moved):
+ * the A2A error code + a `{ success:false, errorReason }` receipt appended to the history (B7).
+ */
+declare function toA2APaymentFailed(code: VerifyErrorCode | string, detail: string, receipts?: (X402Receipt | SettleOutcome)[], network?: string): A2AMetadata;
+/** Read the `X402Challenge` back out of a payment-request Task's metadata (raw JSON). */
+declare function fromA2APaymentRequired(task: A2ATask): X402Challenge | null;
+/**
+ * Read the inbound RAW payment payload object + its correlating `taskId` out of a
+ * `message/send`. The raw object is fed straight into `gate.verifyObject` (the tolerant
+ * object-cores absorb v1+v2). Returns `null` when there's no payload metadata.
+ */
+declare function fromA2APaymentPayload(message: A2AMessage): {
+    raw: unknown;
+    taskId: string;
+} | null;
+/** Options for {@link createA2APaymentHandler}. */
+interface A2APaymentHandlerOptions extends Partial<RequirePaymentOptions> {
+    /**
+     * B5 (MANDATORY cross-transport replay): pass the SAME {@link PaymentGate} instance the
+     * HTTP path uses, so both transports share ONE replay set (`localUsed` / injected
+     * `isUsed`/`markUsed`). This is the PRIMARY, ergonomic form. If omitted, a fresh gate is
+     * built from the inline `RequirePaymentOptions` — and a co-resident HTTP gate MUST then
+     * share `isUsed`/`markUsed`, or a proof settled over one transport can be replayed over
+     * the other.
+     */
+    gate?: PaymentGate;
+    /**
+     * A bounded, pluggable TRANSPORT-lifecycle store (B4) — correlate a follow-up
+     * `message/send` to its in-flight Task + accumulate the append-only `receipts[]`. It is
+     * NOT on the verification path and holds NO nonce-as-security-state (the buyer carries the
+     * nonce in its payload). Default = an in-memory TTL Map (same bound as the replay set).
+     * NOT a backend PipRail hosts.
+     */
+    taskStore?: A2ATaskStore;
+    /** TTL (ms) for the default task store. Default = `maxTimeoutSeconds * 1000` (the replay window). */
+    taskTtlMs?: number;
+    /**
+     * Produce the served result Artifact(s) for a settled task — the merchant's own work (the
+     * image, the JSON, …). Charter-safe: like an Express route handler that runs after `next()`.
+     * Omit for a metadata-only "payment accepted" completion. **B7: if this THROWS after a
+     * successful settle, the Task still completes `completed` carrying the success receipt + an
+     * error annotation — the buyer is NEVER told to re-pay an already-settled proof.**
+     */
+    fulfill?: (ctx: {
+        taskId: string;
+        receipt: X402Receipt;
+        message: A2AMessage;
+    }) => Promise<A2AArtifact[]> | A2AArtifact[];
+}
+/** The seller handler returned by {@link createA2APaymentHandler}. */
+interface A2APaymentHandler {
+    /**
+     * Process one inbound A2A message and return the next Task. Outcomes mirror
+     * `gate.verify()`'s `VerifyPaymentResult` exactly:
+     *  - no payload yet            → Task `input-required` + `x402.payment.required`
+     *  - payload, verified+settled → Task `completed` + `x402.payment.receipts` + artifacts
+     *  - payload, rejected         → Task `input-required` re-challenge (RETRYABLE)
+     *  - settle threw (relayer)    → Task `failed` + `x402.payment.error`  (NOT retryable)
+     *  - settle OK but fulfill threw → Task `completed` + receipt + error annotation (B7)
+     */
+    handleMessage(message: A2AMessage, taskId?: string): Promise<A2ATask>;
+    /** Stamp the x402 extension into an AgentCard's `capabilities.extensions` (§2.4). */
+    agentCardExtension(opts?: {
+        required?: boolean;
+        version?: 'v0.1' | 'v0.2';
+    }): A2AExtensionDeclaration;
+    /** The underlying gate — escape hatch for advanced flows (`describe()`, `landingPage()`). */
+    readonly gate: PaymentGate;
+}
+/**
+ * The A2A analogue of `requirePayment` — wrap a {@link PaymentGate} and map A2A messages ⇄
+ * x402 task metadata. The merchant plugs `handleMessage` into their A2A agent's
+ * `message/send` handler and pushes `agentCardExtension()` into their AgentCard.
+ *
+ * @example
+ * ```ts
+ * import { createPaymentGate, createA2APaymentHandler } from '@piprail/sdk'
+ *
+ * const gate = createPaymentGate({ chain: 'base', token: 'USDC', amount: '0.05', payTo: '0x…' })
+ * const pay = createA2APaymentHandler({ gate, fulfill: async () => [{ name: 'result', parts: [{ kind: 'text', text: 'done' }] }] })
+ * a2aAgent.on('message/send', ({ message, taskId }) => pay.handleMessage(message, taskId))
+ * ```
+ */
+declare function createA2APaymentHandler(options: A2APaymentHandlerOptions): A2APaymentHandler;
+
+export { type A2AArtifact, type A2AExtensionDeclaration, type A2AMessage, type A2AMetadata, type A2APart, type A2APaymentHandler, type A2APaymentHandlerOptions, type A2APaymentStatus, type A2ATask, type A2ATaskRecord, type A2ATaskState, type A2ATaskStore, A2A_ERROR_KEY, A2A_EXTENSIONS_HEADER, A2A_PAYLOAD_KEY, A2A_RECEIPTS_KEY, A2A_REQUIRED_KEY, A2A_STATUS_KEY, A2A_X402_EXTENSION_URI_V01, A2A_X402_EXTENSION_URI_V02, type AcceptOption, AddressId, type AgentTool, type AlgorandToken, type AptosToken, AssetId, BRAND, BUILTIN_DENOMS, type BazaarExtension, type BuildExactParams, CHAINS, Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type CountStatus, DENOM_PRECISION, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DenomRemaining, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_UPTO_WITNESS_TYPES, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, PaidReceipt, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, Permit2UptoPaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, PipRailReceipt, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, type ReceiptInput, type ReceiptOption, type ReceiptVerification, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, SettleOutcome, type SettleViaFacilitatorInput, SettlementError, SignedReceipt, type SolanaToken, SpendLedger, SpendRecord, type SpendRemaining, SpendStore, SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UPTO_PROXY_CHAIN_IDS, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type UptoRailOption, VERIFY_CODE_TO_A2A_ERROR, VerifyErrorCode, type VerifyPaymentResult, VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, X402AcceptEntry, X402AnyAccept, X402Challenge, type X402DnsRecord, X402ExactAcceptEntry, type X402InvalidBody, X402Receipt, X402UptoAcceptEntry, X402_EXACT_PERMIT2_PROXY, X402_UPTO_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildEndpointInfo, buildExactAuthorization, buildOpenApi, buildSelfDescription, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createA2APaymentHandler, createPaymentGate, decorateOutcome, deliverReceipt, denomOf, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, fromA2APaymentPayload, fromA2APaymentRequired, getDirectoryInfo, isPermit2ProxyChain, isUptoProxyChain, knownFacilitatorsFor, normalizeNetwork, parseExactRequirements, parseFacilitatorSupported, paymentTools, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toA2AErrorCode, toA2APaymentFailed, toA2APaymentReceipts, toA2APaymentRequired, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };