@piprail/sdk 1.3.1 → 1.5.0

package/CHAINS.md

@@ -6,7 +6,8 @@ themselves differ, and a few have **setup steps you must do before a wallet can
 receive**. This page is the exact list.
 
 **Most chains need nothing special.** The ones with caveats are **NEAR**, **TON**,
-**Stellar**, **XRPL**, and **Tron** — read those sections before you ship them.
+**Stellar**, **XRPL**, **Tron**, and **Algorand** (USDC needs a one-time ASA opt-in) —
+read those sections before you ship them.
 
 ## At a glance
 
@@ -15,6 +16,8 @@ receive**. This page is the exact list.
 | **EVM** (Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, Mantle, Sonic, Linea, Scroll, Celo, zkSync, Unichain, World Chain, Sei, Injective, + any EVM chain) | ✅ ETH/BNB/POL/… | USDC (all) · USDT (all **except Base, World Chain, Sei**) | 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) |
@@ -22,12 +25,14 @@ receive**. This page is the exact list.
 | **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, 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`).
+> 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 }` · TON `{ master, 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 }`.
 
@@ -93,6 +98,23 @@ receive**. This page is the exact list.
 - **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.
@@ -130,6 +152,7 @@ Fix the *recipient*, not the payer:
 | `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)**.
@@ -143,9 +166,10 @@ 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).
+  (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**, **Tron**, and **native NEAR**. For
+  + 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).
 

package/CHANGELOG.md

@@ -4,6 +4,80 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.5.0] — 2026-06-04
+
+**The killer agent feature — `client.planPayment(url)`.** A read-only call that surveys a 402
+across every rail it offers *on your chain* against your wallet's OWN holdings — **token balance +
+native gas + recipient-readiness** (trustline / ATA / storage_deposit / ASA opt-in / activation) —
+and tells you, crystal-clear, whether it's settleable, on which rail, and if not, exactly what to
+top up. It completes the trio the SDK already ships: **`quote()` (what it costs) → `estimateCost()`
+(the gas) → `planPayment()` (can I actually settle, and where).** Fully backward-compatible and
+opt-in; defaults are unchanged. The official x402 client picks `accepts[0]` blind; PipRail is the
+only backendless SDK that can answer "can I actually pay this?" across 28 chains with pure RPC
+reads, no oracle/facilitator/bridge. Live-proven on Algorand mainnet (ready / recipient-not-ready /
+insufficient / multi-rail-rank, 4/4).
+
+### Added
+- **`client.planPayment(url, init?)` → `PaymentPlan | null`.** Never throws for a read problem (a
+  transient/RPC failure surfaces as a rail in `state: 'unknown'` + a warning, never a false
+  "unaffordable"); returns `null` when the URL isn't 402-gated; and when the 402 offers no rail on
+  your chain it EXPLAINS that (status `blocked` + a hint) instead of throwing. The plan carries:
+  `payable` + `best` (the cheapest settleable rail), `options[]` (every rail with typed `blockers`
+  — `INSUFFICIENT_TOKEN`/`INSUFFICIENT_GAS`/`RECIPIENT_NOT_READY`/`OUTSIDE_POLICY` — plus soft
+  `warnings`, a `shortfall`, live `balance`, and `recipient.fix`), and a one-sentence `fundingHint`.
+- **`client.canAfford(url)` → `boolean`** — convenience over the above.
+- **`fetch(url, { autoRoute: true })` / `new PipRailClient({ autoRoute: true })`** — opt-in:
+  `fetch` pays the cheapest rail the wallet can ACTUALLY settle (not the first policy-passing one),
+  or throws `PaymentDeclinedError` carrying the funding hint before any send. **Default off** —
+  the zero-config path is byte-identical.
+- **`planAcross(clients, url)`** — the cross-chain brain: give it one client per chain you fund and
+  it merges their plans, payable-first (no oracle, so the cross-coin tiebreak is your client order).
+- **`piprail_plan_payment`** agent tool (budget-bound; `paymentTools(client)` now returns 3 tools).
+- **Driver contract:** `balanceOf(wallet, asset)` + `recipientReady(payTo, asset)` on every family
+  (10/10), RPC-read-only and NEVER-throw (transient ⇒ `null`/`'unknown'`, per ERRORS.md §5). Real
+  receive-prerequisite probes on NEAR (`storage_balance_of`), Stellar/XRPL (trustline presence),
+  Algorand (ASA opt-in); truthful `'n/a'` on EVM/Solana/TON/Tron/Sui/Aptos (no prerequisite).
+- New exported types: `PaymentPlan`, `PayOption`, `PayBlocker`, `PayWarning`, `RecipientReason`,
+  `WalletBalance` (and the previously-missing `AptosToken`/`AlgorandToken`).
+
+## [1.4.0] — 2026-06-04
+
+A new chain **family** — **Algorand** — the **10th driver family**, bringing the built-in count to
+**28 chains across 10 families (19 EVM)**. Algorand is genuinely part of the **official x402
+standard** (its `exact` scheme is merged into the canonical x402 repo and the `@x402/avm` package),
+and one of the loudest agentic-commerce chains of 2026 — but the incumbent x402 path there is
+**facilitator-mediated**, so PipRail is the **first facilitator-free, backendless, verify-locally
+x402 SDK on Algorand**. Fully backward-compatible; `algosdk` is a lazy-loaded optional peer, so
+pure-EVM (and other) installs never download it.
+
+### Added
+- **Algorand (`chain: 'algorand'`, CAIP-2 `algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k`)** — native
+  Circle **USDC** (ASA `31566704`, 6 dp) + native **ALGO** (6 dp). The USDC ASA was verified live on
+  mainnet (algod `/v2/assets/31566704` → unit-name `USDC`, decimals 6, creator = Circle's `2UEQ…`
+  account, url `centre.io/usdc`) before shipping. **USDC-only:** Tether deprecated USDT on Algorand
+  (frozen 2025-09-01), so it's intentionally omitted — pass it as a custom `{ assetId, decimals }`.
+- **Template A (memo-bound, like Stellar/XRPL/NEAR):** every Algorand transaction carries an
+  arbitrary **note field (≤1KB)**, so the challenge nonce rides in it verbatim (no hashing needed —
+  a UUID dwarfs nothing of the 1KB cap). `verify()` re-derives the watched account from the
+  **trusted `accept.payTo`** (never the client ref), reads its recent inbound transfers via the
+  indexer, and matches `note === nonce` + recipient + asset + amount + recency — a proof is
+  cryptographically bound to its challenge. Native ALGO is a `pay` txn; USDC/ASAs are `axfer`; both
+  carry the note. Amounts are integer base units (like EVM). `algosdk` is an **optional peer
+  (`>=3 <4`)**, lazy-loaded on first use; the built EVM bundle stays free of any static `algosdk`
+  import (its own chunk).
+- **Receive prerequisite:** to receive a USDC/ASA, the recipient must **opt into the ASA** (a
+  one-time 0-amount self-transfer) — conceptually identical to an XRPL/Stellar trustline. A submit
+  failure for a not-opted-in recipient maps to the typed `RecipientNotReadyError`; native ALGO needs
+  no opt-in.
+
+**Live-proven on Algorand mainnet — both assets, 12/12.** Real 402 → pay → confirm → verify → 200
+round-trips, each with balance moved + replay rejected (`tx_already_used`) + all agent surfaces
+green: **native ALGO** 6/6 (tx `AXXJVYAP7BLK6C76AWCJ3XA5HTECIRSCNRQ2WLFRNSZ6CD5GH32Q`) and
+**USDC** 6/6 (tx `INWCUUBAMIBYOPPUOBWXEHZQAQL6KSV7DPEEVGKAI64Z46TRQKOA`, merchant +0.05 USDC).
+Also verified against the test contract (typecheck + 441 tests + build + the lazy-chunk invariant).
+Funding follow-up: file an Algorand **xGov retroactive** grant for the shipped open-source SDK
+(SDKs/libraries are a named eligible category).
+
 ## [1.3.1] — 2026-06-04
 
 Aptos pay-path fix surfaced by the live mainnet test — no API change, fully compatible with 1.3.0.

package/ERRORS.md

@@ -2,8 +2,8 @@
 
 This is the **single source of truth** for how `@piprail/sdk` reports errors. It is
 deliberately small and uniform: every module — the client, the server gate, the registry,
-and every chain driver (all nine families: EVM, Solana, TON, Tron, NEAR, Sui, Stellar, XRPL, Aptos,
-and any future one) — follows it
+and every chain driver (all ten families: EVM, Solana, TON, Tron, NEAR, Sui, Stellar, XRPL, Aptos,
+Algorand, and any future one) — follows it
 *exactly*, so a human developer, a merchant server, or an AI agent always gets a **typed,
 understandable** reason, never an opaque chain-library blob.
 
@@ -149,6 +149,17 @@ Every `PaymentDriver` / `ResolvedNetwork` method has a fixed error behaviour:
 | `send(wallet, accept)` | wrap the broadcast; map **sender** affordability → `InsufficientFundsError` (§6) and **recipient** setup → `RecipientNotReadyError` (§6.1); **rethrow everything else unchanged** (never swallow). Every mapped throw carries `{ cause }` = the raw chain error. |
 | `verify(ref, accept)` | **return** a `VerifyResult` with a canonical `VerifyErrorCode`. **Guard every RPC read** so a transient failure returns `tx_not_found` — `verify()` must not throw for an RPC hiccup. Re-derive the watched account from the trusted `accept`, never the client ref. |
 | `confirm(ref, n)` | broadcast-but-not-confirmed / timeout → `ConfirmationTimeoutError`. |
+| `estimateCost(accept, opts?)` | **never throw** — guard the RPC read and fall back to a `'heuristic'` constant; always return a valid `CostEstimate`. |
+| `balanceOf(wallet, asset)` | **never throw** — RPC-read-only. A field whose read was unavailable (transient/rate-limit) returns `null`, NOT `0` (a false 0 reads as "broke"). For `asset==='native'`, `token === native`. |
+| `recipientReady(payTo, asset)` | **never throw** — report the receive prerequisite: `{ ready:'n/a' }` (no prerequisite on this family/native), `{ ready:true }`, `{ ready:false, reason }` (a `RecipientReason`), or `{ ready:'unknown' }` on a transient read. `'n/a'` must be TRUTHFUL — never a stand-in for "didn't check". |
+
+> **`planPayment` is a RETURN-channel feature.** The client's `planPayment`/`canAfford` compose
+> `balanceOf` + `recipientReady` + `estimateCost` + the policy verdict into a `PaymentPlan` — and,
+> like `verify()`, they **return** the outcome rather than throwing: a transient read becomes a rail
+> in `state:'unknown'` (+ a warning), an unsettleable rail carries typed `blockers`, and a 402 with
+> no rail on the client's chain is *explained* in the plan. The only throw is `InvalidEnvelopeError`
+> on an unparseable challenge. (`fetch({ autoRoute:true })` is the one place a plan turns into a
+> THROWN `PaymentDeclinedError` — refusing before any send when nothing is settleable.)
 
 ### 6. Affordability converges on one error, by two mechanisms
 

package/README.md

@@ -1,6 +1,6 @@
 # @piprail/sdk
 
-**Accept crypto payments from any HTTP request — on any EVM chain, Solana, TON, Tron, NEAR, Sui, Stellar, and the XRP Ledger — in a couple of lines.**
+**Accept crypto payments from any HTTP request — on any EVM chain, Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar, and the XRP Ledger — in a couple of lines.**
 
 No middleman. No database. No fee. No account. Payments settle **straight into your wallet**, verified locally against your own RPC. Drop one middleware in front of a route and it's paid-only; point an agent at a paid URL and it pays itself.
 
@@ -77,20 +77,48 @@ client.spent() // → { count, byAsset: [{ symbol:'USDC', totalFormatted:'0.05',
 
 **Know the gas before you pay.** `client.estimateCost(url)` returns the quote **and** a `CostEstimate` — the network fee in the chain's **native coin** (you pay in USDC but burn ETH / SOL / TON / XLM / XRP / TRX on gas, a separate balance the agent must keep topped up). It's best-effort and labelled (`cost.basis`): a live-RPC read where cheap (`'estimated'` — EVM gas price, XRPL fee), a typical-cost constant otherwise (`'heuristic'`), and it never throws. Most valuable on **Tron**, where a USD₮ transfer can cost real TRX. So an agent can budget the *total* — payment **+** gas — before any funds move. Every driver implements it; the math is extracted per-chain and shaped uniformly by one shared `nativeCost()` helper.
 
+### Plan before you pay — `planPayment()` (never fumble a payment)
+
+`quote()` tells you the price and `estimateCost()` the gas — **`planPayment(url)`** closes the loop: **one read-only call** that checks, against your wallet's *own* holdings, whether a 402 will actually go through — and if not, exactly what to fix. No funds move.
+
+```ts
+const plan = await client.planPayment(url)
+
+if (plan?.payable) {
+  await client.fetch(url, { autoRoute: true })   // pays plan.best — the cheapest rail you can settle
+} else {
+  console.log(plan?.fundingHint)
+  // "Have the USDC, but need ~0.000021 ETH for gas on base (have 0)."
+  // "Recipient 2OT6…GC5E4 can't receive on algorand yet — must opt into the USDC ASA."
+  // "Top up 0.04 USDC on base (have 0.01)."
+}
+```
+
+For **every rail the 402 offers on your chain**, the plan reads **token balance + native-coin gas + recipient-readiness** (trustline / ATA / `storage_deposit` / ASA opt-in / activation) and returns:
+- **`payable`** + **`best`** — the cheapest rail you can actually settle (recipient confirmed able to receive);
+- **`options[]`** — each rail with typed **`blockers`** (`INSUFFICIENT_TOKEN` · `INSUFFICIENT_GAS` · `RECIPIENT_NOT_READY` · `OUTSIDE_POLICY`), soft **`warnings`** (`SYMBOL_MISMATCH`, `THIN_GAS_MARGIN`, `BALANCE_UNREADABLE`, …), a **`shortfall`**, the live **`balance`**, and **`recipient.fix`**;
+- **`fundingHint`** — one human sentence on exactly what to top up.
+
+**Why it's the agent unlock.** The official x402 client picks `accepts[0]` blind and learns it can't pay only when the broadcast reverts (no token, no gas) or the transfer silently strands (recipient not set up to receive). `planPayment` turns those runtime failures into a pre-checked decision — and on the no-facilitator path *you* pay your own gas, so "I hold USDC but no ETH" is a first-class answer, not a crash. It **never throws for a read hiccup** (a throttled RPC surfaces as `state: 'unknown'` + a warning, never a false "broke"), returns `null` when the URL isn't gated, and *explains* "this is offered on solana, base — you're on xrpl" instead of erroring. `client.canAfford(url)` is the one-boolean convenience.
+
+**Auto-route (opt-in).** `new PipRailClient({ autoRoute: true })` (or `fetch(url, { autoRoute: true })`) makes `fetch` pay the cheapest *settleable* rail instead of the first policy-passing one — refusing with `PaymentDeclinedError` + the funding hint before any send. **Default off; the zero-config path is unchanged.**
+
+**Across chains.** A client is bound to one chain; **`planAcross([baseClient, solanaClient, …], url)`** runs each plan in parallel and merges them payable-first, so an agent holding funds on several chains learns which to use. (No price oracle — cross-coin ties break on the order you list the clients.)
+
 ### Hand an LLM a budget-bound wallet
 
 `paymentTools(client)` returns framework-agnostic tool descriptors (name + description + JSON Schema + `invoke`) — drop them into MCP, the Vercel AI SDK, OpenAI/Anthropic function-calling, or LangChain in a couple of lines. The budget rides on the client, so the model can't overspend.
 
 ```ts
 import { paymentTools } from '@piprail/sdk'
