@aibtc/mcp-server 1.74.0 → 1.76.0

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

@@ -45,6 +45,8 @@ export interface PaymentRequirements {
     recipient: string;
     network: string;
     account: Account;
+    /** True when the endpoint advertised `extra.sponsored` — the relay pays the STX fee. */
+    sponsored: boolean;
 }
 /**
  * Options for createApiClient
@@ -126,6 +128,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";
@@ -525,11 +525,11 @@ export async function createApiClient(baseUrl, options) {
         }
         // Cumulative spending limit (sats ledger) — bounds a drain-by-loop of
         // sub-cap L402 invoices. Keyed by the wallet's Stacks address so all sats
-        // spends (BTC L1, sBTC, L402) share one ledger.
-        const l402Addr = getWalletManager().getActiveAccount()?.address;
-        if (l402Addr) {
-            await getSpendLimiter().check("sats", BigInt(amountSats), l402Addr);
-        }
+        // spends (BTC L1, sBTC, L402) share one ledger, or the __lightning__
+        // bucket when the STX wallet is locked (as lightning_pay_invoice does).
+        // Kept even if the payment throws: that does not prove it did not route.
+        const l402Addr = getWalletManager().getActiveAccount()?.address ?? "__lightning__";
+        await getSpendLimiter().reserve([{ unit: "sats", amount: BigInt(amountSats) }], l402Addr);
         // Pay the Lightning invoice.
         let payment;
         try {
@@ -538,9 +538,6 @@ export async function createApiClient(baseUrl, options) {
         catch (payErr) {
             return Promise.reject(new Error(`L402 payment failed: ${payErr instanceof Error ? payErr.message : String(payErr)}`));
         }
-        if (l402Addr) {
-            await getSpendLimiter().record("sats", BigInt(amountSats), l402Addr);
-        }
         cacheL402Auth(method, canonicalUrlKey, challenge.macaroon, payment.preimage);
         const originalRequest = error.config;
         originalRequest.headers = originalRequest.headers || {};
@@ -623,6 +620,9 @@ export async function createApiClient(baseUrl, options) {
         if (error.response?.status !== 402) {
             return Promise.reject(error);
         }
+        // Booked before signing; given back if the payment fails before the
+        // signed transaction is handed to the endpoint.
+        let reservation;
         try {
             // Decode payment requirements from header
             const headerValue = error.response?.headers?.[X402_HEADERS.PAYMENT_REQUIRED];
@@ -660,10 +660,9 @@ export async function createApiClient(baseUrl, options) {
                 return Promise.reject(new Error(`Network mismatch: endpoint requires ${paymentNetwork} but wallet is configured for ${acct.network}. ` +
                     `Switch to a ${paymentNetwork} wallet or use a ${acct.network} endpoint.`));
             }
-            // Cumulative spending limit: the per-payment cap above bounds a single
-            // 402, but a malicious endpoint can loop sub-cap payments. This blocks
-            // once the session/day total would be exceeded.
-            await getSpendLimiter().check(isSbtc ? "sats" : "ustx", amount, acct.address);
+            // The endpoint offers gas sponsorship: sign with `sponsored: true, fee: 0`
+            // and its relay co-signs and pays the STX fee at settlement.
+            const sponsored = selectedOption.extra?.sponsored === true;
             // Invoke pre-payment callback (e.g. balance check) before signing/broadcasting.
             // If the callback throws, the payment is aborted and the error propagates to the caller.
             if (options?.onBeforePayment) {
@@ -673,14 +672,28 @@ export async function createApiClient(baseUrl, options) {
                     recipient: selectedOption.payTo,
                     network: paymentNetwork ?? acct.network,
                     account: acct,
+                    sponsored,
                 });
             }
-            // Build a non-sponsored signed transaction: the sender pays its own
-            // STX gas (fee + nonce auto-estimated by @stacks), and the x402
-            // facilitator simply verifies and broadcasts it. No relay sponsorship
-            // — this is the same tx shape the x402-stacks lib produces, and the
-            // balance check in onBeforePayment already accounts for the gas.
+            // Clamped fee — do NOT let @stacks auto-estimate, since Hiro's
+            // contract_call tiers are polluted by outliers (observed >2000 STX).
+            // The sbtc_transfer clamp caps it at 0.003 STX.
+            const fee = sponsored
+                ? 0n
+                : await resolveDefaultFee(acct.network, isSbtc ? "sbtc_transfer" : "token_transfer");
+            // Cumulative spending limit: the per-payment cap above bounds a single
+            // 402, but a malicious endpoint can loop sub-cap payments. This blocks
+            // once the session/day total would be exceeded. A self-paying sender
+            // pays the fee, so it is booked in ustx alongside the amount.
+            reservation = await getSpendLimiter().reserve([
+                { unit: isSbtc ? "sats" : "ustx", amount },
+                ...(sponsored ? [] : [{ unit: "ustx", amount: fee }]),
+            ], acct.address);
+            // Build the signed transaction. Self-paid: the sender pays its own STX
+            // gas and the facilitator verifies and broadcasts it. Sponsored: the
+            // sponsor slot is left empty for the endpoint's relay to fill.
             const networkName = getStacksNetwork(acct.network);
+            const memo = paymentIdMemo(selectedOption.extra);
             let transaction;
             if (tokenType === "sBTC") {
                 const contracts = getContracts(acct.network);
@@ -693,7 +706,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,
@@ -705,10 +718,8 @@ export async function createApiClient(baseUrl, options) {
                             .willSendEq(amount)
                             .ft(contracts.SBTC_TOKEN, "sbtc-token"),
                     ],
-                    // Clamped fee — do NOT let @stacks auto-estimate, since Hiro's
-                    // contract_call tiers are polluted by outliers (observed >2000
-                    // STX). The sbtc_transfer clamp caps it at 0.003 STX.
-                    fee: await resolveDefaultFee(acct.network, "sbtc_transfer"),
+                    fee,
+                    sponsored,
                 });
             }
             else {
@@ -717,8 +728,9 @@ export async function createApiClient(baseUrl, options) {
                     amount,
                     senderKey: acct.privateKey,
                     network: networkName,
-                    memo: "",
-                    fee: await resolveDefaultFee(acct.network, "token_transfer"),
+                    memo: memo ?? "",
+                    fee,
+                    sponsored,
                 });
             }
             const txHex = "0x" + transaction.serialize();
@@ -739,9 +751,9 @@ export async function createApiClient(baseUrl, options) {
                 action: "payment_submitted",
                 compatShimUsed: false,
             });
-            // Record the spend against the cumulative ledger now that the signed
-            // payment tx is submitted to the facilitator.
-            await getSpendLimiter().record(isSbtc ? "sats" : "ustx", amount, acct.address);
+            // The signed payment tx is handed to the facilitator from here on, so
+            // the booked spend stands.
+            reservation = undefined;
             // Retry the original request with the payment header
             const originalRequest = error.config;
             originalRequest.headers = originalRequest.headers || {};
@@ -749,6 +761,8 @@ export async function createApiClient(baseUrl, options) {
             return axiosInstance.request(originalRequest);
         }
         catch (paymentError) {
+            if (reservation)
+                await getSpendLimiter().release(reservation);
             return Promise.reject(new Error(`x402 payment failed: ${paymentError instanceof Error ? paymentError.message : String(paymentError)}`));
         }
     });
@@ -813,6 +827,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/endpoint.tools.js

@@ -354,9 +354,8 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
                 toolName: "execute_x402_endpoint",
                 asset,
                 onBeforePayment: async (requirements) => {
-                    // Non-sponsored: sender pays its own gas, so validate STX for the
-                    // fee too (sponsored=false is the default, passed explicitly here).
-                    await checkSufficientBalance(requirements.account, requirements.amount, requirements.asset, false);
+                    // Self-paid payments also need STX for the fee; sponsored ones don't.
+                    await checkSufficientBalance(requirements.account, requirements.amount, requirements.asset, requirements.sponsored);
                 },
             });
             const response = await api.request({ method, url: parsed.requestPath, params, data });

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

@@ -6,14 +6,16 @@ import { McpServer } from "@modelcontextprotocol/server";
  */
 export declare function checkDirectInboxBalance(address: string, amount: string, sponsored?: boolean): Promise<void>;
 /**
- * x402 inbox messaging via the `x402-stacks` client interceptor
- * (`wrapAxiosWithPayment`). The transaction is signed but not broadcast; the
+ * x402 inbox messaging. The transaction is signed but not broadcast; the
  * inbox endpoint settles it through its x402 facilitator.
  *
  * 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.
+ * the `x402-stacks` interceptor (`wrapAxiosWithPayment`, >=2.1.0) signs a
+ * sponsored sBTC transfer with fee 0 and the facilitator co-signs and pays the
+ * STX gas. Without it, the payment goes through `createApiClient`, which signs
+ * a standard transfer at the `sbtc_transfer` fee clamp (max 0.003 STX) with an
+ * exact-amount post-condition. The SDK's standard path leaves the fee to
+ * stacks.js auto-estimation, which has no ceiling (#700).
  *
  * Server side: `lib/inbox/x402-verify.ts` deserializes the payment tx and
  * branches on `tx.auth.authType` (sponsored → relay sponsors; standard →

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

@@ -1,7 +1,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 { createApiClient, 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";
@@ -57,14 +57,32 @@ export async function checkDirectInboxBalance(address, amount, sponsored = false
     }
 }
 /**
- * x402 inbox messaging via the `x402-stacks` client interceptor
- * (`wrapAxiosWithPayment`). The transaction is signed but not broadcast; the
+ * True when a failed x402-stacks request had already carried the signed
+ * payment: the retried request's config holds the payment-signature header,
+ * either on the error itself (the retry failed outright) or on its `cause`
+ * (the interceptor's "402 after payment was sent").
+ */
+function paymentWasSent(error) {
+    const carried = (e) => {
+        const headers = e?.config?.headers;
+        if (!headers || typeof headers !== "object")
+            return false;
+        const wanted = X402_HEADERS.PAYMENT_SIGNATURE.toLowerCase();
+        return Object.entries(headers).some(([name, value]) => name.toLowerCase() === wanted && value != null);
+    };
+    return carried(error) || carried(error?.cause);
+}
+/**
+ * x402 inbox messaging. The transaction is signed but not broadcast; the
  * inbox endpoint settles it through its x402 facilitator.
  *
  * 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.
+ * the `x402-stacks` interceptor (`wrapAxiosWithPayment`, >=2.1.0) signs a
+ * sponsored sBTC transfer with fee 0 and the facilitator co-signs and pays the
+ * STX gas. Without it, the payment goes through `createApiClient`, which signs
+ * a standard transfer at the `sbtc_transfer` fee clamp (max 0.003 STX) with an
+ * exact-amount post-condition. The SDK's standard path leaves the fee to
+ * stacks.js auto-estimation, which has no ceiling (#700).
  *
  * Server side: `lib/inbox/x402-verify.ts` deserializes the payment tx and
  * branches on `tx.auth.authType` (sponsored → relay sponsors; standard →
@@ -140,25 +158,42 @@ export function registerInboxX402Tools(server) {
             // 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 the sBTC
-            // transfer (sponsored or standard, per `extra.feePayer`) and retries
-            // with the payment-signature header.
-            const stacksAccount = {
-                address: account.address,
-                privateKey: account.privateKey,
-                network: NETWORK,
-            };
-            const api = wrapAxiosWithPayment(axios.create({ timeout: 120_000 }), stacksAccount);
-            // Step 4: Send. The interceptor handles 402 -> sign -> retry.
-            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.
+            // Step 3: Send. Either interceptor handles 402 -> sign -> retry.
+            let response;
+            if (sponsored) {
+                // The message cost is a signed sBTC spend: book it before signing.
+                const spendLimiter = getSpendLimiter();
+                const reservation = await spendLimiter.reserve([{ unit: "sats", amount: BigInt(accept.amount) }], account.address);
+                const stacksAccount = {
+                    address: account.address,
+                    privateKey: account.privateKey,
+                    network: NETWORK,
+                };
+                const api = wrapAxiosWithPayment(axios.create({ timeout: 120_000 }), stacksAccount);
+                try {
+                    response = await api.post(inboxUrl, body, {
+                        headers: { "Content-Type": "application/json" },
+                    });
+                }
+                catch (error) {
+                    // Once the signed payment rode the retried request, the inbox may
+                    // have settled it, so the booking stands.
+                    if (!paymentWasSent(error))
+                        await spendLimiter.release(reservation);
+                    throw error;
+                }
+            }
+            else {
+                // Self-paid: createApiClient clamps the fee and meters the spend.
+                const api = await createApiClient(INBOX_BASE, {
+                    toolName: "send_inbox_message_direct",
+                    asset: accept.asset,
+                });
+                response = await api.post(inboxUrl, body, {
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+            // Step 4: 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;

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/dist/tools/index.js

@@ -191,7 +191,7 @@ export function registerAllTools(server, selection) {
     // At Stake (elsalvadorstakesbtc.com — complete-set prediction market)
     inGroup("markets", registerAtStakeTools);
     // At Stake side legions (aibtc.com/legions — weight is the share balance)
-    inGroup("markets", registerAtStakeLegionTools);
+    inGroup("legion", registerAtStakeLegionTools);
     // Identity (ERC-8004 on-chain agent identity management)
     inGroup("identity", registerIdentityTools);
     // Credentials (encrypted credential store — list, get, set, delete, unlock)

package/dist/tools/lightning.tools.js

@@ -312,9 +312,11 @@ export function registerLightningTools(server) {
             // user therefore gets a separate Lightning ledger from their STX-address
             // ledger — see SECURITY.md.
             const ledgerKey = getWalletManager().getActiveAccount()?.address ?? "__lightning__";
-            await getSpendLimiter().check("sats", BigInt(amountSats), ledgerKey);
+            // Booked before paying, and kept even if payInvoice throws: a failed
+            // call does not prove the payment did not route (Spark can settle a
+            // payment and still report no preimage).
+            await getSpendLimiter().reserve([{ unit: "sats", amount: BigInt(amountSats) }], ledgerKey);
             const result = await provider.payInvoice(bolt11, maxFeeSats);
-            await getSpendLimiter().record("sats", BigInt(amountSats), ledgerKey);
             return createJsonResponse({
                 success: true,
                 preimage: result.preimage,

package/dist/tools/profiles.d.ts

@@ -29,8 +29,8 @@ export declare const TOOL_GROUPS: {
     readonly identity: "ERC-8004 identity and reputation, message signing";
     readonly social: "Nostr, AIBTC inbox";
     readonly earn: "Bounty board (create, accept, pay, my views)";
-    readonly legion: "AIBTC News Legion";
-    readonly markets: "Stacks prediction market, At Stake";
+    readonly legion: "AIBTC News Legion, At Stake side legions (El Salvador)";
+    readonly markets: "Stacks prediction market, At Stake market";
     readonly dev: "Scaffolding, OpenRouter, settings, inference marketplace, arXiv";
 };
 export type ToolGroup = keyof typeof TOOL_GROUPS;

package/dist/tools/profiles.js

@@ -59,8 +59,8 @@ export const TOOL_GROUPS = {
     identity: "ERC-8004 identity and reputation, message signing",
     social: "Nostr, AIBTC inbox",
     earn: "Bounty board (create, accept, pay, my views)",
-    legion: "AIBTC News Legion",
-    markets: "Stacks prediction market, At Stake",
+    legion: "AIBTC News Legion, At Stake side legions (El Salvador)",
+    markets: "Stacks prediction market, At Stake market",
     dev: "Scaffolding, OpenRouter, settings, inference marketplace, arXiv",
 };
 export const ALL_TOOLS = { all: true };

package/dist/tools/psbt.tools.js

@@ -289,8 +289,7 @@ export function registerPsbtTools(server) {
             // A signed PSBT can be broadcast by anyone (a marketplace, the
             // counterparty), so the spend is metered here, before it is handed back.
             const outflowSats = psbtOutflowSats(tx, signedInputs, account, NETWORK);
-            await getSpendLimiter().check("sats", outflowSats, account.address);
-            await getSpendLimiter().record("sats", outflowSats, account.address);
+            await getSpendLimiter().reserve([{ unit: "sats", amount: outflowSats }], account.address);
             return createJsonResponse({
                 success: signedInputs.length > 0,
                 network: NETWORK,

package/dist/tools/sbtc.tools.js

@@ -61,7 +61,7 @@ Example: To send 0.001 sBTC, use amount "100000" (satoshis).`,
         try {
             const sbtcService = getSbtcService(NETWORK);
             const account = await getAccount();
-            const resolvedFee = await resolveFee(fee, NETWORK, "contract_call");
+            const resolvedFee = await resolveFee(fee, NETWORK, "sbtc_transfer");
             const result = await sbtcService.transfer(account, recipient, BigInt(amount), memo, resolvedFee, sponsored);
             const btcAmount = (BigInt(amount) / BigInt(100_000_000)).toString();
             return createJsonResponse({