@one-source/api-mcp 5.2.1 → 5.3.1

package/README.md

@@ -1,6 +1,6 @@
 # onesource-api-mcp
 
-MCP server for OneSource blockchain data. 26 named tools for balances, NFTs, transactions, events, and live chain queries via API key or x402 micropayments.
+MCP server for OneSource blockchain data. 27 named tools for balances, NFTs, transactions, events, and live chain queries via API key or x402 micropayments.
 
 ```
 npx onesource-api-mcp
@@ -23,7 +23,7 @@ claude mcp add onesource-api -- npx onesource-api-mcp
 }
 ```
 
-## Tools (26)
+## Tools (27)
 
 
 ### Live Chain Data (12 tools)
@@ -62,11 +62,12 @@ claude mcp add onesource-api -- npx onesource-api-mcp
 | `1s_storage_read` | Read storage slot |
 | `1s_tx_receipt` | Transaction receipt |
 
-### Session (1 tool)
+### Payments (2 tools)
 
 | Tool | Description |
 |------|-------------|
 | `1s_payment_mode` | View or switch the x402 payment scheme (`exact` per-call vs `batch` payment channel) |
+| `1s_refund` | Refund unused `batch` channel balance back to your wallet on demand |
 
 
 ## Networks
@@ -117,6 +118,8 @@ X402_PRIVATE_KEY=your-private-key-hex npx onesource-api-mcp
 
 Payments default to the **exact** scheme (one USDC payment per call). For a burst of calls you can switch to **batch** settlement — a payment channel that funds many off-chain calls from a single on-chain deposit, settled with one claim — by calling the `1s_payment_mode` tool with `{ "mode": "batch" }`, or by setting `X402_PAYMENT_MODE=batch`. Both modes use the same wallet.
 
+In batch mode the first paid call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10) up front, so a session typically over-funds the channel. Reclaim the unused balance whenever you're done with the `1s_refund` tool; idle channels are also auto-refunded by the receiver after a few hours. The deposit residual is always recoverable.
+
 ### No auth
 
 Without either variable, tools work for free endpoints. Paid endpoints return 402 errors with a descriptive message.
@@ -132,8 +135,8 @@ Without either variable, tools work for free endpoints. Paid endpoints return 40
 | `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with the `1s_payment_mode` tool. |
 | `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode |
 | `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
-| `X402_DEPOSIT_MULTIPLIER` | `5` | Batch mode: deposit = price × this multiplier, funding that many calls per channel |
-| `X402_CHANNEL_SALT` | zero | Batch mode: 32-byte hex salt to derive a distinct channel id |
+| `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
+| `X402_CHANNEL_SALT` | zero | Batch mode: 32-byte hex salt to derive the starting channel id. The client auto-rotates to the next salt when a channel is exhausted or refunded. |
 
 
 ## License

package/README.npm.md

@@ -1,6 +1,6 @@
 # onesource-api-mcp
 
-MCP server for OneSource blockchain data. 26 named tools for balances, NFTs, transactions, events, and live chain queries via API key or x402 micropayments.
+MCP server for OneSource blockchain data. 27 named tools for balances, NFTs, transactions, events, and live chain queries via API key or x402 micropayments.
 
 ```
 npx onesource-api-mcp
@@ -23,7 +23,7 @@ claude mcp add onesource-api -- npx onesource-api-mcp
 }
 ```
 
-## Tools (26)
+## Tools (27)
 
 
 ### Live Chain Data (12 tools)
@@ -62,11 +62,12 @@ claude mcp add onesource-api -- npx onesource-api-mcp
 | `1s_storage_read` | Read storage slot |
 | `1s_tx_receipt` | Transaction receipt |
 
-### Session (1 tool)
+### Payments (2 tools)
 
 | Tool | Description |
 |------|-------------|
 | `1s_payment_mode` | View or switch the x402 payment scheme (`exact` per-call vs `batch` payment channel) |
+| `1s_refund` | Refund unused `batch` channel balance back to your wallet on demand |
 
 
 ## Networks
