@piprail/sdk 1.15.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,10 +21,6 @@
   "files": [
     "dist",
     "README.md",
-    "CHAINS.md",
-    "ERRORS.md",
-    "STANDARDS.md",
-    "DISCOVERY.md",
     "CHANGELOG.md",
     "LICENSE"
   ],

package/CHAINS.md

@@ -1,179 +0,0 @@
-# Chain support & per-chain setup
-
-PipRail works the same way on every chain — `requirePayment({ chain, token, amount, payTo })`
-to charge, `new PipRailClient({ chain, wallet }).fetch(url)` to pay. But the chains
-themselves differ, and a few have **setup steps you must do before a wallet can pay or
-receive**. This page is the exact list.
-
-**Most chains need nothing special.** The ones with caveats are **NEAR**, **TON**,
-**Stellar**, **XRPL**, **Tron**, and **Algorand** (USDC needs a one-time ASA opt-in) —
-read those sections before you ship them.
-
-## At a glance
-
-| Chain(s) | Pay in native coin? | Built-in stablecoins | Receiver needs setup? | Wallet input |
-|---|:--:|---|---|---|
-| **EVM** (Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, Mantle, Sonic, Linea, Scroll, Celo, zkSync, Unichain, World Chain, Sei, Injective, HyperEVM, Monad, Kaia, + any EVM chain) | ✅ ETH/BNB/POL/… | USDC (all **except Kaia**) · USDT (all **except Base, World Chain, Sei, HyperEVM, Monad**) · **EURC** (Ethereum, Base, Avalanche) | No | `{ privateKey }` |
-| **Solana** | ✅ SOL | USDC · USDT | No (payer creates the recipient's token account) | `{ secretKey }` |
-| **Sui** | ✅ SUI | USDC (no USDT) | No | `{ privateKey }` (`suiprivkey1…`) |
-| **Aptos** | ✅ APT | USDC · USDT | No (primary FA store auto-creates) | `{ privateKey }` (`ed25519-priv-0x…`) |
-| **Algorand** | ✅ ALGO | **USDC only** (Tether deprecated USDT) | USDC: ⚠️ **ASA opt-in** · **native ALGO: none** | `{ mnemonic }` (25 words) |
-| **Stellar** | ✅ XLM | USDC · EURC | ⚠️ **Yes — trustline + funded account** | `{ secret }` (`S…`) |
-| **XRP Ledger** | ✅ XRP | USDC · RLUSD (no USDT) | ⚠️ **Yes — trustline + activated account** | `{ seed }` (`s…`) |
-| **TON** | ✅ TON | **USD₮ only** (no USDC) | No (payer's gas auto-deploys the jetton wallet) | `{ mnemonic }` (24 words) |
-| **Tron** | ✅ TRX | **USD₮ only** (no USDC) | No | `{ privateKey }` |
-| **NEAR** | ✅ NEAR | USDC · USDT | tokens: ⚠️ `storage_deposit` · **native NEAR: none** | `{ accountId, privateKey }` |
-
-> **`token: 'native'`** (paying in the chain's own coin) is accepted on **every family** —
-> EVM, Solana, Sui, Aptos, Algorand, Stellar, XRPL, TON, NEAR, **and Tron** (native TRX,
-> digest-bound). No exceptions. On NEAR, native is the **zero-setup** path: no `storage_deposit`,
-> and a transfer even creates a fresh recipient (the NEP-141 token path still needs
-> `storage_deposit`).
->
-> **Custom tokens** work everywhere with no allowlist: EVM `{ address, decimals }` ·
-> Solana `{ mint, decimals }` · Sui `{ coinType, decimals }` · Aptos `{ metadata, decimals }` ·
-> Algorand `{ assetId, decimals }` · TON `{ master, decimals }` ·
-> Tron `{ address, decimals }` · NEAR `{ contractId, decimals }` · Stellar
-> `{ issuer, code, decimals }` · XRPL `{ issuer, currencyHex, decimals }`.
-
-**Universal:** the public default RPC on every chain is rate-limited — **pass your own
-`rpcUrl`** in production (there's no separate API-key field; fold any key into the URL).
-
----
-
-## Chains with no caveats
-
-### EVM — Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, …
-- **Pay in:** native coin (`'native'`), `'USDC'`, `'USDT'`, `'EURC'` (where issued), or a custom `{ address, decimals }`.
-- **USDT gap:** built in on every preset **except Base, World Chain, Sei, HyperEVM, and Monad** (USDC only there). **Kaia** is the inverse — **USD₮ only** (no Circle-native USDC on Kaia).
-- **EURC:** Circle's euro stablecoin is built in on **Ethereum, Base, and Avalanche** (EIP-3009, 6-dp, addresses verified on-chain). Its EIP-712 domain name differs per deployment (`"Euro Coin"` on Ethereum/Avalanche, `"EURC"` on Base) — the SDK reads it on-chain, so `exact` payments are correct everywhere. Like USDC, it's `exact`-payable.
-- **Decimals:** on **BNB Chain**, Binance-Peg USDC/USDT are **18 decimals**, not 6 (the SDK handles it; don't hardcode 6).
-- **Stablecoin provenance — issuer-native vs bridged (every shipped address verified on-chain 2026-06-08, incl. bridge markers).** Every address is the correct, canonical, 1:1-redeemable dollar token on its chain; what varies is *who issues it*. You request it as `'USDC'` / `'USDT'` either way — provenance matters only if you specifically require issuer-native settlement.
-  - **USDC** is **Circle-native** on every preset **except** **BNB** (Binance-Peg, 18-dp), **Mantle** (OP canonical-bridge), and **Scroll** (Bridged-USDC-Standard) — the last two are backed 1:1 by Circle USDC on Ethereum but are **not** Circle-issued on that chain (absent from Circle's native-USDC list).
-  - **USDT** is **Tether-native** on **Ethereum, Avalanche, Celo, Kaia** (EVM) and **Solana, Tron, TON, NEAR, Aptos** (non-EVM). Everywhere else it's bridged: **USDT0** (LayerZero omnichain, on-chain `symbol()` = `USD₮0`) on **Arbitrum, Polygon, Unichain**; a **canonical-bridge** token (chain-minted, backed by Tether's Ethereum USDT — not Tether-issued) on **Optimism, zkSync, Sonic, Linea, Injective, Mantle, Scroll**; and **Binance-Peg** (18-dp) on **BNB**. The on-chain `symbol()` may read `USDT`, `USD₮`, `USDt`, or `USD₮0`; all resolve via `token: 'USDT'`.
-- **Receiver setup:** none — any `0x…` address receives ERC-20 or native immediately.
-- **Any other EVM chain:** pass a viem `Chain` or `{ id, rpcUrl }` + `token: { address, decimals }`.
-
-### Solana
-- **Pay in:** `'native'` (SOL), `'USDC'`, `'USDT'`, or `{ mint, decimals }`.
-- **Receiver setup:** none — the payer's transaction idempotently creates the recipient's token account and pays its ~0.00204 SOL rent. **Pass the recipient's wallet address as `payTo`, not a token-account address.**
-- **Payer:** needs SOL for gas + a funded source token account for the SPL token.
-
-### Sui
-- **Pay in:** `'native'` (SUI), `'USDC'`, or `{ coinType, decimals }`. **No built-in USDT** (only Wormhole-bridged exists — supply it as a custom coin if needed).
-- **Receiver setup:** none — any `0x…` (32-byte) Sui address receives immediately.
-- **Payer:** needs SUI for gas even when paying USDC, and must already hold a coin object of the asset.
-
----
-
-## ⚠️ Chains with caveats — read before shipping
-
-### NEAR — native is zero-setup; tokens need `storage_deposit`
-- **Native NEAR works and is the easy path.** `token: 'native'` pays in NEAR (24dp) via
-  digest-binding (like EVM/Solana/Sui) — **no `storage_deposit`, no receiver setup**, and a
-  transfer even **creates a fresh implicit recipient**. Use it when price volatility is fine
-  and you want zero setup. *(NEAR is the volatile gas coin; for stable pricing pay in a token.)*
-- **Tokens (USDC/USDT/custom NEP-141) need `storage_deposit` (NEP-145).** Before an account
-  can *receive* a token, it must be storage-registered on **that exact token contract** — a
-  one-time ~0.00125 NEAR call, **per account per token** (else the payer's `ft_transfer`
-  panics). Both the **merchant (`payTo`)** and the **payer** must be registered on the token.
-  Pay in a token via `'USDC'`, `'USDT'`, or a custom `{ contractId, decimals }`.
-- **Wallet:** `{ accountId, privateKey }` — NEAR needs *both* an account id and an `ed25519:…` secret key (not just a private key).
-- **Implicit accounts** (64-hex) don't exist until funded with NEAR — fund the account first (a native payment to one *creates* it).
-- **Built-in USDC is Circle's native contract** (`17208628…36133a1`), **not** the bridged `…factory.bridge.near` (USDC.e). Don't confuse them.
-- **Do not route through NEAR Intents/solvers** — that re-introduces a third-party facilitator. PipRail uses plain transfers + local receipt verification on purpose.
-
-### TON — USD₮ (or native TON), and you need an API-keyed RPC
-- **Built-in token is USD₮ only** — **native USDC does not exist on TON** (Circle doesn't issue it; `token: 'USDC'` throws). Pay in `'USDT'`, `'native'` (Toncoin), or a custom jetton `{ master, decimals }`.
-- **An RPC API key is effectively required.** The default keyless toncenter endpoint is rate-limited (~1 req/s) and will stall `confirm()`/`verify()` (they poll + read archival history). Use a keyed, archival-capable endpoint and **put the key in the URL**:
-  ```ts
-  requirePayment({ chain: 'ton', token: 'USDT', amount: '0.05', payTo,
-    rpcUrl: 'https://toncenter.com/api/v2/jsonRPC?api_key=YOUR_KEY' })
-  ```
-  (Free keys: message **@tonapibot** on Telegram, or sign up at toncenter.com.)
-- **Receiver setup:** none — the payer's attached gas (~0.05 TON, leftover refunded) auto-deploys the merchant's jetton wallet on first receipt. The payer needs Toncoin for gas even when paying USD₮.
-- **Async settlement:** value crosses contracts, so a credit can take seconds to appear; the proof is a locator (`ton:<jetton-wallet>|<nonce>`), not a tx hash, and the nonce rides in the transfer comment to bind it.
-- **Wallet:** a 24-word `{ mnemonic }` (or `{ keyPair }`), wallet version `v4` (default) or `v5r1` — must match the version your funded address was created with.
-
-### Tron — USD₮ (or native TRX), and gas is real money
-- **Pay in:** `'USDT'` (built in), **`'native'` (TRX, digest-bound)**, or a custom TRC-20 `{ address, decimals }`. **No built-in USDC** (Circle discontinued native USDC on Tron). USD₮ is the default (TRX is volatile gas); native TRX is there for completeness — a plain TransferContract, verified by txid + recency + single-use.
-- **Gas is expensive and paid in TRX.** A USD₮ transfer burns Energy (~30k unstaked ≈ several TRX). The payer must hold **TRX as well as USDT**. Use `client.estimateCost(url)` to budget payment + TRX gas. (Tip for tiny test sends: rent energy from a service like TronZap/feee.io for ~1–2 TRX instead of burning ~27.) A first **native** TRX payment to a brand-new recipient also pays Tron's ~1 TRX account-creation fee (sender side).
-- **Finality is slow-ish:** verification waits for the tx to solidify (~19 blocks, ~57s); until then it reads as `tx_not_found` and is retried.
-- **Wallet:** `{ privateKey }` (32-byte hex, same format as EVM); addresses are Base58 `T…`.
-
-### Algorand — USDC needs a one-time ASA opt-in (native ALGO doesn't)
-- **Pay in:** `'native'` (ALGO, the zero-setup path), `'USDC'`, or a custom ASA `{ assetId, decimals }`. **USDC only for the stablecoin** — Tether deprecated/froze USDT on Algorand (2025-09-01), so it's not built in (pass it as a custom ASA if you must).
-- **Receiving USDC needs an ASA opt-in.** Before an account can *receive* USDC (ASA `31566704`) — or any ASA — it must **opt into that asset** once: a 0-amount asset-transfer to itself, which raises its minimum balance by 0.1 ALGO (locked, recoverable). No opt-in → the payment fails and PipRail returns `RECIPIENT_NOT_READY`. **Native ALGO needs no opt-in.** The payer is implicitly opted-in if it already holds USDC. The one-time opt-in is plain `algosdk` (PipRail stays a payments SDK, not a wallet manager):
-  ```ts
-  import algosdk from 'algosdk'
-  const algod = new algosdk.Algodv2('', 'https://mainnet-api.algonode.cloud', '')
-  const sp = await algod.getTransactionParams().do()
-  const optIn = algosdk.makeAssetTransferTxnWithSuggestedParamsFromObject({
-    sender: account.addr, receiver: account.addr, amount: 0, assetIndex: 31566704, suggestedParams: sp,
-  })
-  await algod.sendRawTransaction(optIn.signTxn(account.sk)).do() // one-time, per account per ASA
-  ```
-- **Fast + cheap:** ~3s single-step finality, flat 0.001 ALGO min fee. The challenge nonce rides in the transaction's **note field** (Template A), so the proof is bound to its challenge; verify reads the merchant account's inbound transfers via the indexer.
-- **x402:** Algorand's `exact` scheme is part of the official x402 standard, but the incumbent on-chain path uses a hosted **facilitator** — PipRail is the **backendless, no-facilitator** option (payer broadcasts, merchant verifies locally).
-- **Wallet:** `{ mnemonic }` (a 25-word Algorand recovery phrase) or `{ account }` (an algosdk `{ addr, sk }`).
-- **Endpoints:** `rpcUrl` overrides the **algod** endpoint (submit/params); the verify-side **indexer** uses the public AlgoNode default (override needs are rare; the public indexer is production-grade for the inbound-transfer read).
-
-### Stellar — the receiver needs a trustline + a funded account
-- **Pay in:** `'native'` (XLM), `'USDC'`, `'EURC'`, or a custom `{ issuer, code, decimals }`.
-- **Receiving an issued asset needs a one-time TRUSTLINE.** The merchant (`payTo`) must (1) **exist** on-chain (funded above the ~1 XLM base reserve) and (2) hold a **trustline** (`changeTrust`) for that exact `code+issuer` *before* it can receive. No trustline → the payment fails. Each trustline locks **+0.5 XLM** of reserve. The **payer** likewise needs its own trustline to hold/send the asset.
-- **Accounts must exist:** this driver sends a payment, it does **not** create accounts — both ends must already be funded above reserve.
-- **Reserves are locked, not spent** — recoverable.
-- **Wallet:** `{ secret }` (an `S…` Ed25519 seed) or `{ keypair }`.
-
-### XRP Ledger — the receiver needs activation + a trustline
-- **Pay in:** `'native'` (XRP), `'USDC'`, `'RLUSD'`, or a custom `{ issuer, currencyHex, decimals }`. **No built-in USDT** on XRPL.
-- **Receiving an IOU needs activation + a TRUSTLINE.** The merchant (`payTo`) must be an **activated** account (holding the ~1 XRP base reserve) **and** hold a **trustline** to the issuer's currency before its first IOU payment — otherwise it fails. Native XRP needs no trustline. The payer must be activated + trustlined too.
-- **Reserves locked, not spent** (~1 XRP base + an owner reserve per trustline) — recoverable.
-- **RLUSD** requires a DestinationTag; the SDK sets a nonce-derived one automatically.
-- **Wallet:** `{ seed }` (an `s…` family seed) or `{ wallet }`.
-
----
-
-## Errors you'll see — and what they actually mean
-
-A payment that "won't go through" is almost always a **chain requirement**, not an SDK bug.
-PipRail maps every such case to a typed error (stable `.code`) with a plain-language fix, and
-**echoes the raw chain code** in the message + keeps the original on `err.cause`. The two you'll
-meet in practice:
-
-**`INSUFFICIENT_FUNDS`** — the **payer** can't cover it → fund the payer (token, native gas, or
-the chain's reserve).
-
-**`RECIPIENT_NOT_READY`** — the **recipient** (`payTo`) isn't set up to receive on this chain yet.
-Fix the *recipient*, not the payer:
-
-| You see (raw → mapped) | Chain | What it means | Fix |
-|---|---|---|---|
-| `tecNO_DST_INSUF_XRP` / `tecNO_DST` | XRPL | the `payTo` account isn't activated (an XRPL account needs ≥1 XRP base reserve to exist) | send the recipient ≥1 XRP to activate it |
-| `tecNO_LINE` / `tecPATH_DRY` | XRPL | recipient has no trustline for the IOU (USDC/RLUSD) | add the trustline on the recipient |
-| `tecDST_TAG_NEEDED` | XRPL | recipient requires a DestinationTag (PipRail sets one automatically) | — |
-| `op_no_destination` | Stellar | the `payTo` account doesn't exist | create it with ≥1 XLM (base reserve) |
-| `op_no_trust` | Stellar | recipient has no trustline for the asset | add the trustline (+0.5 XLM reserve) |
-| `… is not registered` | NEAR | recipient isn't `storage_deposit`-registered on the token | call `storage_deposit` once (~0.00125 NEAR) |
-| `must optin` / `asset … missing from <payTo>` | Algorand | recipient hasn't opted into the USDC ASA | opt the recipient into the ASA once (0-amount self-transfer, +0.1 ALGO min balance) |
-
-Everything else (EVM, Solana, Sui, Tron, native TON/NEAR) needs no recipient setup, so you'll
-only ever see `INSUFFICIENT_FUNDS` there if the payer is short. Full taxonomy: **[ERRORS.md](./ERRORS.md)**.
-
----
-
-## How the proof is bound (for the security-curious)
-
-Every chain proves the *same* facts locally (succeeded · recent · moved ≥ amount of the
-right asset to `payTo`), but binds the proof to your challenge differently:
-
-- **Memo-bound** (the challenge nonce is written on-chain): **NEAR tokens** (ft_transfer
-  memo), **TON** (transfer comment), **Stellar** (`MEMO_HASH = sha256(nonce)`), **XRPL**
-  (Memo + a derived DestinationTag), **Algorand** (the transaction's note field — native ALGO
-  and USDC alike).
-- **Digest-bound** (no on-chain nonce; the proof is the tx id, made single-use by the gate
-  + a recency window): **EVM**, **Solana**, **Sui**, **Aptos**, **Tron**, and **native NEAR**. For
-  these, a persistent `isUsed`/`markUsed` store + a tight `maxTimeoutSeconds` are
-  load-bearing in multi-instance deployments (the default used-set is single-process).
-
-(So NEAR uses *both*: its NEP-141 token path is memo-bound, while native NEAR is digest-bound.)

package/DISCOVERY.md

@@ -1,420 +0,0 @@
-# PipRail discovery — the complete reference
-
-How a PipRail user — a human merchant **or** an AI agent — becomes **discoverable**, and how an
-agent **finds** payable resources. This is the single source of truth for the discovery feature.
-Companion docs: [README.md](./README.md) (the full API), [STANDARDS.md](./STANDARDS.md) (how it's
-built), [ERRORS.md](./ERRORS.md) (the error model). Background research lives in
-`.claude/research/x402-discovery.md` (the "what is this") and `x402-discovery-integration.md` (the
-"exactly how").
-
-> **One line:** PipRail makes you discoverable by building on the **open** x402 indexes that already
-> exist (402 Index, the CDP Bazaar read API, x402scan) — **it hosts nothing of its own**: no
-> registry, no database, no backend, no fee. Every piece is opt-in; the pay path is untouched.
-
-> **⚠️ Status: EXPERIMENTAL.** Discovery integrates with **third-party** open indexes whose wire
-> shapes are a moving, unratified convention — treat this whole layer as experimental and expect to
-> re-verify the integration over time. The **read** path + the **402 Index register** flow are
-> live-verified (see the log in §10); **x402scan SIWX is not yet live-tested** — exercise it against
-> x402scan before relying on it. The pay path and the rest of the SDK are stable; only this layer
-> carries the experimental flag.
-
----
-
-## 1. The problem (discovery is NOT part of x402)
-
-The x402 protocol answers exactly one question: *"how do I pay for THIS url?"* You hit a URL, get a
-`402` with a machine-readable challenge, pay on-chain, retry with proof, get `200`. It does **not**
-answer *"what payable URLs exist?"*
-
-So a fresh PipRail merchant is in a bind:
-
-- A **seller** adds `requirePayment()` to `https://api.acme.com/report`. It's now payable — but
-  nobody knows the URL exists. A shop with no sign, on a street with no name.
-- A **buyer** (an AI agent with a budget-bound wallet) wants to *buy a weather feed under $0.01 on
-  Base*. It has no phone book — it can only pay URLs a human already handed it.
-
-That missing phone book is **discovery**. It's a separate, optional layer built *around* x402.
-
-**Why PipRail doesn't host its own directory.** A registry/database is a backend we'd run forever —
-a bill that never reaches $0, uptime, an open write endpoint that invites spam + a moderation queue.
-That would turn PipRail from *"a tool you `npm install`"* into *"a platform you sign up for"* — the
-exact thing the project is defined against. So instead we **consume and contribute to the open
-indexes that already exist**, and host nothing.
-
----
-
-## 2. The open infrastructure we build on
-
-All three are external, open, and already running. PipRail reads from and writes to them; it operates
-none of them.
-
-| Index | Read (find) | Write (be listed) | Chains | PipRail role |
-|---|---|---|---|---|
-| **402 Index** (402index.io) | ✅ free, no auth | ✅ **`POST /register` — no auth, no signature, no payment** | any | **Primary register target** + a free read source. A superset (it also re-ingests the CDP Bazaar). |
-| **CDP Bazaar** (api.cdp.coinbase.com) | ✅ free, no key | ❌ listed only when the CDP **facilitator settles** your payment | any | **Read-only source.** PipRail uses no facilitator, so PipRail merchants don't auto-list here — discoverability comes from 402 Index / x402scan. |
-| **x402scan** (x402scan.com) | 💲 paid ($0.01–0.02, off by default) | ✅ **SIWX** (one wallet signature; facilitator-free) | **Base + Solana only** | **Secondary register target** (the strongest ownership model); a paid, opt-in read. |
-
-> The honest framing: the most prominent directory, the CDP Bazaar, is a *facilitator network
-> effect* — it lists you only when Coinbase's facilitator settles your payment, which PipRail never
-> uses. That's why discoverability for a backendless merchant flows through 402 Index (and x402scan),
-> not the Bazaar. PipRail can still freely **read** the Bazaar to help an agent find *other* people's
-> endpoints.
-
----
-
-## 2.5 Works on EVERY chain (the guarantee)
-
-**No matter the chain — a built-in preset, a non-EVM family, or a custom `{ id, rpcUrl }` chain we
-don't ship — a PipRail user can be indexed and found, and an agent can discover them.** This is a
-hard guarantee, proven by the test suite (`test/discovery-e2e.test.ts` parametrizes every family +
-a custom chain) and by running it for real:
-
-- **Emit** is pure serialization — it works for any chain's rails, full stop.
-- **Register** defaults to **402 Index**, which needs no signature and has no chain allowlist, so it
-  lists **every** chain. `payment_network` is optional metadata: it's the chain slug when you
-  configured the client with one (`'base'`, `'tron'`, …), and omitted for a custom `{ id, rpcUrl }`
-  chain (pass `network` explicitly if you want it). No chain is ever turned away.
-- **Discover** filters by delegating to the bound driver's own `supports()`, and — critically — a
-  rail whose network it can't resolve to CAIP-2 is **kept, never silently hidden**. So discovery is
-  never empty on a custom or unmapped chain; at worst it returns a re-checkable extra the agent
-  confirms at quote time.
-
-The **one** chain-limited piece is the *optional* x402scan register target (Base/Solana only, its
-own limit). It's a bonus, never the path — 402 Index already covers everyone. So: **402 Index +
-emit + discover = universal discovery on every chain.**
-
-**Future chains.** A chain we add later inherits all of this for free — register and emit need no
-discovery change at all, and `discover()` already never hides an unmapped chain. The only
-discovery touch in the add-a-chain procedure is a one-line entry in `indexes.ts`'s `SLUG_TO_CAIP2`
-(slug → the family's exact `caip2`), which sharpens `'self'` filtering precision; it's on the
-`add-chain-integration` checklist. Omitting it degrades nothing that matters — the resource is
-still found.
-
----
-
-## 3. The three moves
-
-Discovery is three opt-in capabilities. A merchant uses Emit + Register to **be found**; an agent
-uses Discover to **find**. Defaults are byte-identical to before — omit all three and nothing changes.
-
-### 3.1 EMIT — turn a gate's config into a discovery file (pure, no I/O)
-
-A gate already knows its price/asset/chain/`payTo`. `gate.describe()` exposes that as static,
-**nonce-free** metadata (discovery metadata is long-lived; a live challenge mints a nonce, this does
-not). The three pure emitters turn it into the file formats crawlers read. The merchant serves the
-result as a **static file on their own origin** — the one wiring step, no backend.
-
-```ts
-import { createPaymentGate, buildOpenApi, buildWellKnownX402, buildX402DnsTxt } from '@piprail/sdk'
-
-const gate = createPaymentGate({ chain: 'base', token: 'USDC', amount: '0.05', payTo })
-const resource = await gate.describe('https://api.example.com/report')
-//  → { url, description?, accepts: PaymentRail[] }   (PaymentRail = scheme/network/asset/payTo/
-//                                                       amount/amountFormatted/decimals/symbol?/maxTimeoutSeconds)
-
-// (a) OpenAPI-first — the convention the live indexes parse. Serve at /openapi.json.
-const openapi = buildOpenApi({ origin: 'https://api.example.com', resources: [resource] })
-
-// (b) Legacy x402scan origin file. Serve at /.well-known/x402.
-const wellKnown = buildWellKnownX402({ origin: 'https://api.example.com', resources: [resource] })
-
-// (c) The experimental _x402 DNS pointer — paste into your zone.
-const dns = buildX402DnsTxt({ host: 'api.example.com', discoveryUrl: 'https://api.example.com/openapi.json' })
-//  → { name: '_x402.api.example.com', type: 'TXT', value: 'v=x4021;url=https://api.example.com/openapi.json' }
-```
-
-| Function | Output | Serve at |
-|---|---|---|
-| `buildOpenApi(input)` | a minimal valid **OpenAPI 3.1** doc — one path per resource pathname (resources sharing a pathname merge, keyed by HTTP method), `x-payment-info` per paid op, optional `x-agentcash-provenance.ownershipProofs` | `https://<origin>/openapi.json` (primary) |
-| `buildWellKnownX402(input)` | `{ version: 1, resources: [urls], ownershipProofs? }` | `https://<origin>/.well-known/x402` (legacy) |
-| `buildX402DnsTxt({ host, discoveryUrl, descriptor? })` | `{ name: '_x402.<host>', type: 'TXT', value: 'v=x4021;[descriptor=…;]url=…' }` | a DNS TXT record (experimental) |
-
-`ManifestInput` = `{ origin, resources, ownershipProofs?, title?, version?, attribution? }`. All three
-emitters are **pure** — no network, no chain library — so they're deterministic and trivially testable.
-They emit exactly the rails you pass; to be *usefully* listed on the open indexes, also offer a standard
-`exact` rail (see §6).
-
-**Spreading the word — three tasteful, honest channels (no spam, no rule-breaking).**
-
-1. **`x-generator` stamp (default on, opt-out).** `buildOpenApi` marks the document root with
-   `x-generator: "@piprail/sdk · https://piprail.com"` — a standard, unobtrusive "built with" mark
-   (like Swagger/Hugo emit). It lives in the `/openapi.json` the merchant serves on their *own*
-   origin — the very file the open indexes **crawl** — so the attribution rides along wherever a
-   PipRail merchant is found. Metadata only; opt out with `attribution: false`.
-2. **`User-Agent` on every index request (always on).** All reads/registers send
-   `User-Agent: @piprail/sdk (+https://piprail.com)` — the standard bot-UA-with-contact-URL
-   convention, so index operators see PipRail-driven traffic in their logs. It's a request *header*,
-   so it can never affect an index's body validation (zero risk of breaking a register), and the
-   browser keeps its own UA where it must. *(Live-verified: the server echoes it back.)*
-3. **Opt-in `via` listing tag (default OFF).** `register(url, { attribution: true })` adds
-   `via: '@piprail/sdk'` to the listing payload. **Off by default** — it's the *merchant's* listing
-   on a third party, so we never tag it without being asked — and **best-effort** (an index may
-   ignore an unknown field). *(Live-verified safe: 402 Index tolerates the field — a tagged register
-   gets the exact same URL-probe response as an untagged one, never a field rejection.)*
-
-We do **not** hijack the listing's `provider` (that's the merchant's), and the always-on channels (1
-+ 2) are the reliable ones; (3) is purely opt-in. Honest attribution through the channels that
-already exist — never spam.
-
-**Ownership proof (optional trust badge).** Sign the **bare origin string** with the `payTo` key and
-pass it as `ownershipProofs`. x402scan verifies `recoverMessageAddress(origin, sig) === payTo`.
-
-```ts
-const signer = await client.discoverySigner() // EVM today; null on families without it
-const proof = signer ? [await signer.signMessage('https://api.example.com')] : undefined
-const openapi = buildOpenApi({ origin: 'https://api.example.com', resources: [resource], ownershipProofs: proof })
-```
-
-### 3.2 REGISTER — list yourself on the open registries
-
-```ts
-const client = new PipRailClient({ wallet: { privateKey: KEY }, chain: 'base' })
-
-const outcomes = await client.register('https://api.example.com/report', {
-  name: 'Market Report',
-  priceUsd: 0.05,
-  // targets: ['402index']            // default — no auth, no signature
-  // targets: ['402index', 'x402scan'] // also x402scan via SIWX (EVM + Base/Solana)
-})
-//  → [{ source: '402index', ok: true, status: 200, detail: 'Listed on 402 Index (searchable at 402index.io).' }]
-```
-
-`RegisterOptions` = `{ name?, description?, priceUsd?, asset?, network?, method?, targets? }`. The
-`network` slug defaults to the client's `chain` when it's a slug (e.g. `'base'`). Returns one
-`RegisterOutcome` (`{ source, ok, status?, detail?, listingUrl? }`) **per target** — a target the
-chain can't satisfy is reported `{ ok: false, detail }`, **never thrown**:
-
-| target | what happens |
-|---|---|
-| `'402index'` (default) | one `POST` — no auth/signature/payment. The reliable path on every chain. |
-| `'x402scan'` | **SIWX**: `POST` → `402` challenge → sign EIP-4361 with the wallet key → resend with the `SIGN-IN-WITH-X` header. The SDK checks **only** for an EVM `discoverySigner` locally (returns `{ ok:false }` on a non-EVM family); the **Base/Solana-only** limit is enforced by x402scan itself, so any other chain comes back `{ ok:false }` with the HTTP status it returns. **Experimental** — the SIWX handshake is a moving convention; validate against x402scan before relying on it. |
-| `'bazaar'` | honestly refused (`{ ok:false }`) — the Bazaar has no write endpoint (facilitator-settle only). |
-
-Standalone equivalents (no client): `register402Index(input)` and `registerX402Scan({ url }, signer)`.
-
-### 3.3 DISCOVER — find payable resources (read-only, free)
-
-```ts
-const hits = await client.discover({ query: 'weather', maxPrice: 0.01 })
-//  → DiscoveredResource[]  ({ resource, source, name?, description?, priceUsd?, rails: DiscoveredRail[] })
-const res = await client.fetch(hits[0].resource) // then the usual quote → plan → pay
-```
-
-`DiscoverOptions` = `{ query?, network?, maxPrice?, sources?, limit? }`:
-
-| option | default | meaning |
-|---|---|---|
-| `query` | — | free-text; matched against name/description/resource (Bazaar is filtered client-side, 402 Index server-side via `?q=`). |
-| `network` | `'self'` | `'self'` = only resources payable on the client's bound chain · a **CAIP-2** id = that chain · `'any'` = every chain. |
-| `maxPrice` | — | coarse pre-filter: drop results whose *advertised* USD price exceeds it (results with no price pass through — `quote()` gives the exact figure). |
-| `sources` | `['bazaar','402index']` | which open indexes to read (both free). |
-| `limit` | `20` | max results per source before merge. |
-
-Results from all sources are **merged and deduped by resource URL** (first source wins). Standalone:
-`searchOpenIndexes({ query?, sources?, limit?, signal? })`.
-
-**Network filtering is forgiving by design.** An index reports networks as slugs (`'base'`) or CAIP-2
-(`'eip155:8453'`). `normalizeNetwork()` maps known slugs to the exact CAIP-2 each driver binds (every
-family is covered; Solana's reference is the 32-char-truncated form). For `network: 'self'` the filter
-delegates to the driver's own `net.supports()`, and — crucially — a rail whose network it **cannot
-resolve** is **kept, not silently hidden** (a re-checkable false positive beats an invisible
-resource; the agent's next `quote()`/`planPayment()` rejects a wrong chain anyway).
-
----
-
-## 4. The signing primitive — `discoverySigner`
-
-One **optional** addition to the `PaymentDriver` contract:
-
-```ts
-// drivers/types.ts — ResolvedNetwork
-discoverySigner?(wallet: WalletHandle): DiscoverySigner | null
-// DiscoverySigner = { address: string; signMessage(message: string): Promise<string> }
-```
-
-- **Discovery only** — ownership proofs + SIWX registration. It **never signs a payment**.
-- **EVM today** (eip191 via the wallet client; works for `{ privateKey }` and `{ walletClient }`).
-  Recoverable with viem's `recoverMessageAddress` — exactly how x402scan verifies origin ownership.
-- **Optional by design** — a family omits it until an open index verifies its signatures. The
-  primary register path (402 Index) needs no signature, so families without it lose nothing there;
-  `register(..., { targets: ['x402scan'] })` returns a clear `{ ok:false }` for them.
-- It is the SDK's **first optional contract method**, so it does *not* trigger the "implement in all
-  families" rule that applies to required methods.
-
-`client.discoverySigner()` surfaces it (or `null`) so a merchant can generate an ownership proof.
-
----
-
-## 5. Agent / MCP tools
-
-`paymentTools(client)` ships five descriptors; the MCP server is a pass-through, so they appear in
-`@piprail/mcp` automatically:
-
-| tool | does |
-|---|---|
-| **`piprail_discover`** `{ query?, network?, maxPrice?, limit? }` | find payable resources on the open indexes — the phone book. |
-| `piprail_quote_payment` `{ url }` | price a gated URL without paying. |
-| `piprail_plan_payment` `{ url }` | check you *can* pay (balance/gas/recipient) across every rail. |
-| `piprail_pay_request` `{ url, method?, body? }` | pay the 402 and return the result. |
-| **`piprail_register`** `{ url, name?, description?, priceUsd? }` | list a resource you run (402 Index, no signature). |
-
-The discover tool returns a compact list (`resource, name, source, priceUsd, networks`) for the model
-to pick from, then quote → pay. Because index results are cross-scheme, the model should always
-`quote()` a chosen resource (re-hitting the live URL) before paying.
-
----
-
-## 6. The honest caveats (never glossed)
-
-1. **Scheme.** PipRail 402s use `scheme: 'onchain-proof'`; the open indexes assume the mainstream
-   **`exact`** scheme. A naive PipRail 402 risks being marked "skipped." **To be *usefully* indexed,
-   also advertise a standard `exact` USDC rail on Base/Solana.** `discover()` results are
-   cross-scheme: `client.fetch()` pays only `onchain-proof` rails directly; paying a discovered
-   `exact` resource uses the already-exported experimental `drivers/evm/exact.ts` interop.
-2. **x402scan is Base/Solana only** (enforced server-side by x402scan — the SDK does no local chain
-   check before calling `registerX402Scan`). 402 Index has no such
-   limit, so it's the default register target and covers every family.
-3. **There is no single ratified discovery standard.** The ratified x402 v2 spec defines discovery
-   only as the read-only facilitator Bazaar. OpenAPI-first (`x-payment-info`) is an **emerging
-   multi-vendor convention** (an early IETF draft, Merit Systems + Tempo Labs) — emit it, but treat
-   it as a moving target, never "the standard." The `_x402` DNS draft is expired; emit it as a
-   nice-to-have only.
-
----
-
-## 7. Step-by-step walkthrough (and exactly what you need)
-
-Two roles. **A merchant lists their own endpoint so agents can find it; an agent finds and pays.**
-There is **no PipRail account and no x402 sign-up anywhere** — you never "register your SDK" with us
-or with x402. The only thing that's ever "registered" is a *merchant's own URL* on a public index,
-and they do it themselves with one call.
-
-### 7a. Merchant — be found (each step says what it needs)
-
-1. **Gate the route.** `requirePayment({ chain, token, amount, payTo })`.
-   *You need:* your **receiving wallet address** (`payTo`) — a public address, **not** a private key.
-   *No signing, no sign-up.* The route now returns `402` (payable) but is invisible.
-2. **(Optional) Emit a discovery file.** `const r = await gate.describe(url)` →
-   `buildOpenApi({ origin, resources: [r] })` → serve the JSON at `https://<origin>/openapi.json`.
-   *You need:* nothing — it's pure, no keys, no network. It's a static file on your own server.
-3. **Register so agents can find you.** `await client.register(url, { name, priceUsd })`.
-   - **402 Index — the default.** **No sign-up, no API key, no signature, no wallet.** One HTTPS POST;
-     402 Index probes your URL (it must return a real `402`) and lists it. Searchable in seconds.
-   - **x402scan — optional.** Add `targets: ['402index', 'x402scan']`. This one signs a **SIWX**
-     challenge with **your own wallet's key** (one signature — *no funds move*). Base/Solana only.
-     This is the **only** signing on the be-found side, and it's optional.
-4. **(Optional) Ownership badge.** Sign your bare origin string with your `payTo` key
-   (`const s = await client.discoverySigner(); await s.signMessage(origin)`) and pass it as
-   `buildOpenApi({ ownershipProofs: [...] })`. A trust badge on indexes that verify it; never required.
-5. **Found.** Agents discover you through the open indexes. Nothing is hosted by PipRail.
-
-### 7b. Agent — find & pay
-
-1. **Discover.** `await client.discover({ query })` — reads the open indexes (free). *No key, no sign-up.*
-2. **Quote.** `await client.quote(resource)` — the exact live price. *No funds move.*
-3. **Plan.** `await client.planPayment(resource)` — can this wallet actually settle it? *No funds move.*
-4. **Pay.** `await client.fetch(resource)` — *you need:* a **funded wallet** (it signs + broadcasts the
-   payment, then verifies locally). The payment goes **merchant-direct** — no facilitator, and the
-   index never touches the money.
-
-### 7c. What you need at each step (the whole truth, one table)
-
-| Step | Wallet? | Private key / signing? | Sign-up / account? | Cost |
-|---|---|---|---|---|
-| Gate an endpoint | a receiving **address** only | **no** | **no** | free |
-| Emit `/openapi.json` | — | **no** | **no** | free |
-| **Register · 402 Index** (default) | — | **no** | **no** | free |
-| Register · x402scan (optional) | your own | yes — **1 SIWX signature, no funds move** | **no** | free |
-| Ownership badge (optional) | your own | yes — sign the origin string | **no** | free |
-| Discover | — | **no** | **no** | free |
-| Quote / plan | — | **no** | **no** | free |
-| **Pay** a discovered API | a **funded** wallet | yes — the on-chain payment tx | **no** | the price + gas |
-
-**The fastest path to discoverable** is the bold row pair: gate it, then `client.register(url)` —
-**no wallet, no signature, no account, free.** Everything else is optional polish.
-
----
-
-## 8. Constraint compliance
-
-- **No backend / DB / registry of our own.** Emit = a static file the *merchant* hosts; discover /
-  register = runtime calls to *third-party* open indexes; payment is merchant-direct + local verify.
-- **Protocol layer stays chain-agnostic** (STANDARDS §1): `discovery.ts` + `indexes.ts` import only
-  `x402.ts`/`drivers/types.ts` + pure utils — zero chain libraries (verified by the lazy-chunk grep).
-- **Opt-in, defaults unchanged.** `discover`/`register`/`discoverySigner`/the emitters/`gate.describe`
-  are all new optional surface; the zero-config pay path is byte-identical.
-- **Read-style, never throws.** Search returns `[]` on a dead/garbage index; register returns
-  `{ ok:false, detail }` on any failure; the pure emitters can't fail at runtime. (See ERRORS.md.)
-
----
-
-## 9. Full API surface
-
-```ts
-// Emit (pure)
-buildOpenApi(input: ManifestInput): OpenApiDocument
-buildWellKnownX402(input: ManifestInput): WellKnownX402
-buildX402DnsTxt(input: { host; discoveryUrl; descriptor? }): X402DnsRecord
-gate.describe(resourceUrl?): Promise<ResourceDescription>
-
-// Register (developer-invoked I/O; never throws)
-client.register(url, opts?: RegisterOptions): Promise<RegisterOutcome[]>
-register402Index(input: RegisterInput): Promise<RegisterOutcome>
-registerX402Scan({ url }, signer: DiscoverySigner): Promise<RegisterOutcome>
-
-// Discover (read-only I/O; never throws)
-client.discover(opts?: DiscoverOptions): Promise<DiscoveredResource[]>
-searchOpenIndexes(opts?: SearchOpenIndexesOptions): Promise<DiscoveredResource[]>
-normalizeNetwork(network: string): string
-
-// Sign (discovery only)
-client.discoverySigner(): Promise<DiscoverySigner | null>
-
-// Types
-PaymentRail · ResourceDescription · ManifestInput · OpenApiDocument · OpenApiOperation ·
-WellKnownX402 · X402DnsRecord · DiscoverySource · DiscoveredResource · DiscoveredRail ·
-RegisterOutcome · RegisterInput · SearchOpenIndexesOptions · DiscoverOptions · RegisterOptions ·
-DiscoverySigner
-```
-
----
-
-## 10. Experimental status & live-integration log
-
-Discovery is **experimental** because it depends on third-party open indexes (402 Index, CDP Bazaar,
-x402scan) whose APIs and conventions are young and moving. The SDK code is stable and tested; what's
-experimental is the *integration contract* with those external services. Keep this log current.
-
-**Live integration test — 2026-06-06** (the SDK's own functions, run against the real services):
-
-| What | Result |
-|---|---|
-| `searchOpenIndexes({ sources: ['bazaar'] })` — CDP Bazaar, free | ✅ 20 resources normalized; all `exact`-scheme on `eip155:8453` (confirms the cross-scheme caveat). |
-| `searchOpenIndexes({ sources: ['402index'], query })` | ✅ real `{services:[…]}` parsed; the **x402 protocol filter dropped L402/MPP** on live data. |
-| `client.discover({ network: 'any' })` | ✅ both indexes merged + deduped (sources: `bazaar` + `402index`). |
-| `client.discover()` (default `self`) | ✅ filtered to the client's chain; the never-hide invariant held on real data. |
-| `register402Index(...)` (write, no auth) | ✅ POST succeeded end-to-end; **402 Index PROBES the URL** and returned **HTTP 422** for a non-402 URL: *"Your endpoint returned HTTP 200 instead of 402."* Our code reported `{ ok:false, status:422, detail }` **without throwing**, and surfaces the index's own reason. |
-| `registerX402Scan(...)` (SIWX write) | ⏳ **NOT yet live-tested.** EVM signing is correct in isolation, but the SIWX handshake against x402scan is unverified — still experimental. |
-| **`User-Agent` attribution** | ✅ confirmed sent over the wire (`@piprail/sdk (+https://piprail.com)` echoed back by an external header service). |
-| **Opt-in `via` listing tag** | ✅ confirmed **safe**: a `register(..., { attribution: true })` to 402 Index returns the *identical* URL-probe response as an untagged one — the field is tolerated, never causes a rejection. |
-
-**Key facts learned live:**
-- **402 Index validates by probing** — it will only list a URL that actually returns a `402`. So a
-  successful registration requires a **real, deployed, public** x402 endpoint (PipRail has none to
-  test with — a marketing site returns 200 and is correctly rejected). This also means our test
-  created **no junk listing**. The error reason is now surfaced in `RegisterOutcome.detail`.
-- **Read is free and works today** on both CDP Bazaar and 402 Index with no key.
-- **402 Index totals (2026-06-06):** ~63k endpoints (x402: ~61k), ~1.6k services — a real, populated index.
-
-**Before relying on it in production:** (1) register a real deployed x402 endpoint and confirm a
-`200`/listed outcome end-to-end; (2) live-test the x402scan SIWX path; (3) re-verify the index wire
-shapes (they drift — this doc's parser is defensive but the conventions are unratified).
-
----
-
-## 11. Sources & further reading
-
-- `.claude/research/x402-discovery.md` — the from-scratch explainer (concepts, formats, glossary).
-- `.claude/research/x402-discovery-integration.md` — the source-level integration plan + verification log.
-- 402 Index — https://402index.io · CDP Bazaar — https://docs.cdp.coinbase.com/x402/bazaar ·
-  x402scan — https://github.com/Merit-Systems/x402scan · x402 spec — https://github.com/coinbase/x402