@aibtc/mcp-server 1.77.0 → 1.79.0

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

@@ -1,4 +1,4 @@
-import { type AxiosInstance } from "axios";
+import { type AxiosInstance, type AxiosRequestConfig } from "axios";
 import { type PaymentRequirementsV2 } from "../utils/x402-protocol.js";
 import { NETWORK, API_URL, type Network } from "../config/networks.js";
 import type { Account } from "../transactions/builder.js";
@@ -45,9 +45,29 @@ export interface PaymentRequirements {
     recipient: string;
     network: string;
     account: Account;
-    /** True when the endpoint advertised `extra.sponsored` — the relay pays the STX fee. */
+    /** True when the endpoint advertised `extra.feePayer` or `extra.sponsored` — the relay pays the STX fee. */
     sponsored: boolean;
 }
+/**
+ * Who pays STX gas for the payment the interceptor signed. Sponsored: fee 0,
+ * the endpoint's relay pays at settlement. Self-paid: the sender's own fee.
+ */
+export interface X402PaymentGas {
+    sponsored: boolean;
+    feeUstx: string;
+}
+declare module "axios" {
+    interface AxiosRequestConfig {
+        /** Set by the x402 interceptor on the paid retry; read with getPaymentGas. */
+        x402PaymentGas?: X402PaymentGas;
+    }
+}
+/**
+ * Read the gas decision the interceptor attached to a paid request's config
+ * (`response.config` on success, `error.config` on failure). Undefined when
+ * no payment was signed.
+ */
+export declare function getPaymentGas(config: AxiosRequestConfig | undefined): X402PaymentGas | undefined;
 /**
  * Options for createApiClient
  */
@@ -128,6 +148,14 @@ export type PaymentTokenType = 'STX' | 'sBTC' | 'unsupported';
  * @param asset - Full contract identifier or token name
  */
 export declare function detectTokenType(asset: string): PaymentTokenType;