@@ -117,6 +118,8 @@ X402_PRIVATE_KEY=your-private-key-hex npx onesource-api-mcp
 
 Payments default to the **exact** scheme (one USDC payment per call). For a burst of calls you can switch to **batch** settlement — a payment channel that funds many off-chain calls from a single on-chain deposit, settled with one claim — by calling the `1s_payment_mode` tool with `{ "mode": "batch" }`, or by setting `X402_PAYMENT_MODE=batch`. Both modes use the same wallet.
 
+In batch mode the first paid call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10) up front, so a session typically over-funds the channel. Reclaim the unused balance whenever you're done with the `1s_refund` tool; idle channels are also auto-refunded by the receiver after a few hours. The deposit residual is always recoverable.
+
 ### No auth
 
 Without either variable, tools work for free endpoints. Paid endpoints return 402 errors with a descriptive message.
@@ -132,8 +135,8 @@ Without either variable, tools work for free endpoints. Paid endpoints return 40
 | `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with the `1s_payment_mode` tool. |
 | `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode |
 | `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
-| `X402_DEPOSIT_MULTIPLIER` | `5` | Batch mode: deposit = price × this multiplier, funding that many calls per channel |
-| `X402_CHANNEL_SALT` | zero | Batch mode: 32-byte hex salt to derive a distinct channel id |
+| `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
+| `X402_CHANNEL_SALT` | zero | Batch mode: 32-byte hex salt to derive the starting channel id. The client auto-rotates to the next salt when a channel is exhausted or refunded. |
 
 
 ## License

package/README.repo.md

@@ -1,6 +1,6 @@
 # onesource-api-mcp
 
-MCP server for OneSource blockchain data. 26 named tools for balances, NFTs, transactions, events, and live chain queries via API key or x402 micropayments.
+MCP server for OneSource blockchain data. 27 named tools for balances, NFTs, transactions, events, and live chain queries via API key or x402 micropayments.
 
 ```
 npx onesource-api-mcp
@@ -23,7 +23,7 @@ claude mcp add onesource-api -- npx onesource-api-mcp
 }
 ```
 
-## Tools (26)
+## Tools (27)
 
 
 ### Live Chain Data (12 tools)
@@ -62,11 +62,12 @@ claude mcp add onesource-api -- npx onesource-api-mcp
 | `1s_storage_read` | Read storage slot |
 | `1s_tx_receipt` | Transaction receipt |
 
-### Session (1 tool)
+### Payments (2 tools)
 
 | Tool | Description |
 |------|-------------|
 | `1s_payment_mode` | View or switch the x402 payment scheme (`exact` per-call vs `batch` payment channel) |
+| `1s_refund` | Refund unused `batch` channel balance back to your wallet on demand |
 
 
 ## Networks
@@ -117,6 +118,8 @@ X402_PRIVATE_KEY=your-private-key-hex npx onesource-api-mcp
 
 Payments default to the **exact** scheme (one USDC payment per call). For a burst of calls you can switch to **batch** settlement — a payment channel that funds many off-chain calls from a single on-chain deposit, settled with one claim — by calling the `1s_payment_mode` tool with `{ "mode": "batch" }`, or by setting `X402_PAYMENT_MODE=batch`. Both modes use the same wallet.
 
+In batch mode the first paid call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10) up front, so a session typically over-funds the channel. Reclaim the unused balance whenever you're done with the `1s_refund` tool; idle channels are also auto-refunded by the receiver after a few hours. The deposit residual is always recoverable.
+
 ### No auth
 
 Without either variable, tools work for free endpoints. Paid endpoints return 402 errors with a descriptive message.
@@ -132,8 +135,8 @@ Without either variable, tools work for free endpoints. Paid endpoints return 40
 | `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with the `1s_payment_mode` tool. |
 | `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode |
 | `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
-| `X402_DEPOSIT_MULTIPLIER` | `5` | Batch mode: deposit = price × this multiplier, funding that many calls per channel |
-| `X402_CHANNEL_SALT` | zero | Batch mode: 32-byte hex salt to derive a distinct channel id |
+| `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
+| `X402_CHANNEL_SALT` | zero | Batch mode: 32-byte hex salt to derive the starting channel id. The client auto-rotates to the next salt when a channel is exhausted or refunded. |
 | `ONESOURCE_ANALYTICS` | `true` | Set `false` to disable all analytics |
 | `ONESOURCE_ANALYTICS_URL` | `https://1s-analytics.vercel.app` | Dashboard endpoint for event ingestion (baked in by default) |
 | `X402_ANALYTICS_KEY` | `onesource-api-mcp` | Bearer token for the analytics dashboard (baked in by default) |