-const tools = paymentTools(client) // → [piprail_quote_payment, piprail_pay_request]
+const tools = paymentTools(client) // → [piprail_quote_payment, piprail_plan_payment, piprail_pay_request]
 ```
 
 See [`examples/agent-tools.mjs`](../examples/agent-tools.mjs) for MCP / AI-SDK wiring.
 
 ### Accept several chains at once
 
-`requirePayment` (and `createPaymentGate`) take an **`accept: [...]`** array — one challenge that's payable on **any** of several chains/tokens, across **all nine families** (EVM, Solana, TON, Tron, Stellar, XRPL, NEAR, Sui, Aptos). The agent pays with whatever it holds:
+`requirePayment` (and `createPaymentGate`) take an **`accept: [...]`** array — one challenge that's payable on **any** of several chains/tokens, across **all ten families** (EVM, Solana, TON, Tron, Stellar, XRPL, NEAR, Sui, Aptos, Algorand). The agent pays with whatever it holds:
 
 ```ts
 requirePayment({
@@ -133,7 +161,7 @@ requirePayment({ chain: 'ton',      token: 'native', amount: '1',     payTo }) /
 requirePayment({ chain: 'xrpl',     token: 'native', amount: '1',     payTo }) // XRP
 ```
 
-**Native or stablecoin — your choice, on every chain.** Every gate accepts the chain's native coin (ETH, BNB, POL, AVAX, SOL, TON, XLM, XRP, SUI, NEAR, **TRX**, …) just as readily as a stablecoin — set `token: 'native'` and the SDK fills in the right decimals (18 on EVM, 9 on Solana/TON/Sui, 7 on Stellar, 6 on XRPL/Tron, 24 on NEAR). Verification, replay protection, and self-custody are identical to the stablecoin path — across **all nine families, no exceptions**. (On **NEAR**, native is the zero-setup path — no `storage_deposit` — while the NEP-141 token path needs registration; see the NEAR note. On **Tron**, USD₮ is the default since TRX is volatile gas, but native TRX works too.)
+**Native or stablecoin — your choice, on every chain.** Every gate accepts the chain's native coin (ETH, BNB, POL, AVAX, SOL, TON, XLM, XRP, SUI, NEAR, **TRX**, …) just as readily as a stablecoin — set `token: 'native'` and the SDK fills in the right decimals (18 on EVM, 9 on Solana/TON/Sui, 8 on Aptos, 7 on Stellar, 6 on XRPL/Tron/Algorand, 24 on NEAR). Verification, replay protection, and self-custody are identical to the stablecoin path — across **all ten families, no exceptions**. (On **NEAR**, native is the zero-setup path — no `storage_deposit` — while the NEP-141 token path needs registration; see the NEAR note. On **Tron**, USD₮ is the default since TRX is volatile gas, but native TRX works too.)
 
 `token` is **required** — every gate states exactly what it accepts, so there's never any doubt whether a route takes USDC, USDT, or the native coin. Name a built-in symbol (`'USDC'`, `'USDT'`), use `'native'` for the chain's own coin (ETH, BNB, SOL, TON, XLM, …), or pass a custom token by address. The symbol is all you write — the SDK fills in the contract + decimals.
 
@@ -168,6 +196,7 @@ Every token address below was verified on-chain (symbol + decimals) before shipp
 | `'near'` | NEAR | USDC, USDT |
 | `'sui'` | Sui | USDC |
 | `'aptos'` | Aptos | USDC, USDT |
+| `'algorand'` | Algorand | USDC |
 | `'stellar'` | Stellar | USDC, EURC |
 | `'xrpl'` | XRP Ledger | USDC, RLUSD |
 
@@ -179,6 +208,8 @@ Every token address below was verified on-chain (symbol + decimals) before shipp
 
 **Sui note:** **USDC only** — no native USDT on Sui (Wormhole-bridged only). Native SUI works with `token: 'native'`.
 
+**Algorand note:** **USDC only** — Tether deprecated USDT on Algorand (frozen 2025-09-01), so it's intentionally absent (pass it as a custom `{ assetId, decimals }`). Native ALGO works with `token: 'native'` (the zero-setup path). To **receive** USDC the recipient must **opt into the ASA** once (a 0-amount self-transfer — like a trustline); a not-opted-in recipient surfaces `RECIPIENT_NOT_READY`. The challenge nonce binds inside the transaction's note field (Template A). Algorand's `exact` scheme is part of the official x402 standard; the incumbent on-chain path there uses a hosted facilitator, so PipRail is the backendless, no-facilitator option.
+
 **Stellar / XRPL note:** to **receive** an issued asset (USDC/EURC on Stellar; USDC/RLUSD on XRPL) the recipient needs a one-time **trustline** for that asset, and the account must already exist / be activated (a small native reserve — **locked, not spent**). Native XLM/XRP need no trustline. The payer needs its own trustline too.
 
 ### Using TON? Grab one free API key (≈30 seconds)
@@ -474,10 +505,10 @@ The SDK is browser-clean (no Node-only globals in the protocol layer), so a plai
 Two layers, one contract. Worth knowing if you're extending the SDK or auditing it.
 
 - **The protocol layer is chain-agnostic.** `server.ts` (`requirePayment`/`createPaymentGate`), `client.ts` (`PipRailClient`), `x402.ts` (wire envelopes), `policy.ts`, `ledger.ts`, and `agent.ts` depend **only** on the `PaymentDriver` contract in `drivers/types.ts` — zero `viem`, zero `@solana/web3.js`, zero chain SDK. The chain is data the caller passes, not an allowlist the SDK ships.
-- **The `PaymentDriver` contract.** `resolve(chain)` → a bound `ResolvedNetwork` exposing `resolveToken` · `describeAsset` · `assertValidPayTo` · `bindWallet` · `send` · `confirm` · `estimateCost` · `verify`. That's the entire boundary every family implements and the protocol layer ever sees.
-- **Families mirror each other file-for-file.** Each lives in `drivers/<family>/` as `chains` · `wallet` · `pay` · `verify` · `index`, with family-suffixed functions (`payEvm`/`paySui`/…, `verifyEvm`/`verifyNear`/…). Eight today: `evm`, `solana`, `ton`, `stellar`, `xrpl`, `tron`, `near`, `sui`. Adding one = copy the five files, implement the contract, `registerDriver` — the protocol layer never changes.
-- **Routing + lazy auto-mount.** `registry.ts` maps a `chain` value to its family synchronously (`familyForChain`). EVM is always present (viem is a hard peer); every non-EVM family **loads itself on first use** via one dynamic `import()`, so a pure-EVM install never downloads `@solana`/`@ton`/`@stellar`/`xrpl`/`tronweb`/`near-api-js`/`@mysten/sui`. A build-time invariant asserts the main bundle has **zero** static imports of those libs — only per-family lazy chunks.
-- **Two verification templates.** *Template A (memo-bound)* — Stellar, XRPL, TON, NEAR — carries the challenge nonce inside the transfer (memo / tag / comment), so the proof is cryptographically bound to its challenge. *Template B (digest-bound)* — EVM, Solana, Tron, Sui — binds via a single-use proof set + recipient + amount + a tight recency window (use a persistent `isUsed`/`markUsed` store in production).
+- **The `PaymentDriver` contract.** `resolve(chain)` → a bound `ResolvedNetwork` exposing `resolveToken` · `describeAsset` · `assertValidPayTo` · `bindWallet` · `send` · `confirm` · `estimateCost` · `balanceOf` · `recipientReady` · `verify`. That's the entire boundary every family implements and the protocol layer ever sees.
+- **Families mirror each other file-for-file.** Each lives in `drivers/<family>/` as `chains` · `wallet` · `pay` · `verify` · `index`, with family-suffixed functions (`payEvm`/`paySui`/…, `verifyEvm`/`verifyNear`/…). Ten today: `evm`, `solana`, `ton`, `stellar`, `xrpl`, `tron`, `near`, `sui`, `aptos`, `algorand`. Adding one = copy the five files, implement the contract, `registerDriver` — the protocol layer never changes.
+- **Routing + lazy auto-mount.** `registry.ts` maps a `chain` value to its family synchronously (`familyForChain`). EVM is always present (viem is a hard peer); every non-EVM family **loads itself on first use** via one dynamic `import()`, so a pure-EVM install never downloads `@solana`/`@ton`/`@stellar`/`xrpl`/`tronweb`/`near-api-js`/`@mysten/sui`/`@aptos-labs/ts-sdk`/`algosdk`. A build-time invariant asserts the main bundle has **zero** static imports of those libs — only per-family lazy chunks.
+- **Two verification templates.** *Template A (memo-bound)* — Stellar, XRPL, TON, NEAR, Algorand — carries the challenge nonce inside the transfer (memo / tag / comment / note), so the proof is cryptographically bound to its challenge. *Template B (digest-bound)* — EVM, Solana, Tron, Sui, Aptos — binds via a single-use proof set + recipient + amount + a tight recency window (use a persistent `isUsed`/`markUsed` store in production).
 - **Gas estimation.** Every driver's `estimateCost` extracts its own per-chain fee math, shaped into one uniform `CostEstimate` by the shared `nativeCost()` helper (`util/cost.ts`).
 - **The tests are the contract** (`test/`, Vitest), and two living standards govern any change: **[ERRORS.md](./ERRORS.md)** (how every module reports errors) and **STANDARDS.md** (how anything in the SDK is built + the verification gate). Runnable examples — including a local Anvil end-to-end — live in [`examples/`](../examples).
 
@@ -499,11 +530,12 @@ A failed payment is almost always one of two things, and PipRail tells them apar
 
 | Chain | The recipient must… | Sender also needs |
 |---|---|---|
-| **EVM · Solana · Sui · Tron** | nothing (just be a valid address; Solana's token account is auto-created by the SDK) | native gas |
+| **EVM · Solana · Sui · Aptos · Tron** | nothing (just be a valid address; Solana's token account is auto-created by the SDK; Aptos's primary FA store auto-creates) | native gas |
 | **TON** | nothing for native; a jetton wallet auto-deploys on first receipt (sender pays the gas) | TON for gas |
 | **NEAR** | nothing for native; for a token, be `storage_deposit`-registered on it (NEP-145, ~0.00125 NEAR, one-time) | NEAR for gas |
 | **Stellar** | exist (created with ≥1 XLM base reserve); for USDC/EURC, hold a **trustline** (+0.5 XLM each) | base + trustline reserves |
 | **XRP Ledger** | be **activated** — hold ≥1 XRP base reserve to exist; for USDC/RLUSD, a **trustline** | keep its own 1 XRP reserve |
+| **Algorand** | nothing for native ALGO; for USDC, **opt into the ASA** once (a 0-amount self-transfer, ~0.1 ALGO min-balance bump) | ALGO for fees + its own opt-in |
 
 > These are anti-spam "state rent" rules built into each ledger — e.g. an XRPL account can't receive a sub-1-XRP first payment because that payment must create the account at its ≥1 XRP base reserve. PipRail surfaces them as `RECIPIENT_NOT_READY` with the fix, so a payment that "can't go through" is self-explanatory. Per-chain specifics live in **[CHAINS.md](./CHAINS.md)**.
 
@@ -526,7 +558,7 @@ The full standard every module follows is **[ERRORS.md](./ERRORS.md)**.
 |---|---|---|
 | `chain` | — | `'base'` / `'bnb'` / `'solana'` / `'ton'` / …, a viem `Chain`, or `{ id, rpcUrl }` (single-chain form) |
 | `amount` | — | Human-readable, e.g. `'0.05'` (single-chain form) |
-| `token` | — | `'USDC'` / `'USDT'`, `'native'`, or a custom `{ address, decimals }` (EVM/Tron) / `{ mint, decimals }` (Solana) / `{ master, decimals }` (TON) / `{ issuer, code, decimals }` (Stellar) / `{ issuer, currencyHex, decimals }` (XRPL) / `{ contractId, decimals }` (NEAR) / `{ coinType, decimals }` (Sui) — required for the single form |
+| `token` | — | `'USDC'` / `'USDT'`, `'native'`, or a custom `{ address, decimals }` (EVM/Tron) / `{ mint, decimals }` (Solana) / `{ master, decimals }` (TON) / `{ issuer, code, decimals }` (Stellar) / `{ issuer, currencyHex, decimals }` (XRPL) / `{ contractId, decimals }` (NEAR) / `{ coinType, decimals }` (Sui) / `{ metadata, decimals }` (Aptos) / `{ assetId, decimals }` (Algorand) — required for the single form |
 | `accept` | — | Multi-chain form: `[{ chain, token, amount, payTo?, rpcUrl? }, …]` — offer several chains in one challenge |
 | `payTo` | — | Wallet that receives the payment (per-option fallback in the multi form) |
 | `description` | — | Optional text shown to the agent in the challenge (what the payment is for) |
@@ -552,7 +584,7 @@ Provide **either** `chain` + `token` + `amount` (single) **or** a non-empty `acc
 | `retryTimeoutMs` | `30000` | Timeout for the retry leg after broadcast |
 | `onEvent` | — | `(event) => void` observability: `payment-required` · `payment-broadcast` · `payment-confirmed` · `payment-unconfirmed` (broadcast OK, local confirm timed out → deferring to server) · `payment-settled` · `payment-failed` |
 
-Methods: `fetch` · `get` · `post` (return the gated `Response` after settlement) · **`quote(url)`** (price without paying → `PipRailQuote \| null`) · **`estimateCost(url)`** (price **+** native-coin gas estimate → `PipRailCostQuote \| null`) · **`spent()`** (per-asset ledger snapshot).
+Methods: `fetch` · `get` · `post` (return the gated `Response` after settlement) · **`quote(url)`** (price without paying → `PipRailQuote \| null`) · **`estimateCost(url)`** (price **+** native-coin gas estimate → `PipRailCostQuote \| null`) · **`planPayment(url)`** (affordability + recipient-readiness across the offered rails → `PaymentPlan \| null`) · **`canAfford(url)`** (→ `boolean`) · **`spent()`** (per-asset ledger snapshot). Pass `{ autoRoute: true }` to `fetch` (or set it on the client) to pay the cheapest *settleable* rail. Module-level **`planAcross(clients, url)`** plans across chains.
 
 **Wallets by family** — the `chain` selector routes; each driver validates its own key format (a mismatch throws `WrongFamilyError`):
 
@@ -566,6 +598,8 @@ Methods: `fetch` · `get` · `post` (return the gated `Response` after settlemen
 | Tron | `{ privateKey }` (32-byte hex — secp256k1) |
 | NEAR | `{ accountId, privateKey }` (privateKey = ed25519:… secret) |
 | Sui | `{ privateKey }` (suiprivkey1… bech32) or `{ keypair }` |
+| Aptos | `{ privateKey }` (ed25519-priv-0x… AIP-80) or `{ account }` |
+| Algorand | `{ mnemonic }` (25 words) or `{ account }` (algosdk `{ addr, sk }`) |
 
 **Hand an LLM a wallet:** `paymentTools(client)` → framework-agnostic tool descriptors (MCP / AI SDK / function-calling), budget enforced by the client.
 
@@ -576,7 +610,7 @@ Methods: `fetch` · `get` · `post` (return the gated `Response` after settlemen
 ## Requirements
 
 - Node 20+ or a modern browser.
-- `viem ^2.21` (peer dep). Solana: `@solana/web3.js`, `@solana/spl-token`, `bs58` (optional peers). TON: `@ton/ton`, `@ton/core`, `@ton/crypto` (optional peers). Stellar: `@stellar/stellar-sdk` (optional peer). XRPL: `xrpl` (optional peer). Tron: `tronweb` (optional peer). NEAR: `near-api-js` (optional peer). Sui: `@mysten/sui` (optional peer).
+- `viem ^2.21` (peer dep). Solana: `@solana/web3.js`, `@solana/spl-token`, `bs58` (optional peers). TON: `@ton/ton`, `@ton/core`, `@ton/crypto` (optional peers). Stellar: `@stellar/stellar-sdk` (optional peer). XRPL: `xrpl` (optional peer). Tron: `tronweb` (optional peer). NEAR: `near-api-js` (optional peer). Sui: `@mysten/sui` (optional peer). Aptos: `@aptos-labs/ts-sdk` (optional peer). Algorand: `algosdk` (optional peer).
 
 ## License & trademark