@piprail/sdk 3.1.1 → 3.1.2

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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/).
 
+## [3.1.2] — 2026-09-09 — a balance says what it means
+
+### Fixed
+
+- **Three descriptions of a balance still said HOLDS after 3.1.0 made it SPENDABLE.** 3.1.0
+  changed the drivers to deduct a chain's retained minimum (Solana rent, XRPL/Stellar/Algorand
+  reserves) from the native figure, and documented that precisely on `WalletBalance.token` — but
+  every layer above it kept the old wording. `PipRailClient.balanceOf`'s TSDoc, the interface it
+  implements, and the `piprail_wallet` tool description a MODEL reads all still promised "what you
+  hold". They now say what they mean, and name the gap as locked rather than lost.
+
+  The wording mattered most in the tool description, because an agent comparing its own balance
+  against a block explorer sees a smaller number and has to decide whether it is being lied to. On
+  a live Stellar account holding 1.5398 XLM with three subentries, `balanceOf` reports 0.0398: the
+  1.5 XLM difference is the base reserve. Text only; no behaviour changes.
+
 ## [3.1.1] — 2026-09-09 — XRPL payments work again
 
 ### Fixed
@@ -2666,6 +2682,7 @@ straight into your wallet. The API is small and self-contained.
 [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
+[3.1.2]: https://www.npmjs.com/package/@piprail/sdk
 [3.1.1]: https://www.npmjs.com/package/@piprail/sdk
 [3.1.0]: https://www.npmjs.com/package/@piprail/sdk
 [3.0.0]: https://www.npmjs.com/package/@piprail/sdk

package/dist/index.cjs

@@ -3800,7 +3800,16 @@ var PipRailClient = (_class2 = class {
     return this.opts.chain;
   }
   /**
-   * What this wallet actually HOLDS, per asset — the balance sheet, not the leash.
+   * What this wallet can actually SPEND, per asset — the balance sheet, not the leash.
+   *
+   * 🔴 For a NATIVE asset this is not always what the chain says the account holds. Solana
+   * (rent exemption), XRPL (base + owner reserve), Stellar (base reserve per subentry) and
+   * Algorand (minimum balance) all require an account to retain a minimum it can never send,
+   * and since 3.1.0 the drivers report that reserve DEDUCTED, because affordability measured
+   * against the raw balance calls a payment affordable right up until the chain refuses it.
+   * Live example: a Stellar account holding 1.5398 XLM with three subentries reports 0.0398,
+   * the 1.5 XLM difference being the reserve. That is the number to spend against; it is not
+   * missing money. `estimateCost()` judges gas against the TRUE balance separately.
    *
    * `budget()` answers "how much of my allowance is left", a different question and the only
    * one an agent could previously ask. An agent that OWNS a wallet has to answer "what do I
@@ -8311,7 +8320,7 @@ function paymentTools(client) {
     },
     {
       name: "piprail_wallet",
-      description: "What YOU hold, and where you get paid \u2014 your balance sheet, which is a different question from piprail_budget (that is how much of your allowance is left). Returns your own address per chain plus the amount of each asset you actually hold. Use it before deciding to sell, swap or ask to be topped up, and give the address to anyone who needs to send you funds. A null amount means the read was UNAVAILABLE, not zero: do NOT treat it as being broke. Read-only; moves nothing and needs no approval.",
+      description: "What YOU can SPEND, and where you get paid \u2014 your balance sheet, which is a different question from piprail_budget (that is how much of your allowance is left). Returns your own address per chain plus the spendable amount of each asset. Use it before deciding to sell, swap or ask to be topped up, and give the address to anyone who needs to send you funds. On some chains a native amount is LOWER than the figure a block explorer shows, because the chain makes an account retain a minimum it can never send (Solana, XRPL, Stellar, Algorand). That gap is locked, not lost, and this number is the one you can actually pay with. A null amount means the read was UNAVAILABLE, not zero: do NOT treat it as being broke. Read-only; moves nothing and needs no approval.",
       annotations: {
         title: "Your wallet",
         readOnlyHint: true,

package/dist/index.d.cts

@@ -5974,7 +5974,9 @@ interface PayingClient {
     canAgentSell?(): boolean;
     /** The chain this client is configured for — the default an offer is priced on. */
     chain?(): ChainSelector;
-    /** What this wallet HOLDS, per asset — the balance sheet, distinct from the budget leash. */
+    /** What this wallet can SPEND, per asset — the balance sheet, distinct from the budget
+     *  leash. On a chain with a retained minimum (Solana rent, XRPL/Stellar/Algorand
+     *  reserves) a native balance reports the reserve DEDUCTED. See {@link WalletBalance}. */
     balanceOf?(assets?: readonly string[]): Promise<WalletAssetBalance[]>;
 }
 /**
@@ -6214,7 +6216,16 @@ declare class PipRailClient {
      *  defaults to it, so an agent prices on the chain it actually holds funds on. */
     chain(): ChainSelector;
     /**
-     * What this wallet actually HOLDS, per asset — the balance sheet, not the leash.
+     * What this wallet can actually SPEND, per asset — the balance sheet, not the leash.
+     *
+     * 🔴 For a NATIVE asset this is not always what the chain says the account holds. Solana
+     * (rent exemption), XRPL (base + owner reserve), Stellar (base reserve per subentry) and
+     * Algorand (minimum balance) all require an account to retain a minimum it can never send,
+     * and since 3.1.0 the drivers report that reserve DEDUCTED, because affordability measured
+     * against the raw balance calls a payment affordable right up until the chain refuses it.
+     * Live example: a Stellar account holding 1.5398 XLM with three subentries reports 0.0398,
+     * the 1.5 XLM difference being the reserve. That is the number to spend against; it is not
+     * missing money. `estimateCost()` judges gas against the TRUE balance separately.
      *
      * `budget()` answers "how much of my allowance is left", a different question and the only
      * one an agent could previously ask. An agent that OWNS a wallet has to answer "what do I

package/dist/index.d.ts

@@ -5974,7 +5974,9 @@ interface PayingClient {
     canAgentSell?(): boolean;
     /** The chain this client is configured for — the default an offer is priced on. */
     chain?(): ChainSelector;
-    /** What this wallet HOLDS, per asset — the balance sheet, distinct from the budget leash. */
+    /** What this wallet can SPEND, per asset — the balance sheet, distinct from the budget
+     *  leash. On a chain with a retained minimum (Solana rent, XRPL/Stellar/Algorand
+     *  reserves) a native balance reports the reserve DEDUCTED. See {@link WalletBalance}. */
     balanceOf?(assets?: readonly string[]): Promise<WalletAssetBalance[]>;
 }
 /**
@@ -6214,7 +6216,16 @@ declare class PipRailClient {
      *  defaults to it, so an agent prices on the chain it actually holds funds on. */
     chain(): ChainSelector;
     /**
-     * What this wallet actually HOLDS, per asset — the balance sheet, not the leash.
+     * What this wallet can actually SPEND, per asset — the balance sheet, not the leash.
+     *
+     * 🔴 For a NATIVE asset this is not always what the chain says the account holds. Solana
+     * (rent exemption), XRPL (base + owner reserve), Stellar (base reserve per subentry) and
+     * Algorand (minimum balance) all require an account to retain a minimum it can never send,
+     * and since 3.1.0 the drivers report that reserve DEDUCTED, because affordability measured
+     * against the raw balance calls a payment affordable right up until the chain refuses it.
+     * Live example: a Stellar account holding 1.5398 XLM with three subentries reports 0.0398,
+     * the 1.5 XLM difference being the reserve. That is the number to spend against; it is not
+     * missing money. `estimateCost()` judges gas against the TRUE balance separately.
      *
      * `budget()` answers "how much of my allowance is left", a different question and the only
      * one an agent could previously ask. An agent that OWNS a wallet has to answer "what do I

package/dist/index.js

@@ -3800,7 +3800,16 @@ var PipRailClient = class {
     return this.opts.chain;
   }
   /**
-   * What this wallet actually HOLDS, per asset — the balance sheet, not the leash.
+   * What this wallet can actually SPEND, per asset — the balance sheet, not the leash.
+   *
+   * 🔴 For a NATIVE asset this is not always what the chain says the account holds. Solana
+   * (rent exemption), XRPL (base + owner reserve), Stellar (base reserve per subentry) and
+   * Algorand (minimum balance) all require an account to retain a minimum it can never send,
+   * and since 3.1.0 the drivers report that reserve DEDUCTED, because affordability measured
+   * against the raw balance calls a payment affordable right up until the chain refuses it.
+   * Live example: a Stellar account holding 1.5398 XLM with three subentries reports 0.0398,
+   * the 1.5 XLM difference being the reserve. That is the number to spend against; it is not
+   * missing money. `estimateCost()` judges gas against the TRUE balance separately.
    *
    * `budget()` answers "how much of my allowance is left", a different question and the only
    * one an agent could previously ask. An agent that OWNS a wallet has to answer "what do I
@@ -8311,7 +8320,7 @@ function paymentTools(client) {
     },
     {
       name: "piprail_wallet",
-      description: "What YOU hold, and where you get paid \u2014 your balance sheet, which is a different question from piprail_budget (that is how much of your allowance is left). Returns your own address per chain plus the amount of each asset you actually hold. Use it before deciding to sell, swap or ask to be topped up, and give the address to anyone who needs to send you funds. A null amount means the read was UNAVAILABLE, not zero: do NOT treat it as being broke. Read-only; moves nothing and needs no approval.",
+      description: "What YOU can SPEND, and where you get paid \u2014 your balance sheet, which is a different question from piprail_budget (that is how much of your allowance is left). Returns your own address per chain plus the spendable amount of each asset. Use it before deciding to sell, swap or ask to be topped up, and give the address to anyone who needs to send you funds. On some chains a native amount is LOWER than the figure a block explorer shows, because the chain makes an account retain a minimum it can never send (Solana, XRPL, Stellar, Algorand). That gap is locked, not lost, and this number is the one you can actually pay with. A null amount means the read was UNAVAILABLE, not zero: do NOT treat it as being broke. Read-only; moves nothing and needs no approval.",
       annotations: {
         title: "Your wallet",
         readOnlyHint: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "description": "Accept x402 crypto payments across 30 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",