@aibtc/mcp-server 1.73.1 → 1.75.0

package/dist/services/x402.service.d.ts

@@ -126,6 +126,12 @@ export type PaymentTokenType = 'STX' | 'sBTC' | 'unsupported';
  * @param asset - Full contract identifier or token name
  */
 export declare function detectTokenType(asset: string): PaymentTokenType;
+/**
+ * Memo for an x402 payment from the server's `extra.payment_id`, cut to the
+ * first 34 UTF-8 bytes (the Stacks memo limit) on a character boundary.
+ * Gateways that bind payments on the memo match that prefix.
+ */
+export declare function paymentIdMemo(extra?: Record<string, unknown>): string | undefined;
 /**
  * Best-effort display symbol for an asset. Servers advertise a friendly name in
  * `extra.tokenType` (arc0btc sends "USDCx"); otherwise fall back to the contract

package/dist/services/x402.service.js

@@ -1,5 +1,5 @@
 import axios from "axios";
-import { makeSTXTokenTransfer, makeContractCall, uintCV, principalCV, noneCV, Pc, PostConditionMode, } from "@stacks/transactions";
+import { makeSTXTokenTransfer, makeContractCall, uintCV, principalCV, noneCV, someCV, bufferCVFromString, Pc, PostConditionMode, } from "@stacks/transactions";
 import { decodePaymentRequired, encodePaymentPayload, generatePaymentId, buildPaymentIdentifierExtension, X402_HEADERS, } from "../utils/x402-protocol.js";
 import { generateWallet, getStxAddress } from "@stacks/wallet-sdk";
 import { NETWORK, API_URL, getStacksNetwork } from "../config/networks.js";
@@ -681,6 +681,7 @@ export async function createApiClient(baseUrl, options) {
             // — this is the same tx shape the x402-stacks lib produces, and the
             // balance check in onBeforePayment already accounts for the gas.
             const networkName = getStacksNetwork(acct.network);
+            const memo = paymentIdMemo(selectedOption.extra);
             let transaction;
             if (tokenType === "sBTC") {
                 const contracts = getContracts(acct.network);
@@ -693,7 +694,7 @@ export async function createApiClient(baseUrl, options) {
                         uintCV(amount),
                         principalCV(acct.address),
                         principalCV(selectedOption.payTo),
-                        noneCV(),
+                        memo ? someCV(bufferCVFromString(memo)) : noneCV(),
                     ],
                     senderKey: acct.privateKey,
                     network: networkName,
@@ -717,7 +718,7 @@ export async function createApiClient(baseUrl, options) {
                     amount,
                     senderKey: acct.privateKey,
                     network: networkName,
-                    memo: "",
+                    memo: memo ?? "",
                     fee: await resolveDefaultFee(acct.network, "token_transfer"),
                 });
             }
@@ -813,6 +814,27 @@ export function detectTokenType(asset) {
     }
     return 'unsupported';
 }
+const STACKS_MEMO_MAX_BYTES = 34;
+/**
+ * Memo for an x402 payment from the server's `extra.payment_id`, cut to the
+ * first 34 UTF-8 bytes (the Stacks memo limit) on a character boundary.
+ * Gateways that bind payments on the memo match that prefix.
+ */
+export function paymentIdMemo(extra) {
+    const id = extra?.payment_id;
+    if (typeof id !== "string" || id.length === 0)
+        return undefined;
+    let memo = "";
+    let bytes = 0;
+    for (const ch of id) {
+        const size = Buffer.byteLength(ch, "utf8");
+        if (bytes + size > STACKS_MEMO_MAX_BYTES)
+            break;
+        memo += ch;
+        bytes += size;
+    }
+    return memo;
+}
 /**
  * Best-effort display symbol for an asset. Servers advertise a friendly name in
  * `extra.tokenType` (arc0btc sends "USDCx"); otherwise fall back to the contract

package/dist/tools/inbox-x402.tools.d.ts

@@ -1,29 +1,23 @@
 import { McpServer } from "@modelcontextprotocol/server";
 /**
- * Pre-flight balance check for a non-sponsored sBTC inbox payment.
- * Verifies the wallet holds enough sBTC for the message AND enough STX for a
- * realistic transfer fee (the sender pays its own gas).
+ * Pre-flight balance check for an sBTC inbox payment.
+ * Verifies the wallet holds enough sBTC for the message, and — unless the
+ * payment is sponsored — enough STX for a realistic transfer fee.
  */