package/dist/tools/chain/refund.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 1s_refund — reclaim unused x402 batch-channel escrow back to the payer wallet.
+ */
+import type { ToolDef } from '../../types.js';
+export declare const tool: ToolDef;
+//# sourceMappingURL=refund.d.ts.map

package/dist/tools/chain/refund.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../../../src/tools/chain/refund.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAG9C,eAAO,MAAM,IAAI,EAAE,OAuBlB,CAAC"}

package/dist/tools/chain/refund.js

@@ -0,0 +1,23 @@
+import { getPaymentModeInfo, refundBatchChannel } from '../../x402.js';
+export const tool = {
+    name: '1s_refund',
+    description: 'Refund unused balance from your x402 batch payment channel back to your wallet on Base. ' +
+        'Batch mode deposits enough USDC up front to cover many calls (price × deposit multiplier); ' +
+        'whatever you do not spend stays locked in the channel. ' +
+        'Call this when you are done making batch calls to get the leftover escrow back right away, ' +
+        'instead of waiting for the gateway\'s automatic idle refund. Refunds the full remaining balance. ' +
+        'Only relevant when paying via x402 in batch mode (X402_PRIVATE_KEY set); with an API key, calls are covered by your plan and there is nothing to refund.',
+    category: 'chain',
+    schema: {},
+    handler: async () => {
+        const info = getPaymentModeInfo();
+        if (!info.enabled) {
+            return ('x402 payment is not active in this session, so there is no channel balance to refund. ' +
+                'Refunds apply only when paying per-call via x402 (set X402_PRIVATE_KEY to a funded Base wallet). ' +
+                'With an API key (ONESOURCE_API_KEY), calls are covered by your plan and no x402 payment is made.');
+        }
+        const res = await refundBatchChannel();
+        return res.message;
+    },
+};
+//# sourceMappingURL=refund.js.map

package/dist/tools/chain/refund.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refund.js","sourceRoot":"","sources":["../../../src/tools/chain/refund.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEvE,MAAM,CAAC,MAAM,IAAI,GAAY;IAC3B,IAAI,EAAE,WAAW;IACjB,WAAW,EACT,0FAA0F;QAC1F,6FAA6F;QAC7F,yDAAyD;QACzD,6FAA6F;QAC7F,mGAAmG;QACnG,0JAA0J;IAC5J,QAAQ,EAAE,OAAO;IACjB,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,KAAK,IAAI,EAAE;QAClB,MAAM,IAAI,GAAG,kBAAkB,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,CACL,wFAAwF;gBACxF,mGAAmG;gBACnG,kGAAkG,CACnG,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,kBAAkB,EAAE,CAAC;QACvC,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;CACF,CAAC"}

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAgC3C,eAAO,MAAM,QAAQ,EAAE,OAAO,EA8B7B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAiC3C,eAAO,MAAM,QAAQ,EAAE,OAAO,EA+B7B,CAAC"}

package/dist/tools/index.js

@@ -11,7 +11,7 @@ import { tool as nftMetadataLive } from './live/nft-metadata.js';
 import { tool as nftOwnerLive } from './live/nft-owner.js';
 import { tool as totalSupplyLive } from './live/total-supply.js';
 import { tool as txDetailsLive } from './live/tx-details.js';
-// --- Chain utilities (14 tools) ---
+// --- Chain utilities (15 tools) ---
 import { tool as blockByNumber } from './chain/block-by-number.js';
 import { tool as blockNumber } from './chain/block-number.js';
 import { tool as chainId } from './chain/chain-id.js';
@@ -23,6 +23,7 @@ import { tool as nonce } from './chain/nonce.js';
 import { tool as paymentMode } from './chain/payment-mode.js';
 import { tool as pendingBlock } from './chain/pending-block.js';
 import { tool as proxyDetect } from './chain/proxy-detect.js';
+import { tool as refund } from './chain/refund.js';
 import { tool as simulateCall } from './chain/simulate-call.js';
 import { tool as storageRead } from './chain/storage-read.js';
 import { tool as txReceipt } from './chain/tx-receipt.js';