+/**
+ * Whether an x402 payment requirement offers gas sponsorship (sign with fee 0,
+ * the relay co-signs and pays the STX fee). x402-stacks documents a non-empty
+ * `extra.feePayer` as the signal; `extra.sponsored === true` is also honored
+ * for endpoints that send only that, and an explicit `sponsored: false` wins.
+ * Shared by createApiClient and x402-post so both paths use one rule.
+ */
+export declare function isSponsoredRequirement(extra?: Record<string, unknown>): boolean;
 /**
  * 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.

package/dist/services/x402.service.js

@@ -367,6 +367,14 @@ export async function mnemonicToAccount(mnemonic, network) {
         network,
     };
 }
+/**
+ * Read the gas decision the interceptor attached to a paid request's config
+ * (`response.config` on success, `error.config` on failure). Undefined when
+ * no payment was signed.
+ */
+export function getPaymentGas(config) {
+    return config?.x402PaymentGas;
+}
 /**
  * Build a canonical absolute URL for a request so that the L402 attempt
  * counter and macaroon cache are keyed by the actual endpoint, not the
@@ -662,7 +670,7 @@ export async function createApiClient(baseUrl, options) {
             }
             // 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;
+            const sponsored = isSponsoredRequirement(selectedOption.extra);
             // 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) {
@@ -758,6 +766,7 @@ export async function createApiClient(baseUrl, options) {
             const originalRequest = error.config;
             originalRequest.headers = originalRequest.headers || {};
             originalRequest.headers[X402_HEADERS.PAYMENT_SIGNATURE] = encodedPayload;
+            originalRequest.x402PaymentGas = { sponsored, feeUstx: fee.toString() };
             return axiosInstance.request(originalRequest);
         }
         catch (paymentError) {
@@ -827,6 +836,18 @@ export function detectTokenType(asset) {
     }
     return 'unsupported';
 }
+/**
+ * Whether an x402 payment requirement offers gas sponsorship (sign with fee 0,
+ * the relay co-signs and pays the STX fee). x402-stacks documents a non-empty
+ * `extra.feePayer` as the signal; `extra.sponsored === true` is also honored
+ * for endpoints that send only that, and an explicit `sponsored: false` wins.
+ * Shared by createApiClient and x402-post so both paths use one rule.
+ */
+export function isSponsoredRequirement(extra) {
+    if (extra?.sponsored === false)
+        return false;
+    return (typeof extra?.feePayer === "string" && extra.feePayer !== "") || extra?.sponsored === true;
+}
 const STACKS_MEMO_MAX_BYTES = 34;
 /**
  * Memo for an x402 payment from the server's `extra.payment_id`, cut to the

package/dist/tools/endpoint.tools.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { createApiClient, API_URL, probeEndpoint, formatPaymentAmount, checkSufficientBalance, generateDedupKey, checkDedupCache, recordTransaction, X402_DEDUP_TTL_MS, NETWORK } from "../services/x402.service.js";
+import { createApiClient, API_URL, probeEndpoint, formatPaymentAmount, checkSufficientBalance, generateDedupKey, checkDedupCache, recordTransaction, X402_DEDUP_TTL_MS, NETWORK, getPaymentGas } from "../services/x402.service.js";
 import { STATIC_ENDPOINTS, formatEndpointsTable } from "../endpoints/registry.js";
 import { discoverOpenApiEndpoints, fetchDirectoryEntries, } from "../services/x402-discovery.service.js";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
@@ -127,6 +127,18 @@ function formatProbeResponse(result, method, fullUrl, callWithOptions, messagePr
         callWith: buildCallWith(callWithOptions),
     });
 }
+/**
+ * One line saying who pays STX gas for a payment that was signed but whose
+ * call failed, or "" when none was signed. The fee is only charged if the
+ * payment settles on chain, which a failed call does not tell us.
+ */
+function formatGasLine(gas) {
+    if (!gas)
+        return "";
+    return gas.sponsored
+        ? "\n\nGas: sponsored (the endpoint's relay pays the STX fee if the payment settles)."
+        : `\n\nGas: self-paid; the payment was signed with a ${gas.feeUstx} uSTX fee, charged only if it settles on chain.`;
+}
 export function registerEndpointTools(server) {
     // List x402 endpoints
     server.registerTool("list_x402_endpoints", {
@@ -273,6 +285,8 @@ Supported sources:
 
 Use list_x402_endpoints to discover available endpoints.
 
+A paid result includes txid and gas: {sponsored, feeUstx}. Sponsored means the endpoint's relay pays the STX fee (feeUstx "0"); otherwise this wallet paid feeUstx on top of the price.
+
 For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs a standard sBTC transfer and settles directly through the x402 facilitator.`,
         inputSchema: z.object({
             method: z
@@ -402,10 +416,13 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
                 : txid !== null
                     ? { txid }
                     : {};
+            // Who paid STX gas for the payment, as decided when it was signed.
+            const gas = getPaymentGas(response.config);
             return createJsonResponse({
                 endpoint: `${method} ${fullUrl}`,
                 response: response.data,
                 ...txidFields,
+                ...(gas && { gas }),
             });
         }
         catch (error) {
@@ -423,6 +440,9 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
             // Mirrors the success path, including the synthetic pending marker
             // used when the txid is not yet observable.
             const paymentSigHeader = axiosError.config?.headers?.[X402_HEADERS.PAYMENT_SIGNATURE];
+            // A signed payment may still settle after the call failed, so say who
+            // pays gas on every error path too.
+            const gasLine = formatGasLine(getPaymentGas(axiosError.config));
             if (paymentSigHeader && dedupKey) {
                 const broadcastTxid = extractTxidFromPaymentSignature(paymentSigHeader);
                 await recordTransaction(dedupKey, broadcastTxid ?? `pending:${dedupKey}`);
@@ -453,7 +473,7 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
                 }
                 return {
                     ...baseError,
-                    content: [{ type: "text", text }],
+                    content: [{ type: "text", text: text + gasLine }],
                 };
             }
             if (paymentSigHeader) {
@@ -480,11 +500,29 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
                                     `Transaction recovery info:\n` +
                                     `  txid: ${confirmation.txid}\n` +
                                     `  status: ${confirmation.status}\n` +
-                                    `  explorer: ${confirmation.explorer}`,
+                                    `  explorer: ${confirmation.explorer}` +
+                                    gasLine,
                             },
                         ],
                     };
                 }
+                // No txid from the header: a sponsored payment (the relay assigns its
+                // txid when it sponsors) or one that didn't decode. It may still have
+                // settled, so point at where the real txid can be found.
+                const baseError = formatEndpointError(error, label);
+                return {
+                    ...baseError,
+                    content: [
+                        {
+                            type: "text",
+                            text: baseError.content[0].text +
+                                `\n\nA payment was signed, but its txid is not known here` +
+                                (fallbackPaymentId ? ` (paymentId: ${fallbackPaymentId})` : "") +
+                                `. It may have settled: query get_account_transactions for this wallet before paying again.` +
+                                gasLine,
+                        },
+                    ],
+                };
             }
             return formatEndpointError(error, label);
         }

package/dist/tools/inbox-auto-reply.tools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Inbox auto-reply tools.
+ *
+ * - inbox_auto_reply_configure: store enabled / model / systemPrompt / dailyCapSats /
+ *   maxSatsPerReply in ~/.aibtc/config.json (no args = show the current settings)
+ * - inbox_auto_reply: answer paid, unanswered inbox messages with a reply
+ *   written by an AIBTC Inference Marketplace model (x402, sBTC), then sign and
+ *   post it to the outbox. Built to be called from an agent's autonomy loop.
+ *
+ * The run logic, ledger and safety rules live in services/inbox-auto-reply.service.ts.
+ */
+import { McpServer } from "@modelcontextprotocol/server";
+export declare function registerInboxAutoReplyTools(server: McpServer): void;
+//# sourceMappingURL=inbox-auto-reply.tools.d.ts.map

package/dist/tools/inbox-auto-reply.tools.js

@@ -0,0 +1,177 @@
+/**
+ * Inbox auto-reply tools.
+ *
+ * - inbox_auto_reply_configure: store enabled / model / systemPrompt / dailyCapSats /
+ *   maxSatsPerReply in ~/.aibtc/config.json (no args = show the current settings)
+ * - inbox_auto_reply: answer paid, unanswered inbox messages with a reply
+ *   written by an AIBTC Inference Marketplace model (x402, sBTC), then sign and
+ *   post it to the outbox. Built to be called from an agent's autonomy loop.
+ *
+ * The run logic, ledger and safety rules live in services/inbox-auto-reply.service.ts.
+ */
+import { z } from "zod";
+import { getAccount, NETWORK } from "../services/x402.service.js";
+import { DEFAULT_AUTO_REPLY_MODEL, DEFAULT_DAILY_CAP_SATS, DEFAULT_MAX_REPLIES_PER_RUN, DEFAULT_MAX_SATS_PER_REPLY, listLiveModels, marketplaceReplyGenerator, runAutoReply, } from "../services/inbox-auto-reply.service.js";
+import { readAppConfig, writeAppConfig } from "../utils/storage.js";
+import { createJsonResponse, createErrorResponse } from "../utils/index.js";
+/**
+ * The stored sat limits, defaulted and checked. The config file is plain JSON
+ * (shared with the skills CLI), so a missing or hand-edited value must not
+ * turn into "no limit" at run time.
+ */
+function autoReplyLimits(config) {
+    const limit = (name, value, fallback) => {
+        if (value === undefined || value === null)
+            return fallback;
+        if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+            throw new Error(`inboxAutoReply.${name} in ~/.aibtc/config.json must be a non-negative integer, got ${JSON.stringify(value)}. ` +
+                `Fix it with inbox_auto_reply_configure { ${name}: <sats> }.`);
+        }
+        return value;
+    };
+    return {
+        dailyCapSats: limit("dailyCapSats", config.dailyCapSats, DEFAULT_DAILY_CAP_SATS),
+        maxSatsPerReply: limit("maxSatsPerReply", config.maxSatsPerReply, DEFAULT_MAX_SATS_PER_REPLY),
+    };
+}
+function requireMainnet() {
+    if (NETWORK !== "mainnet") {
+        throw new Error("Inbox auto-reply is mainnet only: the aibtc.com inbox and the inference marketplace settle in mainnet sBTC. Set NETWORK=mainnet.");
+    }
+}
+export function registerInboxAutoReplyTools(server) {
+    server.registerTool("inbox_auto_reply_configure", {
+        description: "Configure inbox auto-reply (stored in ~/.aibtc/config.json). Call with no arguments to see the current " +
+            "settings. A systemPrompt (the agent's voice / personality / what it can help with) is required before " +
+            "auto-reply can be enabled. The model must be live on inference.aibtc.com; it is checked against the " +
+            "catalog when set. dailyCapSats caps sats spent on reply inference per UTC day, on top of the wallet-wide " +
+            "spending limit. maxSatsPerReply is the most one reply may cost; a higher quote stops the run unpaid.",
+        inputSchema: z.object({
+            enabled: z.boolean().optional().describe("Allow inbox_auto_reply to post replies. Dry runs work while disabled."),
+            model: z
+                .string()
+                .optional()
+                .describe(`Inference marketplace model id (see GET https://inference.aibtc.com/v1/models). Default ${DEFAULT_AUTO_REPLY_MODEL}.`),
+            systemPrompt: z
+                .string()
+                .min(1)
+                .max(4000)
+                .optional()
+                .describe("System prompt for reply generation: who the agent is, its tone, what it offers, what it won't do."),
+            dailyCapSats: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe(`Most sats spent on reply inference per UTC day. Default ${DEFAULT_DAILY_CAP_SATS}.`),
+            maxSatsPerReply: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe(`Most sats paid for one reply. Default ${DEFAULT_MAX_SATS_PER_REPLY}.`),
+        }),
+    }, async ({ enabled, model, systemPrompt, dailyCapSats, maxSatsPerReply }) => {
+        try {
+            const config = await readAppConfig();
+            const current = config.inboxAutoReply;
+            if (enabled === undefined &&
+                model === undefined &&
+                systemPrompt === undefined &&
+                dailyCapSats === undefined &&
+                maxSatsPerReply === undefined) {
+                return createJsonResponse({
+                    configured: Boolean(current),
+                    settings: current ?? null,
+                    ...(!current && {
+                        note: "Not configured. Set at least systemPrompt, then enabled: true.",
+                    }),
+                });
+            }
+            if (model !== undefined) {
+                const live = await listLiveModels();
+                if (!live.includes(model)) {
+                    throw new Error(`Model "${model}" is not live on the inference marketplace. Live models: ${live.join(", ")}`);
+                }
+            }
+            const next = {
+                enabled: enabled ?? current?.enabled ?? false,
+                model: model ?? current?.model ?? DEFAULT_AUTO_REPLY_MODEL,
+                systemPrompt: systemPrompt ?? current?.systemPrompt ?? "",
+                dailyCapSats: dailyCapSats ?? current?.dailyCapSats ?? DEFAULT_DAILY_CAP_SATS,
+                maxSatsPerReply: maxSatsPerReply ?? current?.maxSatsPerReply ?? DEFAULT_MAX_SATS_PER_REPLY,
+            };
+            if (next.enabled && !next.systemPrompt) {
+                throw new Error("Set a systemPrompt before enabling auto-reply.");
+            }
+            await writeAppConfig({ ...config, inboxAutoReply: next });
+            return createJsonResponse({ success: true, settings: next });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    server.registerTool("inbox_auto_reply", {
+        description: "Answer this agent's paid aibtc.com inbox messages automatically. In one call: reads the inbox, picks paid, " +
+            "settled, unanswered messages (oldest first), writes each reply with an AIBTC Inference Marketplace model " +
+            "(paid per request in sBTC via x402, ~1 sat), signs it (BIP-322) and posts it to the outbox (free). " +
+            "Never answers a message twice (overlapping runs skip a message another run is answering), stops at the " +
+            "daily cap or on a quote above maxSatsPerReply, gives up on a message after 2 paid failures, and returns a summary: checked, replied, " +
+            "skipped (with reason), failed, inference sats spent and inference cap remaining.\n\n" +
+            "Posting a reply is free; the only cost is the inference call that writes it. " +
+            "Call it from the autonomy loop when the heartbeat or inbox shows unread messages. Configure first with " +
+            "inbox_auto_reply_configure. dryRun writes (and pays for) replies without posting them, so the operator " +
+            "can review the voice; each draft is saved and reused by later dry runs and the real run while the " +
+            "systemPrompt and model are unchanged. Requires an unlocked wallet with a bc1q address and a little sBTC. Mainnet only.",
+        inputSchema: z.object({
+            maxRepliesPerRun: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .optional()
+                .describe(`Most messages to answer in this call. Default ${DEFAULT_MAX_REPLIES_PER_RUN}.`),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("Generate replies without posting them or marking messages handled. A new draft is paid for once; " +
+                "a saved draft with the same systemPrompt and model is reused free, here and by the real run."),
+        }),
+    }, async ({ maxRepliesPerRun, dryRun }) => {
+        try {
+            requireMainnet();
+            const config = (await readAppConfig()).inboxAutoReply;
+            if (!config?.systemPrompt) {
+                throw new Error("Inbox auto-reply is not configured. Call inbox_auto_reply_configure with a systemPrompt first.");
+            }
+            const isDryRun = dryRun ?? false;
+            if (!config.enabled && !isDryRun) {
+                throw new Error("Inbox auto-reply is disabled. Enable it with inbox_auto_reply_configure { enabled: true }, or pass dryRun: true to preview replies.");
+            }
+            const limits = autoReplyLimits(config);
+            const account = await getAccount();
+            const summary = await runAutoReply({
+                account,
+                systemPrompt: config.systemPrompt,
+                ...limits,
+                maxRepliesPerRun: maxRepliesPerRun ?? DEFAULT_MAX_REPLIES_PER_RUN,
+                dryRun: isDryRun,
+                generator: marketplaceReplyGenerator(config.model),
+            });
+            return createJsonResponse({
+                success: summary.failed.length === 0,
+                dryRun: isDryRun,
+                model: config.model,
+                ...summary,
+                repliedCount: summary.replied.length,
+                skippedCount: summary.skipped.length,
+                failedCount: summary.failed.length,
+                ...limits,
+            });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=inbox-auto-reply.tools.js.map

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

@@ -9,13 +9,8 @@ export declare function checkDirectInboxBalance(address: string, amount: string,
  * 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`,
- * 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).
+ * The inbox decides who pays gas (402 `extra.feePayer`); the sponsored and
+ * self-paid paths live in `postWithX402Payment` (`services/x402-post.ts`).
  *
  * 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,8 +1,7 @@
 import { z } from "zod";
-import axios, { AxiosError } from "axios";
-import { wrapAxiosWithPayment, decodePaymentRequired, decodePaymentResponse, X402_HEADERS, } from "x402-stacks";
-import { createApiClient, getAccount, NETWORK } from "../services/x402.service.js";
-import { getSpendLimiter } from "../services/spend-limiter.js";
+import { AxiosError } from "axios";
+import { getAccount, NETWORK } from "../services/x402.service.js";
+import { postWithX402Payment } from "../services/x402-post.js";
 import { getSbtcService } from "../services/sbtc.service.js";
 import { getHiroApi } from "../services/hiro-api.js";
 import { getExplorerTxUrl } from "../config/networks.js";
@@ -56,33 +55,12 @@ export async function checkDirectInboxBalance(address, amount, sponsored = false
             `This send requires STX for gas — deposit STX to cover the transfer fee.`, "STX", stxBalance.toString(), feeBudget.toString(), shortfall.toString());
     }
 }
-/**
- * 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`,
- * 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).
+ * The inbox decides who pays gas (402 `extra.feePayer`); the sponsored and
+ * self-paid paths live in `postWithX402Payment` (`services/x402-post.ts`).
  *
  * Server side: `lib/inbox/x402-verify.ts` deserializes the payment tx and
  * branches on `tx.auth.authType` (sponsored → relay sponsors; standard →
@@ -126,79 +104,24 @@ export function registerInboxX402Tools(server) {
                 toStxAddress: recipientStxAddress,
                 content,
             };
-            // Step 1: Probe for the 402 challenge (no payment) so we can pre-check
-            // balance before signing. A bare POST never charges — it just returns
-            // the payment requirements. We use plain fetch here so the x402-stacks
-            // interceptor does not auto-pay this probe.
-            const probe = await fetch(inboxUrl, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(body),
-                signal: AbortSignal.timeout(30_000),
+            // Probe for the 402, pre-flight the balance (sBTC for the message, plus
+            // a realistic STX gas budget when the sender pays its own fee), then pay.
+            const result = await postWithX402Payment({
+                baseUrl: INBOX_BASE,
+                url: inboxUrl,
+                body,
+                toolName: "send_inbox_message_direct",
+                beforePay: (accept, sponsored) => checkDirectInboxBalance(account.address, accept.amount, sponsored),
+                timeoutMs: 120_000,
             });
-            if (probe.status !== 402) {
-                const text = await probe.text();
-                if (probe.ok) {
-                    return createJsonResponse({
-                        success: true,
-                        message: "Message sent (no payment required)",
-                        response: text,
-                    });
-                }
-                throw new Error(`Expected 402 payment challenge, got ${probe.status}: ${text}`);
-            }
-            const paymentRequired = decodePaymentRequired(probe.headers.get(X402_HEADERS.PAYMENT_REQUIRED));
-            if (!paymentRequired?.accepts?.length) {
-                throw new Error("402 response missing or empty payment-required header");
-            }
-            const accept = paymentRequired.accepts[0];
-            // 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);
-            // 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,
-                };
-                // x402-stacks is CJS, so its AxiosInstance comes from axios' .d.cts
-                // types; ours comes from .d.ts. Same runtime object, different type.
-                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" },
+            if (!result.paid) {
+                return createJsonResponse({
+                    success: true,
+                    message: "Message sent (no payment required)",
+                    response: result.text,
                 });
             }
-            // 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;
+            const { response, accept, sponsored, txid, payer } = result;
             return createJsonResponse({
                 success: true,
                 message: sponsored

package/dist/tools/index.js

@@ -50,6 +50,7 @@ import { registerBountyScannerTools } from "./bounty-scanner.tools.js";
 import { registerRunesTools } from "./runes.tools.js";
 import { registerInboxTools } from "./inbox.tools.js";
 import { registerInboxX402Tools } from "./inbox-x402.tools.js";
+import { registerInboxAutoReplyTools } from "./inbox-auto-reply.tools.js";
 import { registerArxivResearchTools } from "./arxiv-research.tools.js";
 import { registerEarningTools } from "./earning.tools.js";
 import { registerTaskmarketTools } from "./taskmarket.tools.js";
@@ -211,6 +212,8 @@ export function registerAllTools(server, selection) {
     inGroup("social", registerInboxTools);
     // Inbox direct x402 (non-sponsored — sender pays own STX gas, no relay)
     inGroup("social", registerInboxX402Tools);
+    // Inbox auto-reply (answer paid inbox messages with an inference marketplace model)
+    inGroup("social", registerInboxAutoReplyTools);
     // arXiv Research (public arXiv Atom API — paper search and digest compilation)
     inGroup("dev", registerArxivResearchTools);
     // Earning Opportunities (static "how to put your assets to work" menu)

package/dist/tools/profiles.js

@@ -44,6 +44,9 @@ export const CORE_TOOLS = new Set([
     "bounty_get",
     "bounty_submit",
     "identity_register",
+    // Inbox auto-reply (off until the agent sets a system prompt and enables it)
+    "inbox_auto_reply",
+    "inbox_auto_reply_configure",
 ]);
 export const TOOL_GROUPS = {
     wallet: "Wallet management extras, encrypted credential store",

package/dist/tools/skill-mappings.js

@@ -107,6 +107,8 @@ export const TOOL_SKILL_MAP = {
     openrouter_models: "x402",
     send_inbox_message: "x402",
     send_inbox_message_direct: "x402",
+    inbox_auto_reply: "x402",
+    inbox_auto_reply_configure: "x402",
     // defi skill — ALEX DEX and Zest Protocol
     alex_list_pools: "defi",
     alex_get_swap_quote: "defi",

package/dist/utils/storage.d.ts

@@ -39,6 +39,15 @@ export interface AppConfig {
     autoLockTimeout: number;
     hiroApiKey?: string;
     stacksApiUrl?: string;
+    /** Set by inbox_auto_reply_configure; unset means auto-reply was never configured. */
+    inboxAutoReply?: {
+        enabled: boolean;
+        model: string;
+        systemPrompt: string;
+        dailyCapSats: number;
+        /** Most sats paid for one reply. Missing in configs written before it existed. */
+        maxSatsPerReply?: number;
+    };
 }
 /**
  * Keystore file structure (contains encrypted mnemonic)

package/dist/utils/x402-recovery.d.ts

@@ -14,7 +14,10 @@ import { type Network } from "../config/networks.js";
  * The payment-signature header is a base64-encoded JSON PaymentPayloadV2 object
  * whose payload.transaction field contains the signed transaction hex.
  *
- * Returns the txid string (64-char hex, no 0x prefix), or null if extraction fails.
+ * Returns the txid string (64-char hex, no 0x prefix), or null if extraction
+ * fails or the payment is sponsored. A sponsored transaction gets its txid only
+ * when the relay adds its sponsor signature and fee, so the txid of the signed
+ * payment in the header never appears on chain.
  */
 export declare function extractTxidFromPaymentSignature(paymentSignatureHeader: string): string | null;
 /**

package/dist/utils/x402-recovery.js

@@ -7,7 +7,7 @@
  * Used by inbox.tools.ts and endpoint.tools.ts as an operational fallback
  * when canonical paymentId polling is unavailable or inconclusive.
  */
-import { deserializeTransaction } from "@stacks/transactions";
+import { AuthType, deserializeTransaction } from "@stacks/transactions";
 import { getHiroApi } from "../services/hiro-api.js";
 import { getExplorerTxUrl } from "../config/networks.js";
 import { decodePaymentPayload } from "./x402-protocol.js";
@@ -20,7 +20,10 @@ import { decodePaymentPayload } from "./x402-protocol.js";
  * The payment-signature header is a base64-encoded JSON PaymentPayloadV2 object
  * whose payload.transaction field contains the signed transaction hex.
  *
- * Returns the txid string (64-char hex, no 0x prefix), or null if extraction fails.
+ * Returns the txid string (64-char hex, no 0x prefix), or null if extraction
+ * fails or the payment is sponsored. A sponsored transaction gets its txid only
+ * when the relay adds its sponsor signature and fee, so the txid of the signed
+ * payment in the header never appears on chain.
  */
 export function extractTxidFromPaymentSignature(paymentSignatureHeader) {
     try {
@@ -33,6 +36,9 @@ export function extractTxidFromPaymentSignature(paymentSignatureHeader) {
         const hexWithout0x = txHex.startsWith("0x") ? txHex.slice(2) : txHex;
         const txBytes = Buffer.from(hexWithout0x, "hex");
         const tx = deserializeTransaction(txBytes);
+        if (tx.auth.authType === AuthType.Sponsored) {
+            return null;
+        }
         return tx.txid();
     }
     catch {