@piprail/sdk 1.5.0 → 1.6.0

package/CHAINS.md

@@ -13,7 +13,7 @@ read those sections before you ship them.
 
 | 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, + any EVM chain) | ✅ ETH/BNB/POL/… | USDC (all) · USDT (all **except Base, World Chain, Sei**) | No | `{ privateKey }` |
+| **EVM** (Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, Mantle, Sonic, Linea, Scroll, Celo, zkSync, Unichain, World Chain, Sei, Injective, HyperEVM, Monad, + any EVM chain) | ✅ ETH/BNB/POL/… | USDC (all) · USDT (all **except Base, World Chain, Sei, HyperEVM, Monad**) | 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…`) |
@@ -45,7 +45,7 @@ read those sections before you ship them.
 
 ### EVM — Ethereum, Base, Arbitrum, Optimism, Polygon, BNB, Avalanche, …
 - **Pay in:** native coin (`'native'`), `'USDC'`, `'USDT'`, or a custom `{ address, decimals }`.
-- **USDT gap:** built in on every preset **except Base, World Chain, and Sei** (USDC only there).
+- **USDT gap:** built in on every preset **except Base, World Chain, Sei, HyperEVM, and Monad** (USDC only there).
 - **Decimals:** on **BNB Chain**, Binance-Peg USDC/USDT are **18 decimals**, not 6 (the SDK handles it; don't hardcode 6).
 - **USDT branding:** on **Arbitrum, Polygon, and Unichain** the canonical Tether is the omnichain **USD₮0 / USDT0** (LayerZero), and on **Celo** it's native **USD₮** — all genuine, Tether-issued, 6-decimal USDT at the addresses shipped (verified live on-chain by symbol/decimals/supply). You still ask for it as `token: 'USDT'`; only the on-chain `symbol()` string differs from the plain `USDT` your wallet may show elsewhere.
 - **Receiver setup:** none — any `0x…` address receives ERC-20 or native immediately.

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.6.0] — 2026-06-05
+
+### Added
+- **`policy.tokens` accepts `'native'`** — a chain-agnostic alias that allows the chain's native coin
+  (ETH/BNB/TRX/XLM/…) by the same word the accept side already uses (`token: 'native'`), without naming
+  the per-chain ticker. It's matched on the asset (not the symbol), so it works on every family; symbol
+  matching is unchanged (the real ticker still works), and `'native'` only ever matches a genuinely
+  native asset — it never loosens a stablecoin allowlist. Closes a terminology gap where allowing native
+  payments previously required knowing the coin's symbol. `@piprail/mcp`'s `PIPRAIL_TOKENS` inherits this.
+  Additive + non-breaking (next release is a minor).
+
+## [1.5.1] — 2026-06-04
+
+**Cosmetic polish — docs & comments only, zero behavior change.** A repo-wide tidy pass so the
+in-code docs match the SDK as it actually ships (10 families / 28 chains). No runtime, API, type,
+or wire change — every existing program behaves identically.
+
+- **JSDoc parity across the public surface.** The `chain` / `token` / `payTo` / wallet docs on
+  `RequirePaymentOptions`, `AcceptOption`, and `PipRailClientOptions` now enumerate all 10 families
+  (Aptos + Algorand were missing); the typed error JSDoc (`WrongFamilyError`, `UnknownTokenError`,
+  `MissingDriverError`, `RecipientNotReadyError`) lists every family + install command + custom-token form.
+- **Stale comments corrected.** Native TRX and native NEAR are documented as the payment assets they've
+  been since 1.1.0 (the old "not a payment asset" / "`'native'` is rejected" notes were removed); the
+  `'native'` coin list, the barrel header, the tsup code-split note, and the lazy-mount docs now name all
+  9 non-EVM families; the `paymentTools` doc says "three tools" (quote · plan · pay).
+- **Driver-family symmetry.** `evm/wallet.ts` gained the `── EVM SECTION: wallet ──` banner the other 9
+  families carry, and `evm/index.ts`'s `recipientReady()` comment now uses the shared "No receive
+  prerequisite —" lead-in.
+- **Docs:** README contract-method list adds `balanceOf` / `recipientReady`; README custom-token examples
+  add Aptos + Algorand; CHAINS.md lists HyperEVM + Monad (and their USDT gap); ERRORS.md + AGENTS.md list
+  all 10 families; CHANGELOG version footer links restored.
+- **Packaging:** `algosdk` moved to its alphabetical slot in `peerDependencies` (no dependency change).
+
 ## [1.5.0] — 2026-06-04
 
 **The killer agent feature — `client.planPayment(url)`.** A read-only call that surveys a 402
@@ -384,6 +417,14 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[1.6.0]: https://www.npmjs.com/package/@piprail/sdk
+[1.5.1]: https://www.npmjs.com/package/@piprail/sdk
+[1.5.0]: https://www.npmjs.com/package/@piprail/sdk
+[1.4.0]: https://www.npmjs.com/package/@piprail/sdk
+[1.3.1]: https://www.npmjs.com/package/@piprail/sdk
+[1.3.0]: https://www.npmjs.com/package/@piprail/sdk
+[1.2.0]: https://www.npmjs.com/package/@piprail/sdk
+[1.1.1]: https://www.npmjs.com/package/@piprail/sdk
 [1.1.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.0.0]: https://www.npmjs.com/package/@piprail/sdk
 [0.1.0]: https://www.npmjs.com/package/@piprail/sdk

package/ERRORS.md

@@ -205,9 +205,10 @@ the reader, full raw detail for the debugger — both, always. Chains with no re
 
 ## 7. Registry / loader pattern
 
-- EVM is registered eagerly (`viem` is the one hard peer dep). Solana / TON / Stellar mount
-  lazily via a single dynamic `import()` in [`drivers/index.ts`](src/drivers/index.ts) the
-  first time their `chain` is named — no setup call.
+- EVM is registered eagerly (`viem` is the one hard peer dep). Every non-EVM family (Solana,
+  TON, Tron, NEAR, Sui, Stellar, XRPL, Aptos, Algorand) mounts lazily via a single dynamic
+  `import()` in [`drivers/index.ts`](src/drivers/index.ts) the first time its `chain` is
+  named — no setup call.
 - A failed lazy `import()` → `MissingDriverError` naming the exact `npm install` + `{ cause }`.
   The in-flight promise isn't cached on failure, so a later call can retry.
 - No driver for the family, or `resolve()` → `null` → `UnsupportedNetworkError`.

package/README.md

@@ -52,7 +52,7 @@ const client = new PipRailClient({
     maxAmount: '0.10',        // never pay more than $0.10 for one call
     maxTotal: '5.00',         // never spend more than $5 total (per token)
     chains: ['base'],         // only on Base
-    tokens: ['USDC'],         // only in USDC
+    tokens: ['USDC'],         // only in USDC (use 'native' to also allow the chain's coin)
     hosts: ['*.example.com'], // only these hosts
   },
   onBeforePay: (q) => Number(q.amountFormatted) <= 0.05, // final say on each payment
@@ -75,6 +75,8 @@ client.spent() // → { count, byAsset: [{ symbol:'USDC', totalFormatted:'0.05',
 
 **The budget can't be fooled.** `maxAmount`/`maxTotal` are enforced against the token's **true** decimals (the SDK's own, via the driver) — a server can't slip past a cap by understating the price, and an asset the SDK can't recognise is refused unless you set `allowUnknownTokens`. `quote()` even flags a `symbolMismatch` when a challenge's stated symbol disagrees with the real token.
 
+**`policy.tokens` takes symbols *or* `'native'`.** List stablecoin symbols (`'USDC'`, `'USDT'`, …) and/or the chain-agnostic alias **`'native'`** to allow the chain's own coin (ETH/BNB/TRX/XLM/…) on any family — the same word the accept side uses (`token: 'native'`), so you never name per-chain tickers (the real ticker works too). It only ever matches a genuinely native asset, so it never loosens a stablecoin-only list. The MCP server's `PIPRAIL_TOKENS` is the same allowlist.
+
 **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)
@@ -276,6 +278,12 @@ requirePayment({ chain: 'near', token: { contractId: 'token.near', decimals: 6 }
 
 // On Sui, a custom coin is { coinType, decimals }:
 requirePayment({ chain: 'sui', token: { coinType: '0x…::usdc::USDC', decimals: 6 }, amount: '0.05', payTo })
+
+// On Aptos, a custom Fungible Asset is { metadata, decimals }:
+requirePayment({ chain: 'aptos', token: { metadata: '0x…', decimals: 6 }, amount: '0.05', payTo })
+
+// On Algorand, a custom ASA is { assetId, decimals }:
+requirePayment({ chain: 'algorand', token: { assetId: 12345678, decimals: 6 }, amount: '0.05', payTo })
 ```
 
 > **Production:** the built-in chains use public RPCs (rate-limited). Pass your own `rpcUrl` for real traffic.