@@ -52,6 +53,7 @@ export const allTools = [
     paymentMode,
     pendingBlock,
     proxyDetect,
+    refund,
     simulateCall,
     storageRead,
     txReceipt,

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAMA,qCAAqC;AACrC,OAAO,EAAE,IAAI,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,IAAI,IAAI,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,IAAI,IAAI,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,IAAI,IAAI,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,IAAI,IAAI,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,IAAI,IAAI,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE7D,qCAAqC;AACrC,OAAO,EAAE,IAAI,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,CAAC,MAAM,QAAQ,GAAc;IACjC,kBAAkB;IAClB,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,UAAU;IACV,gBAAgB;IAChB,eAAe;IACf,YAAY;IACZ,eAAe;IACf,aAAa;IAEb,kBAAkB;IAClB,aAAa;IACb,WAAW;IACX,OAAO;IACP,YAAY;IACZ,UAAU;IACV,WAAW;IACX,WAAW;IACX,KAAK;IACL,WAAW;IACX,YAAY;IACZ,WAAW;IACX,YAAY;IACZ,WAAW;IACX,SAAS;CACV,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAMA,qCAAqC;AACrC,OAAO,EAAE,IAAI,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,IAAI,IAAI,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,IAAI,IAAI,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,IAAI,IAAI,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,IAAI,IAAI,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,IAAI,IAAI,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,IAAI,IAAI,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE7D,qCAAqC;AACrC,OAAO,EAAE,IAAI,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,CAAC,MAAM,QAAQ,GAAc;IACjC,kBAAkB;IAClB,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,UAAU;IACV,gBAAgB;IAChB,eAAe;IACf,YAAY;IACZ,eAAe;IACf,aAAa;IAEb,kBAAkB;IAClB,aAAa;IACb,WAAW;IACX,OAAO;IACP,YAAY;IACZ,UAAU;IACV,WAAW;IACX,WAAW;IACX,KAAK;IACL,WAAW;IACX,YAAY;IACZ,WAAW;IACX,MAAM;IACN,YAAY;IACZ,WAAW;IACX,SAAS;CACV,CAAC"}

package/dist/x402.d.ts

@@ -24,4 +24,23 @@ export declare function getPaymentMode(): PaymentMode;
 export declare function setPaymentMode(mode: PaymentMode): PaymentMode;
 /** Snapshot of payment state for the 1s_payment_mode tool. */
 export declare function getPaymentModeInfo(): PaymentModeInfo;
+export interface RefundResult {
+    ok: boolean;
+    /** Human-readable outcome, safe to surface directly to the user. */
+    message: string;
+    /** Refund transaction hash, when the receiver settled one. */
+    transaction?: string;
+}
+/**
+ * Cooperatively refund the unused balance of the current batch payment channel
+ * back to the payer wallet. Probes {@link REFUND_PROBE_PATH} for the channel
+ * requirements, then asks the receiver (via its receiverAuthorizer) to sign and
+ * submit the on-chain refund. Always a full refund of the remaining escrow.
+ *
+ * Returns a structured result rather than throwing, so the calling tool can
+ * surface a clear message for the common "nothing to refund" / "no channel"
+ * cases. Uses the unwrapped global fetch (the SDK attaches the refund payload
+ * itself; the payment-wrapping fetch would wrongly try to pay the 402 probe).
+ */
+export declare function refundBatchChannel(): Promise<RefundResult>;
 //# sourceMappingURL=x402.d.ts.map

package/dist/x402.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"AA6BA,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,CAAC;AAc5C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,cAAc,EAAE,OAAO,CAAC;CACzB;AAuBD,wBAAgB,SAAS,IAAI,eAAe,CA4D3C;AAED,8BAA8B;AAC9B,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAK7D;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD"}
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"AA6BA,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,CAAC;AAkB5C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,cAAc,EAAE,OAAO,CAAC;CACzB;AAiCD,wBAAgB,SAAS,IAAI,eAAe,CAkF3C;AA4BD,8BAA8B;AAC9B,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAK7D;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AAuBD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CAgDhE"}

package/dist/x402.js