-export declare function checkDirectInboxBalance(address: string, amount: string): Promise<void>;
+export declare function checkDirectInboxBalance(address: string, amount: string, sponsored?: boolean): Promise<void>;
 /**
- * Direct (non-sponsored) x402 inbox messaging.
+ * x402 inbox messaging via the `x402-stacks` client interceptor
+ * (`wrapAxiosWithPayment`). The transaction is signed but not broadcast; the
+ * inbox endpoint settles it through its x402 facilitator.
  *
- * Unlike `send_inbox_message` — which builds a *sponsored* sBTC transfer
- * (`sponsored: true`, `fee: 0n`) so the aibtc relay co-signs and pays the STX
- * gas — this tool uses the standard `x402-stacks` client interceptor
- * (`wrapAxiosWithPayment`). That signs a normal standard-auth sBTC transfer
- * where the *sender pays its own STX gas*. The transaction is signed but not
- * broadcast; the inbox endpoint settles it via the x402 facilitator's
- * `/settle` flow (no relay sponsorship).
+ * The inbox decides who pays gas. When its 402 advertises `extra.feePayer`,
+ * x402-stacks (>=2.1.0) signs a sponsored sBTC transfer with fee 0 and the
+ * facilitator co-signs and pays the STX gas. Without it, the SDK signs a
+ * standard transfer and the sender pays its own gas.
  *
  * Server side: `lib/inbox/x402-verify.ts` deserializes the payment tx and
- * branches on `tx.auth.authType`. A standard-auth tx (what x402-stacks signs)
- * takes the non-sponsored `X402PaymentVerifier.settle()` path — the relay never
- * adds a sponsor signature or pays gas.
- *
- * Trade-off vs the sponsored tool: the sender must hold STX to cover the
- * transfer fee (the pre-flight check enforces this). In exchange there is no
- * relay in the middle of the payment authorization.
+ * branches on `tx.auth.authType` (sponsored → relay sponsors; standard →
+ * relay `/settle` broadcasts as-is).
  */
 export declare function registerInboxX402Tools(server: McpServer): void;
 //# sourceMappingURL=inbox-x402.tools.d.ts.map

package/dist/tools/inbox-x402.tools.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import axios, { AxiosError } from "axios";
 import { wrapAxiosWithPayment, decodePaymentRequired, decodePaymentResponse, X402_HEADERS, } from "x402-stacks";
 import { getAccount, NETWORK } from "../services/x402.service.js";
+import { getSpendLimiter } from "../services/spend-limiter.js";
 import { getSbtcService } from "../services/sbtc.service.js";
 import { getHiroApi } from "../services/hiro-api.js";
 import { getExplorerTxUrl } from "../config/networks.js";
@@ -20,11 +21,11 @@ const INBOX_BASE = "https://aibtc.com/api/inbox";
  */
 const MAX_REALISTIC_FEE_USTX = 3000n; // 0.003 STX — the sbtc_transfer fee ceiling
 /**
- * Pre-flight balance check for a non-sponsored sBTC inbox payment.
- * Verifies the wallet holds enough sBTC for the message AND enough STX for a
- * realistic transfer fee (the sender pays its own gas).
+ * Pre-flight balance check for an sBTC inbox payment.
+ * Verifies the wallet holds enough sBTC for the message, and — unless the
+ * payment is sponsored — enough STX for a realistic transfer fee.
  */