@@ -603,7 +611,7 @@ Methods: `fetch` · `get` · `post` (return the gated `Response` after settlemen
 
 **Hand an LLM a wallet:** `paymentTools(client)` → framework-agnostic tool descriptors (MCP / AI SDK / function-calling), budget enforced by the client.
 
-**Bring your own chain family:** the SDK is built on a tiny `PaymentDriver` contract — `resolve(chain)` returns a bound network with `resolveToken` / `describeAsset` / `assertValidPayTo` / `bindWallet` / `send` / `confirm` / `estimateCost` / `verify`. Register your own with `registerDriver(...)`; the protocol layer never changes (see [Architecture](#architecture-under-the-hood)).
+**Bring your own chain family:** the SDK is built on a tiny `PaymentDriver` contract — `resolve(chain)` returns a bound network with `resolveToken` / `describeAsset` / `assertValidPayTo` / `bindWallet` / `send` / `confirm` / `estimateCost` / `balanceOf` / `recipientReady` / `verify`. Register your own with `registerDriver(...)`; the protocol layer never changes (see [Architecture](#architecture-under-the-hood)).
 
 **Universal x402 (experimental):** building blocks to pay servers on the mainstream x402 `exact` scheme (EIP-3009 + facilitator) — `parseExactRequirements`, `buildExactAuthorization`, `encodeXPaymentHeader`. EVM-only; validate against your target facilitator before production.
 

package/dist/index.cjs

@@ -733,7 +733,7 @@ function makeEvmNetwork(resolved) {
       }
       return { token, native };
     },
-    // EVM has no receive prerequisite — any 0x address receives native or ERC-20 immediately.
+    // No receive prerequisite — any 0x address receives native or ERC-20 immediately.
     async recipientReady() {
       return { ready: "n/a" };
     },
@@ -923,7 +923,12 @@ function evaluatePolicy(intent, policy, spentForAssetBase) {
   }
   if (policy.tokens) {
     const sym = intent.recognized ? intent.symbol : void 0;
-    if (!sym || !policy.tokens.some((t) => t.toUpperCase() === sym.toUpperCase())) {
+    const isNative = intent.asset === "native";
+    const matches = policy.tokens.some((t) => {
+      if (isNative && t.toUpperCase() === "NATIVE") return true;
+      return sym ? t.toUpperCase() === sym.toUpperCase() : false;
+    });
+    if (!matches) {
       return deny(
         `token ${_nullishCoalesce(intent.symbol, () => ( intent.asset))} is not in the allowed set (policy.tokens).`
       );

package/dist/index.d.cts

@@ -3845,7 +3845,7 @@ interface AlgorandToken {
 }
 /**
  * What to be paid in. Each driver validates the forms it accepts:
- *   - 'native'        the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP)
+ *   - 'native'        the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP, TRX, NEAR, SUI, APT, ALGO)
  *   - 'USDC' (string) a symbol resolved against the chosen chain
  *   - EvmToken        any ERC-20         (EVM chains)
  *   - SolanaToken     any SPL token      (Solana)
@@ -4014,8 +4014,11 @@ interface PaymentPolicy {
     /** 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. */
     chains?: ChainSelector[];
-    /** Allowlist of token symbols (matched against the TRUE symbol). An asset the
-     *  SDK can't recognise never satisfies this list. */
+    /** Allowlist of token symbols (matched against the TRUE symbol). The special
+     *  value `'native'` is a chain-agnostic alias for the chain's native coin — it
+     *  matches the native asset on ANY family (ETH/BNB/TRX/XLM/…) without naming
+     *  the ticker, mirroring the merchant-side `token: 'native'`. An asset the SDK
+     *  can't recognise never satisfies this list. */
     tokens?: string[];
     /** Allowlist of hosts. Exact (`api.example.com`) or wildcard (`*.example.com`). */
     hosts?: string[];
@@ -4130,6 +4133,8 @@ type PipRailEvent = {
  *   - Stellar → `{ secret }` (S… seed) or a ready `{ keypair }`
  *   - XRPL    → `{ seed }` (s… seed) or a ready `{ wallet }`
  *   - NEAR    → `{ accountId, privateKey }` (privateKey = ed25519:… secret)
+ *   - Aptos   → `{ privateKey }` (AIP-80 `ed25519-priv-0x…` / raw `0x…` hex) or `{ account }`
+ *   - Algorand→ `{ mnemonic }` (25 words) or a ready `{ account }`
  */
 type WalletInput = {
     privateKey: string;
@@ -4263,7 +4268,7 @@ interface PipRailClientOptions {
     /** Wallet for the chosen chain family. */
     wallet: WalletInput;
     /** Which chain to pay on. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar',
-     *  'xrpl', 'tron', 'sui', or 'near'. */
+     *  'xrpl', 'tron', 'sui', 'near', 'aptos', or 'algorand'. */
     chain: ChainSelector;
     /** Override the chain's default RPC URL (recommended in production). */
     rpcUrl?: string;
@@ -4441,8 +4446,10 @@ interface AgentTool {
     invoke: (args: Record<string, unknown>) => Promise<unknown>;
 }
 /**
- * Two tools wrapping a configured {@link PipRailClient}:
+ * Three tools wrapping a configured {@link PipRailClient}:
  *   - `piprail_quote_payment(url)` — price a gated URL WITHOUT paying.
+ *   - `piprail_plan_payment(url)` — check you CAN pay (balance + gas + recipient
+ *     readiness) across every rail the URL offers, WITHOUT paying.
  *   - `piprail_pay_request(url, method?, body?)` — pay if needed and return the result.
  *
  * A policy/approval refusal comes back as a structured `{ declined: true, reason }`
@@ -4478,7 +4485,7 @@ declare function paymentTools(client: PipRailClient): AgentTool[];
  */
 interface AcceptOption {
     /** Which chain. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar', 'xrpl',
-     *  'tron', 'near', or 'sui'. */
+     *  'tron', 'near', 'sui', 'aptos', or 'algorand'. */
     chain: ChainSelector;
     /** Token to be paid in (symbol / 'native' / custom descriptor). */
     token: TokenInput;
@@ -4492,8 +4499,9 @@ interface AcceptOption {
 interface RequirePaymentOptions {
     /**
      * Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
-     * 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near', or 'sui'. Provide
-     * `chain` + `token` + `amount`, OR use the multi-chain `accept` array below.
+     * 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near', 'sui', 'aptos', or
+     * 'algorand'. Provide `chain` + `token` + `amount`, OR use the multi-chain
+     * `accept` array below.
      */
     chain?: ChainSelector;
     /** Override the chain's default RPC URL (recommended in production). */
@@ -4504,9 +4512,10 @@ interface RequirePaymentOptions {
      * `{ address, decimals }` on EVM/Tron, `{ mint, decimals }` on Solana,
      * `{ master, decimals }` on TON, `{ issuer, code, decimals }` on Stellar,
      * `{ issuer, currencyHex, decimals }` on XRPL, `{ contractId, decimals }` on
-     * NEAR, `{ coinType, decimals }` on Sui. You name the token; the SDK fills in
+     * NEAR, `{ coinType, decimals }` on Sui, `{ metadata, decimals }` on Aptos, or
+     * `{ assetId, decimals }` on Algorand. You name the token; the SDK fills in
      * the contract + decimals for built-in symbols. (Note: native USDC doesn't
-     * exist on TON/Tron — USDT does; NEAR is FT-only, so `'native'` is rejected.)
+     * exist on TON/Tron — USDT does; native NEAR is supported via `'native'`.)
      */
     token?: TokenInput;
     /** Human-readable amount, e.g. "0.05" (single-chain form). */
@@ -4518,8 +4527,8 @@ interface RequirePaymentOptions {
      */
     accept?: AcceptOption[];
     /** Address that receives the payment (0x… EVM/Sui, base58 Solana, EQ…/UQ… TON,
-     *  G… Stellar, r… XRPL, T… Tron, account id on NEAR). Required for the single
-     *  form; the per-option fallback for the multi form. */
+     *  G… Stellar, r… XRPL, T… Tron, account id on NEAR, 0x… Aptos, base32 Algorand).
+     *  Required for the single form; the per-option fallback for the multi form. */
     payTo?: AddressId;
     /** Shown to the agent in the challenge. */
     description?: string;
@@ -4669,7 +4678,7 @@ declare class InsufficientFundsError extends PipRailError {
  * The message states the requirement and the fix in plain language **and echoes
  * the raw chain code** (e.g. `(XRPL: tecNO_DST_INSUF_XRP)`), while the untouched
  * chain error is preserved on `.cause` for deeper debugging. Chains with no
- * receive prerequisite (EVM, Solana, Sui, Tron, and native TON/NEAR) never throw it.
+ * receive prerequisite (EVM, Solana, Sui, Aptos, Tron, and native TON/NEAR) never throw it.
  */
 declare class RecipientNotReadyError extends PipRailError {
     readonly code = "RECIPIENT_NOT_READY";
@@ -4766,7 +4775,7 @@ declare class NonReplayableBodyError extends PipRailError {
 }
 /**
  * The chosen chain belongs to one family (EVM, Solana, TON, Stellar, XRPL, Tron,
- * Sui, NEAR) but the wallet, payTo, or token was given in another family's form
+ * Sui, NEAR, Aptos, Algorand) but the wallet, payTo, or token was given in another family's form
  * (e.g. an `0x…` payTo on Solana, or a `{ mint }` token on a Stellar chain).
  */
 declare class WrongFamilyError extends PipRailError {
@@ -4778,7 +4787,8 @@ declare class WrongFamilyError extends PipRailError {
  * token by full descriptor ({ address, decimals } EVM/Tron · { mint, decimals }
  * Solana · { master, decimals } TON · { issuer, code, decimals } Stellar ·
  * { issuer, currencyHex, decimals } XRPL · { coinType, decimals } Sui ·
- * { contractId, decimals } NEAR).
+ * { contractId, decimals } NEAR · { metadata, decimals } Aptos ·
+ * { assetId, decimals } Algorand).
  */
 declare class UnknownTokenError extends PipRailError {
     readonly code = "UNKNOWN_TOKEN";
@@ -4790,7 +4800,8 @@ declare class UnknownTokenError extends PipRailError {
  * `npm install @ton/ton @ton/core @ton/crypto`; Stellar:
  * `npm install @stellar/stellar-sdk`; XRPL: `npm install xrpl`; Tron:
  * `npm install tronweb`; Sui: `npm install @mysten/sui`; NEAR:
- * `npm install near-api-js`.
+ * `npm install near-api-js`; Aptos: `npm install @aptos-labs/ts-sdk`;
+ * Algorand: `npm install algosdk`.
  */
 declare class MissingDriverError extends PipRailError {
     readonly code = "MISSING_DRIVER";

package/dist/index.d.ts

@@ -3845,7 +3845,7 @@ interface AlgorandToken {
 }
 /**
  * What to be paid in. Each driver validates the forms it accepts:
- *   - 'native'        the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP)
+ *   - 'native'        the chain's native coin (ETH, BNB, SOL, TON, XLM, XRP, TRX, NEAR, SUI, APT, ALGO)
  *   - 'USDC' (string) a symbol resolved against the chosen chain
  *   - EvmToken        any ERC-20         (EVM chains)
  *   - SolanaToken     any SPL token      (Solana)
@@ -4014,8 +4014,11 @@ interface PaymentPolicy {
     /** 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. */
     chains?: ChainSelector[];
-    /** Allowlist of token symbols (matched against the TRUE symbol). An asset the
-     *  SDK can't recognise never satisfies this list. */
+    /** Allowlist of token symbols (matched against the TRUE symbol). The special
+     *  value `'native'` is a chain-agnostic alias for the chain's native coin — it
+     *  matches the native asset on ANY family (ETH/BNB/TRX/XLM/…) without naming
+     *  the ticker, mirroring the merchant-side `token: 'native'`. An asset the SDK
+     *  can't recognise never satisfies this list. */
     tokens?: string[];
     /** Allowlist of hosts. Exact (`api.example.com`) or wildcard (`*.example.com`). */
     hosts?: string[];
@@ -4130,6 +4133,8 @@ type PipRailEvent = {
  *   - Stellar → `{ secret }` (S… seed) or a ready `{ keypair }`
  *   - XRPL    → `{ seed }` (s… seed) or a ready `{ wallet }`
  *   - NEAR    → `{ accountId, privateKey }` (privateKey = ed25519:… secret)
+ *   - Aptos   → `{ privateKey }` (AIP-80 `ed25519-priv-0x…` / raw `0x…` hex) or `{ account }`
+ *   - Algorand→ `{ mnemonic }` (25 words) or a ready `{ account }`
  */
 type WalletInput = {
     privateKey: string;
@@ -4263,7 +4268,7 @@ interface PipRailClientOptions {
     /** Wallet for the chosen chain family. */
     wallet: WalletInput;
     /** Which chain to pay on. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar',
-     *  'xrpl', 'tron', 'sui', or 'near'. */
+     *  'xrpl', 'tron', 'sui', 'near', 'aptos', or 'algorand'. */
     chain: ChainSelector;
     /** Override the chain's default RPC URL (recommended in production). */
     rpcUrl?: string;
@@ -4441,8 +4446,10 @@ interface AgentTool {
     invoke: (args: Record<string, unknown>) => Promise<unknown>;
 }
 /**
- * Two tools wrapping a configured {@link PipRailClient}:
+ * Three tools wrapping a configured {@link PipRailClient}:
  *   - `piprail_quote_payment(url)` — price a gated URL WITHOUT paying.
+ *   - `piprail_plan_payment(url)` — check you CAN pay (balance + gas + recipient
+ *     readiness) across every rail the URL offers, WITHOUT paying.
  *   - `piprail_pay_request(url, method?, body?)` — pay if needed and return the result.
  *
  * A policy/approval refusal comes back as a structured `{ declined: true, reason }`
@@ -4478,7 +4485,7 @@ declare function paymentTools(client: PipRailClient): AgentTool[];
  */
 interface AcceptOption {
     /** Which chain. EVM ('bnb'|'base'|…), 'solana', 'ton', 'stellar', 'xrpl',
-     *  'tron', 'near', or 'sui'. */
+     *  'tron', 'near', 'sui', 'aptos', or 'algorand'. */
     chain: ChainSelector;
     /** Token to be paid in (symbol / 'native' / custom descriptor). */
     token: TokenInput;
@@ -4492,8 +4499,9 @@ interface AcceptOption {
 interface RequirePaymentOptions {
     /**
      * Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
-     * 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near', or 'sui'. Provide
-     * `chain` + `token` + `amount`, OR use the multi-chain `accept` array below.
+     * 'solana', 'ton', 'stellar', 'xrpl', 'tron', 'near', 'sui', 'aptos', or
+     * 'algorand'. Provide `chain` + `token` + `amount`, OR use the multi-chain
+     * `accept` array below.
      */
     chain?: ChainSelector;
     /** Override the chain's default RPC URL (recommended in production). */
@@ -4504,9 +4512,10 @@ interface RequirePaymentOptions {
      * `{ address, decimals }` on EVM/Tron, `{ mint, decimals }` on Solana,
      * `{ master, decimals }` on TON, `{ issuer, code, decimals }` on Stellar,
      * `{ issuer, currencyHex, decimals }` on XRPL, `{ contractId, decimals }` on
-     * NEAR, `{ coinType, decimals }` on Sui. You name the token; the SDK fills in
+     * NEAR, `{ coinType, decimals }` on Sui, `{ metadata, decimals }` on Aptos, or
+     * `{ assetId, decimals }` on Algorand. You name the token; the SDK fills in
      * the contract + decimals for built-in symbols. (Note: native USDC doesn't
-     * exist on TON/Tron — USDT does; NEAR is FT-only, so `'native'` is rejected.)
+     * exist on TON/Tron — USDT does; native NEAR is supported via `'native'`.)
      */
     token?: TokenInput;
     /** Human-readable amount, e.g. "0.05" (single-chain form). */
@@ -4518,8 +4527,8 @@ interface RequirePaymentOptions {
      */
     accept?: AcceptOption[];
     /** Address that receives the payment (0x… EVM/Sui, base58 Solana, EQ…/UQ… TON,
-     *  G… Stellar, r… XRPL, T… Tron, account id on NEAR). Required for the single
-     *  form; the per-option fallback for the multi form. */
+     *  G… Stellar, r… XRPL, T… Tron, account id on NEAR, 0x… Aptos, base32 Algorand).
+     *  Required for the single form; the per-option fallback for the multi form. */
     payTo?: AddressId;
     /** Shown to the agent in the challenge. */
     description?: string;
@@ -4669,7 +4678,7 @@ declare class InsufficientFundsError extends PipRailError {
  * The message states the requirement and the fix in plain language **and echoes
  * the raw chain code** (e.g. `(XRPL: tecNO_DST_INSUF_XRP)`), while the untouched
  * chain error is preserved on `.cause` for deeper debugging. Chains with no
- * receive prerequisite (EVM, Solana, Sui, Tron, and native TON/NEAR) never throw it.
+ * receive prerequisite (EVM, Solana, Sui, Aptos, Tron, and native TON/NEAR) never throw it.
  */
 declare class RecipientNotReadyError extends PipRailError {
     readonly code = "RECIPIENT_NOT_READY";
@@ -4766,7 +4775,7 @@ declare class NonReplayableBodyError extends PipRailError {
 }
 /**
  * The chosen chain belongs to one family (EVM, Solana, TON, Stellar, XRPL, Tron,
- * Sui, NEAR) but the wallet, payTo, or token was given in another family's form
+ * Sui, NEAR, Aptos, Algorand) but the wallet, payTo, or token was given in another family's form
  * (e.g. an `0x…` payTo on Solana, or a `{ mint }` token on a Stellar chain).
  */
 declare class WrongFamilyError extends PipRailError {
@@ -4778,7 +4787,8 @@ declare class WrongFamilyError extends PipRailError {
  * token by full descriptor ({ address, decimals } EVM/Tron · { mint, decimals }
  * Solana · { master, decimals } TON · { issuer, code, decimals } Stellar ·
  * { issuer, currencyHex, decimals } XRPL · { coinType, decimals } Sui ·
- * { contractId, decimals } NEAR).
+ * { contractId, decimals } NEAR · { metadata, decimals } Aptos ·
+ * { assetId, decimals } Algorand).
  */
 declare class UnknownTokenError extends PipRailError {
     readonly code = "UNKNOWN_TOKEN";
@@ -4790,7 +4800,8 @@ declare class UnknownTokenError extends PipRailError {
  * `npm install @ton/ton @ton/core @ton/crypto`; Stellar:
  * `npm install @stellar/stellar-sdk`; XRPL: `npm install xrpl`; Tron:
  * `npm install tronweb`; Sui: `npm install @mysten/sui`; NEAR:
- * `npm install near-api-js`.
+ * `npm install near-api-js`; Aptos: `npm install @aptos-labs/ts-sdk`;
+ * Algorand: `npm install algosdk`.
  */
 declare class MissingDriverError extends PipRailError {
     readonly code = "MISSING_DRIVER";

package/dist/index.js

@@ -733,7 +733,7 @@ function makeEvmNetwork(resolved) {
       }
       return { token, native };
     },
-    // EVM has no receive prerequisite — any 0x address receives native or ERC-20 immediately.
+    // No receive prerequisite — any 0x address receives native or ERC-20 immediately.
     async recipientReady() {
       return { ready: "n/a" };
     },
@@ -923,7 +923,12 @@ function evaluatePolicy(intent, policy, spentForAssetBase) {
   }
   if (policy.tokens) {
     const sym = intent.recognized ? intent.symbol : void 0;
-    if (!sym || !policy.tokens.some((t) => t.toUpperCase() === sym.toUpperCase())) {
+    const isNative = intent.asset === "native";
+    const matches = policy.tokens.some((t) => {
+      if (isNative && t.toUpperCase() === "NATIVE") return true;
+      return sym ? t.toUpperCase() === sym.toUpperCase() : false;
+    });
+    if (!matches) {
       return deny(
         `token ${intent.symbol ?? intent.asset} is not in the allowed set (policy.tokens).`
       );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Accept x402 crypto payments across 28 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",
@@ -82,13 +82,13 @@
   "peerDependencies": {
     "@aptos-labs/ts-sdk": ">=2 <8",
     "@mysten/sui": ">=2 <3",
-    "algosdk": ">=3 <4",
     "@solana/spl-token": "^0.4.0",
     "@solana/web3.js": "^1.95.0",
     "@stellar/stellar-sdk": ">=13 <16",
     "@ton/core": ">=0.59 <1",
     "@ton/crypto": ">=3 <4",
     "@ton/ton": ">=15 <17",
+    "algosdk": ">=3 <4",
     "bs58": "^5.0.0",
     "near-api-js": ">=7 <8",
     "tronweb": ">=6 <7",