@@ -24,19 +24,22 @@ import { toClientEvmSigner } from '@x402/evm';
 import { BatchSettlementEvmScheme } from '@x402/evm/batch-settlement/client';
 import { FileClientChannelStorage } from '@x402/evm/batch-settlement/client/file-storage';
 import { privateKeyToAccount } from 'viem/accounts';
-import { createPublicClient, http } from 'viem';
+import { createPublicClient, http, numberToHex } from 'viem';
 import { base } from 'viem/chains';
 const ZERO_SALT = `0x${'0'.repeat(64)}`;
 // Each channel's first paid call deposits depositMultiplier × the call price,
-// funding that many calls before a top-up deposit is needed. Top-ups are the
-// fragile path — a top-up deposit that the facilitator fails to land onchain
-// leaves the channel with a voucher that exceeds real escrow (the 2026-06-05
-// incident: multiplier 5 → free 6th call + bricked channel). The gateway now
-// gates on confirmed onchain escrow, but a larger first deposit keeps typical
-// sessions on the single-deposit path entirely. 20 funds 20 calls per deposit
-// (e.g. 0.10 USDC at $0.005/call) and is fully recoverable via cooperative
-// refund. Override with X402_DEPOSIT_MULTIPLIER (SDK minimum is 3).
-const DEFAULT_DEPOSIT_MULTIPLIER = 20;
+// funding that many calls before a top-up is needed. We keep modest headroom
+// (10 calls per deposit; e.g. 0.05 USDC at $0.005/call) rather than a large
+// upfront lockup: top-ups are now safe — the gateway gates on confirmed onchain
+// escrow (after the 2026-06-05 multiplier-5 free-call incident) and the client
+// rotates the channel salt past dead/refunded channels — and any unspent
+// balance is reclaimable via 1s_refund or the gateway's idle auto-refund.
+// Override with X402_DEPOSIT_MULTIPLIER (SDK minimum is 3).
+const DEFAULT_DEPOSIT_MULTIPLIER = 10;
+// How many times one batch request will bump the channel salt to skip a dead
+// channel before giving up (and letting the caller fall back to exact). Each
+// bump is a fresh channelId; the failed verify that triggers it isn't charged.
+const MAX_SALT_BUMPS = 8;
 let _applied = false;
 let _cachedResult;
 // Runtime-mutable mode state. `setupX402` seeds it from X402_PAYMENT_MODE; the
@@ -45,6 +48,16 @@ let _enabled = false;
 let _address;
 let _mode = 'exact';
 let _batchAvailable = false;