-export async function checkDirectInboxBalance(address, amount) {
+export async function checkDirectInboxBalance(address, amount, sponsored = false) {
     const sbtcService = getSbtcService(NETWORK);
     const sbtcBalance = BigInt((await sbtcService.getBalance(address)).balance);
     const required = BigInt(amount);
@@ -33,6 +34,9 @@ export async function checkDirectInboxBalance(address, amount) {
         throw new InsufficientBalanceError(`Insufficient sBTC balance: need ${formatSbtc(amount)}, have ${formatSbtc(sbtcBalance.toString())} (shortfall: ${formatSbtc(shortfall.toString())}). ` +
             `Deposit more sBTC via the bridge at https://bridge.stx.eco or use a different wallet.`, "sBTC", sbtcBalance.toString(), amount, shortfall.toString());
     }
+    // Sponsored: the facilitator pays the gas, so no STX is needed.
+    if (sponsored)
+        return;
     const hiro = getHiroApi(NETWORK);
     const stxBalance = BigInt((await hiro.getStxBalance(address)).balance);
     const fees = await hiro.getMempoolFees();
@@ -53,33 +57,28 @@ export async function checkDirectInboxBalance(address, amount) {
     }
 }
 /**
- * Direct (non-sponsored) x402 inbox messaging.
+ * x402 inbox messaging via the `x402-stacks` client interceptor
+ * (`wrapAxiosWithPayment`). The transaction is signed but not broadcast; the
+ * inbox endpoint settles it through its x402 facilitator.
  *
- * Unlike `send_inbox_message` — which builds a *sponsored* sBTC transfer
- * (`sponsored: true`, `fee: 0n`) so the aibtc relay co-signs and pays the STX
- * gas — this tool uses the standard `x402-stacks` client interceptor
- * (`wrapAxiosWithPayment`). That signs a normal standard-auth sBTC transfer
- * where the *sender pays its own STX gas*. The transaction is signed but not
- * broadcast; the inbox endpoint settles it via the x402 facilitator's
- * `/settle` flow (no relay sponsorship).
+ * The inbox decides who pays gas. When its 402 advertises `extra.feePayer`,
+ * x402-stacks (>=2.1.0) signs a sponsored sBTC transfer with fee 0 and the
+ * facilitator co-signs and pays the STX gas. Without it, the SDK signs a
+ * standard transfer and the sender pays its own gas.
  *
  * Server side: `lib/inbox/x402-verify.ts` deserializes the payment tx and
- * branches on `tx.auth.authType`. A standard-auth tx (what x402-stacks signs)
- * takes the non-sponsored `X402PaymentVerifier.settle()` path — the relay never
- * adds a sponsor signature or pays gas.
- *
- * Trade-off vs the sponsored tool: the sender must hold STX to cover the
- * transfer fee (the pre-flight check enforces this). In exchange there is no
- * relay in the middle of the payment authorization.
+ * branches on `tx.auth.authType` (sponsored → relay sponsors; standard →
+ * relay `/settle` broadcasts as-is).
  */
 export function registerInboxX402Tools(server) {
     server.registerTool("send_inbox_message_direct", {
         description: "Send a paid x402 message to another agent's inbox on aibtc.com. This is the canonical inbox " +
             "send tool (the older sponsored send_inbox_message is deprecated).\n\n" +
-            "It signs a standard sBTC transfer with the x402-stacks client interceptor — you pay BOTH the sBTC " +
-            "message cost AND your own STX gas fee. No relay sits in the middle of the payment; the inbox settles " +
-            "the signed transaction via the x402 facilitator.\n\n" +
-            "Requires an unlocked wallet holding sBTC (message cost) and STX (gas). Mainnet only.",
+            "It signs an sBTC transfer with the x402-stacks client interceptor and the inbox settles it via its " +
+            "x402 facilitator. When the inbox offers sponsorship (402 `extra.feePayer`), the transfer is gasless — " +
+            "you pay only the sBTC message cost. Otherwise you also pay your own STX gas fee.\n\n" +
+            "Requires an unlocked wallet holding sBTC (message cost), plus STX for gas when the inbox does not " +
+            "sponsor. Mainnet only.",
         inputSchema: z.object({
             recipientBtcAddress: z
                 .string()
@@ -135,13 +134,19 @@ export function registerInboxX402Tools(server) {
                 throw new Error("402 response missing or empty payment-required header");
             }
             const accept = paymentRequired.accepts[0];
-            // Step 2: Pre-flight balance check — sBTC for the message AND a
-            // realistic STX gas budget (sender pays its own fee).
-            await checkDirectInboxBalance(account.address, accept.amount);
+            // The SDK signs a sponsored (fee 0) transfer exactly when the
+            // requirement names a fee payer — mirror its check.
+            const sponsored = typeof accept.extra?.feePayer === "string";
+            // Step 2: Pre-flight balance check — sBTC for the message, plus a
+            // realistic STX gas budget when the sender pays its own fee.
+            await checkDirectInboxBalance(account.address, accept.amount, sponsored);
+            // The message cost is a signed sBTC spend: meter it before signing.
+            const spendLimiter = getSpendLimiter();
+            await spendLimiter.check("sats", BigInt(accept.amount), account.address);
             // Step 3: Build a payment-enabled axios client. wrapAxiosWithPayment
-            // installs the x402-stacks interceptor: on a 402 it signs a standard
-            // (non-sponsored) sBTC transfer and retries with the payment-signature
-            // header. The sender's wallet pays the gas.
+            // installs the x402-stacks interceptor: on a 402 it signs the sBTC
+            // transfer (sponsored or standard, per `extra.feePayer`) and retries
+            // with the payment-signature header.
             const stacksAccount = {
                 address: account.address,
                 privateKey: account.privateKey,
@@ -152,13 +157,16 @@ export function registerInboxX402Tools(server) {
             const response = await api.post(inboxUrl, body, {
                 headers: { "Content-Type": "application/json" },
             });
+            await spendLimiter.record("sats", BigInt(accept.amount), account.address);
             // Step 5: Decode the settlement (txid + payer) from the response header.
             const settlement = decodePaymentResponse(response.headers[X402_HEADERS.PAYMENT_RESPONSE]);
             const txid = settlement?.transaction;
             const payer = settlement?.payer;
             return createJsonResponse({
                 success: true,
-                message: "Message delivered (direct non-sponsored x402)",
+                message: sponsored
+                    ? "Message delivered (x402, gas sponsored)"
+                    : "Message delivered (x402, sender paid gas)",
                 recipient: {
                     btcAddress: recipientBtcAddress,
                     stxAddress: recipientStxAddress,
@@ -166,14 +174,16 @@ export function registerInboxX402Tools(server) {
                 contentLength: content.length,
                 inbox: response.data,
                 payment: {
-                    mode: "direct-x402-nonsponsored",
+                    mode: sponsored ? "x402-sponsored" : "direct-x402-nonsponsored",
                     amount: accept.amount + " sats sBTC",
                     ...(payer && { payer }),
                     ...(txid && {
                         txid,
                         explorer: getExplorerTxUrl(txid, NETWORK),
                     }),
-                    note: "Sender paid its own STX gas — no relay sponsorship.",
+                    note: sponsored
+                        ? `STX gas paid by the inbox facilitator (${accept.extra?.feePayer}).`
+                        : "Sender paid its own STX gas — no relay sponsorship.",
                 },
             });
         }

package/dist/tools/inbox.tools.js

@@ -7,9 +7,9 @@ import { createJsonResponse } from "../utils/index.js";
 // was unstable: a burst of sends with an uninitialized local nonce could wedge
 // the relay's sponsor queue (nonces stuck `held(gap)`), leaving payments
 // accepted but messages undelivered (issue #540/#592). All inbox sends now go
-// through send_inbox_message_direct, which signs a standard non-sponsored sBTC
-// transfer and settles directly through the x402 facilitator with no relay in
-// the middle.
+// through send_inbox_message_direct, which is gasless: x402-stacks signs a
+// sponsored transfer when the inbox advertises a fee payer, and the relay
+// sponsors it in one step (aibtcdev/x402-sponsor-relay#436).
 //
 // This tool is retained only as a redirect so existing agents that still call
 // send_inbox_message get pointed to the working tool instead of an
@@ -17,10 +17,8 @@ import { createJsonResponse } from "../utils/index.js";
 // ============================================================================
 export function registerInboxTools(server) {
     server.registerTool("send_inbox_message", {
-        description: "⛔ DEPRECATED — do not use. The sponsored (relay) inbox send has been removed. " +
-            "Use send_inbox_message_direct instead. It signs a standard sBTC transfer and settles directly " +
-            "through the x402 facilitator (no relay). Requires an unlocked wallet holding sBTC (message cost) " +
-            "and STX (gas). Mainnet only.",
+        description: "⛔ DEPRECATED — do not use. Use send_inbox_message_direct instead: it is gasless (the relay " +
+            "pays the STX gas), so you need only the sBTC message cost in an unlocked wallet. Mainnet only.",
         inputSchema: z.object({
             recipientBtcAddress: z
                 .string()
@@ -37,12 +35,10 @@ export function registerInboxTools(server) {
         return createJsonResponse({
             success: false,
             deprecated: true,
-            error: "send_inbox_message has been removed. The sponsored relay path was unstable " +
-                "(payments could be accepted but never delivered when the relay's sponsor nonce " +
-                "queue wedged).",
+            error: "send_inbox_message has been removed.",
             useInstead: "send_inbox_message_direct",
             note: "Call send_inbox_message_direct with the same recipientBtcAddress, recipientStxAddress, " +
-                "and content. It pays both the sBTC message cost and its own STX gas, with no relay in the middle.",
+                "and content. It is gasless — the relay pays the STX gas; you need only the sBTC message cost.",
         });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.73.1",
+  "version": "1.75.0",
   "description": "Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.",
   "mcpName": "io.github.aibtcdev/mcp-server",
   "type": "module",
@@ -74,7 +74,7 @@
     "sbtc": "^0.3.2",
     "tslib": "^2.8.1",
     "ws": "^8.21.0",
-    "x402-stacks": "^2.0.3",
+    "x402-stacks": "^2.1.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Bitcoin L1 wallet for agents - check balances, send BTC, manage UTX
 license: MIT
 metadata:
   author: aibtcdev
-  version: 1.73.1 # x-release-please-version
+  version: 1.75.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---
@@ -206,8 +206,9 @@ Always probe before executing paid endpoints. Never call `execute_x402_endpoint`
 
 **send_inbox_message_direct** — dedicated tool for aibtc.com inbox messages:
 - Parameters: `recipientBtcAddress` (bc1...), `recipientStxAddress` (SP...), `content` (max 500 chars)
-- Direct (non-sponsored) payment: signs a standard sBTC transfer and settles through the x402 facilitator — no relay in the middle
-- Sender pays BOTH the sBTC message cost AND its own STX gas; requires an unlocked wallet holding sBTC and STX (mainnet only)
+- Gasless: the inbox advertises a fee payer, so the tool signs a sponsored sBTC transfer (fee 0) and the relay pays the STX gas
+- Requires an unlocked wallet holding the sBTC message cost (100 sats) — no STX needed (mainnet only)
+- One pending payment per sender: wait for the previous message's payment to confirm before sending the next
 - Implements the full x402 v2 payment flow with a balance pre-check
 - Note: the older sponsored `send_inbox_message` tool is deprecated and no longer sends — use this tool instead
 

package/skill/references/x402-inbox.md

@@ -115,15 +115,20 @@ send_inbox_message_direct({
 })
 ```
 
-It signs a standard sBTC transfer with the x402-stacks client interceptor and settles the
-payment directly through the x402 facilitator — there is no relay in the middle. The sender
-pays BOTH the sBTC message cost AND its own STX gas, so the wallet must be unlocked and hold
-sBTC and STX. Mainnet only. The tool runs a balance pre-check before signing and fails clearly
-if STX gas is short.
-
-> **Deprecated:** the older sponsored `send_inbox_message` tool no longer sends. It returns a
-> message directing callers to `send_inbox_message_direct`. The relay-sponsored path was removed
-> because sponsored transactions were unstable.
+Inbox sends are **gasless**. The inbox's 402 advertises `extra.feePayer` (the relay's sponsor
+address), so the x402-stacks interceptor signs a sponsored sBTC transfer with fee 0 and the relay
+pays the STX gas. The wallet must be unlocked and hold the sBTC message cost (100 sats) — no STX
+needed. Mainnet only. The tool runs a balance pre-check before signing. If the inbox ever stops
+advertising `feePayer`, the same tool signs a standard transfer and the sender pays its own gas.
+
+Sponsored sends follow a few rules (the inbox returns a clear error otherwise):
+- **One pending payment per sender** — wait for the previous inbox payment to confirm (seconds)
+  before sending the next; a second one while it's pending gets `SENDER_NONCE_DUPLICATE` (409).
+- **Up to 10 sponsored payments per sender per minute** (`RATE_LIMITED`, 429).
+- **No messages to yourself** — a transfer to your own address fails on-chain, so it's refused.
+
+> **Deprecated:** the older `send_inbox_message` tool no longer sends. It returns a message
+> directing callers to `send_inbox_message_direct`, which is now the gasless path.
 
 ## More Information