@piprail/sdk 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ 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
@@ -406,6 +417,7 @@ 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

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)

package/dist/index.cjs

@@ -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

@@ -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[];

package/dist/index.d.ts

@@ -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[];

package/dist/index.js

@@ -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.1",
+  "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",