+// The batch-settlement client scheme, retained at module scope so the
+// `1s_refund` tool can call its cooperative-refund flow after setup.
+let _batchScheme;
+// Batch fetch + the machinery to rebuild it under a new channel salt. The salt
+// is rotated when the current channel is dead (exhausted/refunded), so a refund
+// doesn't permanently strand the wallet's batch path on one channelId.
+let _batchFetch;
+let _buildBatch;
+let _baseSalt = ZERO_SALT;
+let _saltOffset = 0n;
 function initialMode() {
     return process.env.X402_PAYMENT_MODE?.trim().toLowerCase() === 'batch'
         ? 'batch'
@@ -73,7 +86,9 @@ export function setupX402() {
     // Built eagerly but lazily funded: no on-chain deposit happens until the
     // first paid request is made while in batch mode. If construction fails
     // (e.g. RPC misconfig), fall back to exact-only rather than crashing the MCP.
-    let batchFetch;
+    //
+    // _buildBatch (re)constructs the scheme for a given salt so the dispatcher can
+    // rotate to a fresh channelId when the current channel is dead — see bumpSalt.
     try {
         const publicClient = createPublicClient({
             chain: base,
@@ -81,34 +96,84 @@ export function setupX402() {
         });
         const batchSigner = toClientEvmSigner(account, publicClient);
         const channelDir = process.env.X402_CHANNEL_DIR?.trim() || undefined;
-        const salt = process.env.X402_CHANNEL_SALT?.trim() || ZERO_SALT;
-        const batchScheme = new BatchSettlementEvmScheme(batchSigner, {
-            depositPolicy: { depositMultiplier: depositMultiplier() },
-            salt,
-            ...(channelDir ? { storage: new FileClientChannelStorage({ directory: channelDir }) } : {}),
-        });
-        const batchClient = new x402Client();
-        batchClient.register('eip155:*', batchScheme);
-        batchFetch = wrapFetchWithPayment(fetch, batchClient);
+        _baseSalt = process.env.X402_CHANNEL_SALT?.trim() || ZERO_SALT;
+        _saltOffset = 0n;
+        _buildBatch = (salt) => {
+            const batchScheme = new BatchSettlementEvmScheme(batchSigner, {
+                depositPolicy: { depositMultiplier: depositMultiplier() },
+                salt,
+                ...(channelDir ? { storage: new FileClientChannelStorage({ directory: channelDir }) } : {}),
+            });
+            const batchClient = new x402Client();
+            batchClient.register('eip155:*', batchScheme);
+            _batchScheme = batchScheme;
+            _batchFetch = wrapFetchWithPayment(fetch, batchClient);
+        };
+        // Initial build uses the base salt verbatim (no numberToHex) — offset 0.
+        _buildBatch(_baseSalt);
         _batchAvailable = true;
     }
     catch (err) {
         _batchAvailable = false;
+        _batchFetch = undefined;
+        _buildBatch = undefined;
         console.error(`[onesource-api] warning: batch payment scheme unavailable (${err instanceof Error ? err.message : String(err)}); falling back to exact-only`);
     }
     _enabled = true;
     _address = account.address;
     _mode = initialMode();
     // If batch was requested but is unavailable, stay on exact.
-    if (_mode === 'batch' && !batchFetch)
+    if (_mode === 'batch' && !_batchFetch)
         _mode = 'exact';
     // Dispatcher: route each request through the active scheme. Reads `_mode`
-    // live so in-session switches via setPaymentMode take effect immediately.
-    const dispatchFetch = (input, init) => (_mode === 'batch' && batchFetch ? batchFetch : exactFetch)(input, init);
+    // and `_batchFetch` live so in-session mode switches and salt rotations take
+    // effect immediately. In batch mode, a "channel exhausted/refunded" 402 means
+    // the deterministic channelId is dead; rotate the salt to a fresh channel and
+    // retry, bounded by MAX_SALT_BUMPS, so a prior refund can't strand batch.
+    const dispatchFetch = async (input, init) => {
+        if (!(_mode === 'batch' && _batchFetch))
+            return exactFetch(input, init);
+        let resp = await _batchFetch(input, init);
+        let bumps = 0;
+        while (_mode === 'batch' && bumps < MAX_SALT_BUMPS && (await isDeadChannel402(resp))) {
+            if (!bumpSalt())
+                break;
+            bumps += 1;
+            resp = await _batchFetch(input, init);
+        }
+        return resp;
+    };
     _applied = true;
     _cachedResult = { enabled: true, address: account.address, fetch: dispatchFetch };
     return _cachedResult;
 }
+// isDeadChannel402 reports whether a response is a "this channel can't be
+// reused" rejection — the deterministic channelId is exhausted or was refunded,
+// so the voucher's cumulative can't be backed. Detected from the gateway's 402
+// body reason (cumulative_exceeds_balance / cumulative_below_claimed). Cloning
+// leaves the original body readable for the caller when we don't retry.
+async function isDeadChannel402(resp) {
+    if (!resp || resp.status !== 402)
+        return false;
+    try {
+        const text = await resp.clone().text();
+        return /cumulative_exceeds_balance|cumulative_below_claimed/.test(text);
+    }
+    catch {
+        return false;
+    }
+}
+// bumpSalt advances the channel salt by one and rebuilds the batch scheme/fetch,
+// so the next request opens a fresh channelId instead of the dead one. Returns
+// false when batch isn't built (nothing to rebuild).
+function bumpSalt() {
+    if (!_buildBatch)
+        return false;
+    _saltOffset += 1n;
+    const next = numberToHex(BigInt(_baseSalt) + _saltOffset, { size: 32 });
+    _buildBatch(next);
+    return true;
+}
 /** Current payment scheme. */
 export function getPaymentMode() {
     return _mode;
@@ -137,5 +202,79 @@ export function resetX402() {
     _address = undefined;
     _mode = 'exact';
     _batchAvailable = false;
+    _batchScheme = undefined;
+    _batchFetch = undefined;
+    _buildBatch = undefined;
+    _baseSalt = ZERO_SALT;
+    _saltOffset = 0n;
+}
+// A batch-eligible (/api/chain/*) endpoint the refund flow probes for the
+// channel's payment requirements (receiver, asset, receiverAuthorizer) — it's
+// a plain unpaid GET that the gateway answers with a 402 challenge, so any
+// such route works and the specific one is irrelevant to the wallet/channel.
+const REFUND_PROBE_PATH = '/api/chain/block-number';
+function atomicToUsdc(atomic) {
+    try {
+        const n = Number(BigInt(atomic)) / 1e6;
+        return n.toFixed(6).replace(/\.?0+$/, '');
+    }
+    catch {
+        return atomic;
+    }
+}
+/**
+ * Cooperatively refund the unused balance of the current batch payment channel
+ * back to the payer wallet. Probes {@link REFUND_PROBE_PATH} for the channel
+ * requirements, then asks the receiver (via its receiverAuthorizer) to sign and
+ * submit the on-chain refund. Always a full refund of the remaining escrow.
+ *
+ * Returns a structured result rather than throwing, so the calling tool can
+ * surface a clear message for the common "nothing to refund" / "no channel"
+ * cases. Uses the unwrapped global fetch (the SDK attaches the refund payload
+ * itself; the payment-wrapping fetch would wrongly try to pay the 402 probe).
+ */
+export async function refundBatchChannel() {
+    if (!_enabled) {
+        return { ok: false, message: 'x402 payment is not active in this session (set X402_PRIVATE_KEY).' };
+    }
+    if (!_batchScheme) {
+        return { ok: false, message: 'Batch payment channels are unavailable in this session, so there is nothing to refund.' };
+    }
+    const base = (process.env.ONESOURCE_BASE_URL ?? 'https://skills.onesource.io').replace(/\/+$/, '');
+    const probeUrl = base + REFUND_PROBE_PATH;
+    try {
+        const settle = (await _batchScheme.refund(probeUrl));
+        const tx = settle?.transaction;
+        const balance = settle?.extra?.channelState?.balance;
+        const remaining = typeof balance === 'string' ? ` Remaining channel balance: ${atomicToUsdc(balance)} USDC.` : '';
+        // The refunded channel is now closed; advance the salt so the next batch
+        // burst opens a fresh channelId rather than re-deriving the dead one.
+        bumpSalt();
+        return {
+            ok: true,
+            transaction: tx,
+            message: `Refund submitted${tx ? ` (tx ${tx})` : ''}.${remaining} ` +
+                `Unused channel escrow is being returned to ${_address ?? 'your wallet'} on Base.`,
+        };
+    }
+    catch (err) {
+        const raw = err instanceof Error ? err.message : String(err);
+        const lower = raw.toLowerCase();
+        if (lower.includes('no remaining balance') || lower.includes('amount_too_low')) {
+            return {
+                ok: false,
+                message: 'Nothing to refund — the channel has no unused balance (everything deposited has been spent or already refunded).',
+            };
+        }
+        if (lower.includes('existing channel record')) {
+            return {
+                ok: false,
+                message: 'No payment channel found for this wallet. Open one by making a call in batch mode first (1s_payment_mode → batch).',
+            };
+        }
+        // Collapse the SDK's own "Refund failed:" prefix(es) so we don't double it.
+        const clean = raw.replace(/^(refund failed:\s*)+/i, '');
+        return { ok: false, message: `Refund failed: ${clean}` };
+    }
 }
 //# sourceMappingURL=x402.js.map

package/dist/x402.js.map

@@ -1 +1 @@
-{"version":3,"file":"x402.js","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"x402.js","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@one-source/api-mcp",
-  "version": "5.2.1",
+  "version": "5.3.1",
   "type": "module",
-  "description": "MCP server for OneSource blockchain data — 26 named tools for balances, NFTs, transactions, events, live chain queries, and x402 payment-mode control via x402",
+  "description": "MCP server for OneSource blockchain data — 27 named tools for balances, NFTs, transactions, events, live chain queries, and x402 payment-mode + refund control via x402",
   "bin": {
     "onesource-api-mcp": "./dist/cli.js"
   },