@aibtc/mcp-server 1.60.0 → 1.62.0

package/README.md

@@ -99,6 +99,8 @@ npx @aibtc/mcp-server@latest bridge --read-only --list-tools
 npx @aibtc/mcp-server@latest bridge --read-only --allow transfer_stx "send 1 STX to SP3..."
 ```
 
+Before any agent loop runs (and on `--list-tools`), the bridge prints a compact **safety receipt** to stderr — network, read-only mode, exposed/write/blocked tool counts, the session spend cap, and the number of known x402 endpoints — so the configured execution boundaries are visible up front. It reports boundaries only; it never claims any value moved.
+
 The allowlist is re-enforced at execution time, so a model can never call a tool outside the exposed set. Any MCP-capable agent framework (`@openrouter/agent`, OpenAI Agents SDK, Claude Agent SDK) can also point at this server directly — the bridge is for driving it through OpenRouter's raw API without adopting a framework.
 
 ### Testnet Mode

package/dist/bridge/index.js

@@ -29,6 +29,7 @@
  */
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { ALL_ENDPOINTS } from "../endpoints/registry.js";
 const OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions";
 const DEFAULT_MODEL = "anthropic/claude-3.5-haiku";
 /**
@@ -136,6 +137,28 @@ function parseArgs(argv) {
     opts.prompt = promptWords.join(" ").trim();
     return opts;
 }
+/**
+ * Compact safety receipt printed before any agent loop runs (#583). Makes the
+ * configured execution boundaries visible up front so a user can trust the
+ * bridge without digging through flags/config. It reports ONLY configured
+ * boundaries — it never claims that any value moved. Emitted on stderr so it
+ * can't pollute stdout (the final assistant reply / --list-tools piping).
+ */
+function printSafetyReceipt(opts, exposed, totalTools) {
+    const writeToolCount = exposed.filter((t) => !isReadOnly(t.name)).length;
+    const lines = [
+        "aibtc-mcp bridge — safety receipt",
+        `  network=${opts.network}`,
+        `  read_only=${opts.readOnly}`,
+        `  exposed_tools=${exposed.length}/${totalTools}`,
+        `  write_tool_count=${writeToolCount}`,
+        `  blocked_tool_count=${opts.block.size}`,
+        `  session_spend_cap=${opts.maxSpendUstx ?? "default"} uSTX / ${opts.maxSpendSats ?? "default"} sats`,
+        `  x402_endpoints_known=${ALL_ENDPOINTS.length}`,
+        "  (reports configured execution boundaries only; no value has moved)",
+    ];
+    console.error(lines.join("\n"));
+}
 /** Apply read-only + allow + block to the raw MCP tool list. */
 function selectTools(tools, opts) {
     return tools.filter((t) => {
@@ -193,6 +216,7 @@ export async function runBridge(argv) {
     const { tools: allTools } = await client.listTools();
     const exposed = selectTools(allTools, opts);
     if (opts.listTools) {
+        printSafetyReceipt(opts, exposed, allTools.length);
         console.log(`Exposed ${exposed.length}/${allTools.length} tools` +
             (opts.readOnly ? " (read-only)" : "") + ":");
         for (const t of exposed)
@@ -211,12 +235,8 @@ export async function runBridge(argv) {
         await client.close();
         process.exit(1);
     }
-    const writeCount = exposed.filter((t) => !isReadOnly(t.name)).length;
-    console.error(`Bridge: ${exposed.length} tools -> ${opts.model}` +
-        (opts.readOnly ? " [read-only]" : ` [${writeCount} can write/spend]`) +
-        (opts.maxSpendUstx || opts.maxSpendSats
-            ? ` (cap ${opts.maxSpendUstx ?? "-"} uSTX / ${opts.maxSpendSats ?? "-"} sats)`
-            : ""));
+    printSafetyReceipt(opts, exposed, allTools.length);
+    console.error(`  model=${opts.model}, max_turns=${opts.maxTurns}`);
     const openaiTools = exposed.map(toOpenAITool);
     const messages = [
         {

package/dist/tools/dual-stacking.tools.js

@@ -64,13 +64,33 @@ Note: Dual Stacking is only available on mainnet.`,
                 });
             }
             const resolvedAddress = address || (await getWalletAddress());
-            const [enrolledThisCycleRaw, enrolledNextCycleRaw, minimumAmountRaw, aprDataRaw, cycleOverviewRaw,] = await Promise.all([
+            // Use allSettled, not all: `is-enrolled-this-cycle` fails contract-side
+            // on mainnet with RuntimeCheck(AtBlockUnavailable) (it reads historical
+            // block state Hiro has pruned). With Promise.all a single failing read
+            // sinks the whole response, hiding the other 4 useful fields. Recover
+            // per-call and surface a `warnings` array instead. (#554)
+            const warnings = [];
+            const settled = await Promise.allSettled([
                 callDualStackingReadOnly("is-enrolled-this-cycle", [principalCV(resolvedAddress)]),
                 callDualStackingReadOnly("is-enrolled-in-next-cycle", [principalCV(resolvedAddress)]),
                 callDualStackingReadOnly("get-minimum-enrollment-amount", []),
                 callDualStackingReadOnly("get-apr-data", []),
                 callDualStackingReadOnly("current-overview-data", []),
             ]);
+            const readNames = [
+                "is-enrolled-this-cycle",
+                "is-enrolled-in-next-cycle",
+                "get-minimum-enrollment-amount",
+                "get-apr-data",
+                "current-overview-data",
+            ];
+            const values = settled.map((r, i) => {
+                if (r.status === "fulfilled")
+                    return r.value;
+                warnings.push(`${readNames[i]}: ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`);
+                return null;
+            });
+            const [enrolledThisCycleRaw, enrolledNextCycleRaw, minimumAmountRaw, aprDataRaw, cycleOverviewRaw,] = values;
             // Parse APR data — returns {min-apr: uint, max-apr: uint} divided by 1_000_000 for %
             let apr = {
                 minApr: 0,
@@ -107,10 +127,11 @@ Note: Dual Stacking is only available on mainnet.`,
                 const raw = minimumAmountRaw;
                 minimumEnrollmentSats = raw.value !== undefined ? Number(raw.value) : 0;
             }
-            // Parse boolean enrollment flags
+            // Parse boolean enrollment flags. A failed read stays null (unknown)
+            // rather than collapsing to a misleading `false`.
             const parseBoolean = (raw) => {
                 if (raw === null || raw === undefined)
-                    return false;
+                    return null;
                 if (typeof raw === "boolean")
                     return raw;
                 const obj = raw;
@@ -126,6 +147,7 @@ Note: Dual Stacking is only available on mainnet.`,
                 minimumEnrollmentSats,
                 apr,
                 cycleOverview,
+                ...(warnings.length > 0 && { warnings }),
             });
         }
         catch (error) {

package/dist/tools/index.js

@@ -34,6 +34,7 @@ import { registerOrdinalsMarketplaceTools } from "./ordinals-marketplace.tools.j
 import { registerTaprootMultisigTools } from "./taproot-multisig.tools.js";
 import { registerJingswapTools } from "./jingswap.tools.js";
 import { registerSigningTools } from "./signing.tools.js";
+import { registerInferenceMarketplaceTools } from "./inference-marketplace.tools.js";
 import { registerNewsTools } from "./news.tools.js";
 import { registerIdentityTools } from "./identity.tools.js";
 import { registerCredentialsTools } from "./credentials.tools.js";
@@ -160,6 +161,8 @@ export function registerAllTools(server) {
     registerJingswapTools(server);
     // Message Signing (BTC BIP-322, Stacks SIWS, SIP-018 structured data, Nostr NIP-01)
     registerSigningTools(server);
+    // AIBTC Inference Marketplace (list/manage a paid model endpoint via wallet signature)
+    registerInferenceMarketplaceTools(server);
     // AIBTC News (signal feed, leaderboard, file signals)
     registerNewsTools(server);
     // Identity (ERC-8004 on-chain agent identity management)

package/dist/tools/inference-marketplace.tools.d.ts

@@ -0,0 +1,30 @@
+/**
+ * AIBTC Inference Marketplace Tools
+ *
+ * List an OpenAI-compatible model endpoint on the marketplace and manage it, all
+ * authorized by a wallet signature (the same wallet that receives sBTC payouts).
+ * Ownership is proven by signing a short message with the payout wallet — no
+ * accounts, no API keys. These tools sign locally with the unlocked wallet and
+ * call the gateway, so an agent can register/update/check in one step.
+ *
+ * - inference_register_provider: verify + list an endpoint (signed)
+ * - inference_update_provider:   change name/models/payout/endpoint in place (signed)
+ * - inference_reveal_key:        reveal or rotate the gateway↔endpoint shared key (signed)
+ * - inference_check_provider:    re-run the health/functional probe (unsigned)
+ * - inference_list_providers:    list registered providers + health (unsigned)
+ *
+ * The gateway verifies the signature recovers to `payoutAddress` (which also
+ * enforces the network), that the endpoint is reachable AND serving inference,
+ * and that model ids are real, text-generation, commercially-licensed HF repos.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+type AuthAction = "register" | "update" | "reveal-key";
+/** The exact message the gateway rebuilds and verifies. Must match byte-for-byte. */
+export declare function authMessage(action: AuthAction, providerId: string, timestamp: number): string;
+/** Sign an auth message with the unlocked wallet and return the gateway headers. */
+export declare function signAuthHeaders(account: {
+    privateKey: string;
+}, action: AuthAction, providerId: string): Record<string, string>;
+export declare function registerInferenceMarketplaceTools(server: McpServer): void;
+export {};
+//# sourceMappingURL=inference-marketplace.tools.d.ts.map

package/dist/tools/inference-marketplace.tools.js

@@ -0,0 +1,303 @@
+/**
+ * AIBTC Inference Marketplace Tools
+ *
+ * List an OpenAI-compatible model endpoint on the marketplace and manage it, all
+ * authorized by a wallet signature (the same wallet that receives sBTC payouts).
+ * Ownership is proven by signing a short message with the payout wallet — no
+ * accounts, no API keys. These tools sign locally with the unlocked wallet and
+ * call the gateway, so an agent can register/update/check in one step.
+ *
+ * - inference_register_provider: verify + list an endpoint (signed)
+ * - inference_update_provider:   change name/models/payout/endpoint in place (signed)
+ * - inference_reveal_key:        reveal or rotate the gateway↔endpoint shared key (signed)
+ * - inference_check_provider:    re-run the health/functional probe (unsigned)
+ * - inference_list_providers:    list registered providers + health (unsigned)
+ *
+ * The gateway verifies the signature recovers to `payoutAddress` (which also
+ * enforces the network), that the endpoint is reachable AND serving inference,
+ * and that model ids are real, text-generation, commercially-licensed HF repos.
+ */
+import { z } from "zod";
+import { signMessageHashRsv, privateKeyToPublic, compressPublicKey, } from "@stacks/transactions";
+import { hashMessage } from "@stacks/encryption";
+import { bytesToHex } from "@stacks/common";
+import { createJsonResponse, createErrorResponse } from "../utils/index.js";
+import { getWalletManager } from "../services/wallet-manager.js";
+/** Default marketplace gateway; override with the `gateway` arg for local dev. */
+const DEFAULT_GATEWAY = "https://inference.aibtc.com";
+/** Bound network calls so a hung endpoint can't block the tool call forever. */
+const GATEWAY_TIMEOUT_MS = 15_000;
+/** Loopback hosts always allowed for local dev. */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+/**
+ * These tools sign an ownership message with the payout wallet and may forward
+ * the endpoint's own `apiKey` — both secrets. If the gateway destination were
+ * free-form, a prompt-injected "use gateway https://attacker.example" could
+ * redirect that signed request and leak the signature + apiKey. So the override
+ * is restricted to localhost and the marketplace (`*.aibtc.com`); any other host
+ * requires an explicit `allowUnsafeGateway: true`, which natural language alone
+ * won't set.
+ */
+function isAllowedGatewayHost(hostname) {
+    const host = hostname.toLowerCase();
+    if (LOOPBACK_HOSTS.has(host))
+        return true;
+    return host === "aibtc.com" || host.endsWith(".aibtc.com");
+}
+/** Validate + normalize the gateway base URL (trailing slash stripped). */
+function resolveGateway(gateway, allowUnsafe) {
+    const base = (gateway ?? DEFAULT_GATEWAY).replace(/\/$/, "");
+    let url;
+    try {
+        url = new URL(base);
+    }
+    catch {
+        throw new Error(`Invalid gateway URL: ${base}`);
+    }
+    if (!allowUnsafe && !isAllowedGatewayHost(url.hostname)) {
+        throw new Error(`Gateway host "${url.hostname}" is not allowed. Wallet-signed headers and your endpoint apiKey ` +
+            `are only sent to the marketplace (*.aibtc.com) or localhost. To target another host on ` +
+            `purpose, pass allowUnsafeGateway: true.`);
+    }
+    return base;
+}
+function requireUnlockedWallet() {
+    const account = getWalletManager().getActiveAccount();
+    if (!account) {
+        throw new Error("Wallet is not unlocked. Use wallet_unlock first to enable signing.");
+    }
+    return account;
+}
+/** The exact message the gateway rebuilds and verifies. Must match byte-for-byte. */
+export function authMessage(action, providerId, timestamp) {
+    return `Inference Marketplace\nAction: ${action}\nProvider: ${providerId}\nTimestamp: ${timestamp}`;
+}
+/** Sign an auth message with the unlocked wallet and return the gateway headers. */
+export function signAuthHeaders(account, action, providerId) {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const message = authMessage(action, providerId, timestamp);
+    const signature = signMessageHashRsv({
+        messageHash: bytesToHex(hashMessage(message)),
+        privateKey: account.privateKey,
+    });
+    const publicKey = compressPublicKey(privateKeyToPublic(account.privateKey));
+    return {
+        "Content-Type": "application/json",
+        "X-Stacks-Signature": signature,
+        "X-Stacks-Public-Key": publicKey,
+        "X-Stacks-Timestamp": String(timestamp),
+    };
+}
+async function gatewayFetch(url, init) {
+    const res = await fetch(url, { ...init, signal: AbortSignal.timeout(GATEWAY_TIMEOUT_MS) });
+    const text = await res.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = { raw: text };
+    }
+    return { ok: res.ok, status: res.status, body };
+}
+const gatewayArg = z
+    .string()
+    .url()
+    .optional()
+    .describe(`Marketplace gateway base URL. Defaults to ${DEFAULT_GATEWAY}. Use http://localhost:8787 for local dev.`);
+const allowUnsafeGatewayArg = z
+    .boolean()
+    .optional()
+    .describe("Allow a gateway host outside localhost / *.aibtc.com. Required to send wallet-signed headers " +
+    "(and any apiKey) to an arbitrary host — leave unset unless you deliberately self-host the gateway.");
+export function registerInferenceMarketplaceTools(server) {
+    // Register (verify + list) an endpoint — signed
+    server.registerTool("inference_register_provider", {
+        description: "List an OpenAI-compatible model endpoint on the AIBTC Inference Marketplace and get paid per request in sBTC. " +
+            "Signs a registration message with the unlocked payout wallet (proving ownership) and POSTs it. " +
+            "The gateway verifies the signature recovers to payoutAddress, that the endpoint is reachable AND actually " +
+            "serving inference, and that model ids are real/commercial Hugging Face repos — then lists it. " +
+            "Requires an unlocked wallet on the gateway's network.",
+        inputSchema: {
+            name: z.string().describe("Display name for your node, e.g. \"Alice's Qwen node\"."),
+            endpoint: z
+                .string()
+                .url()
+                .describe("OpenAI-compatible base URL, e.g. https://my-host/v1 (must expose /models and /chat/completions)."),
+            models: z
+                .array(z.string())
+                .min(1)
+                .describe("Hugging Face repo ids you serve, e.g. [\"Qwen/Qwen2.5-7B-Instruct\"]."),
+            payoutAddress: z
+                .string()
+                .optional()
+                .describe("Stacks address that receives sBTC. Defaults to the unlocked wallet's address (must match the gateway network)."),
+            apiKey: z
+                .string()
+                .optional()
+                .describe("Optional: a key your endpoint requires. Locks the endpoint so only the gateway (which presents it) can call it."),
+            gateway: gatewayArg,
+            allowUnsafeGateway: allowUnsafeGatewayArg,
+        },
+    }, async ({ name, endpoint, models, payoutAddress, apiKey, gateway, allowUnsafeGateway }) => {
+        try {
+            const account = requireUnlockedWallet();
+            const base = resolveGateway(gateway, allowUnsafeGateway ?? false);
+            const payout = payoutAddress ?? account.address;
+            const headers = signAuthHeaders(account, "register", endpoint);
+            const { ok, status, body } = await gatewayFetch(`${base}/v1/providers`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                    name,
+                    endpoint,
+                    payoutAddress: payout,
+                    models,
+                    ...(apiKey ? { apiKey } : {}),
+                }),
+            });
+            return createJsonResponse({
+                success: ok,
+                status,
+                payoutAddress: payout,
+                gateway: base,
+                result: body,
+                note: ok
+                    ? "Registered and verified. Your endpoint is listed and callable."
+                    : "Registration failed — see result.error (e.g. wrong network, endpoint unreachable, or invalid model id).",
+            });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Update a listing in place — signed
+    server.registerTool("inference_update_provider", {
+        description: "Update your marketplace listing in place — name, models, payout address, endpoint, or description — no delete/re-add. " +
+            "Signs an update message with the unlocked payout wallet and PATCHes it. Only fields you pass change. " +
+            "Changing the endpoint re-verifies reachability before taking effect. Requires an unlocked wallet.",
+        inputSchema: {
+            providerId: z.string().describe("The provider id returned at registration (from inference_list_providers)."),
+            name: z.string().optional().describe("New display name."),
+            endpoint: z.string().url().optional().describe("New OpenAI-compatible base URL (re-verified before it takes effect)."),
+            models: z.array(z.string()).optional().describe("New Hugging Face repo id list."),
+            payoutAddress: z.string().optional().describe("New payout address (must match the gateway network)."),
+            description: z.string().optional().describe("New description."),
+            apiKey: z.string().optional().describe("Set/replace the key your endpoint requires (locks the endpoint)."),
+            gateway: gatewayArg,
+            allowUnsafeGateway: allowUnsafeGatewayArg,
+        },
+    }, async ({ providerId, name, endpoint, models, payoutAddress, description, apiKey, gateway, allowUnsafeGateway }) => {
+        try {
+            const account = requireUnlockedWallet();
+            const base = resolveGateway(gateway, allowUnsafeGateway ?? false);
+            const patch = {};
+            if (name !== undefined)
+                patch.name = name;
+            if (endpoint !== undefined)
+                patch.endpoint = endpoint;
+            if (models !== undefined)
+                patch.models = models;
+            if (payoutAddress !== undefined)
+                patch.payoutAddress = payoutAddress;
+            if (description !== undefined)
+                patch.description = description;
+            if (apiKey !== undefined)
+                patch.apiKey = apiKey;
+            if (Object.keys(patch).length === 0) {
+                throw new Error("Nothing to update — pass at least one of name/endpoint/models/payoutAddress/description/apiKey.");
+            }
+            const headers = signAuthHeaders(account, "update", providerId);
+            const { ok, status, body } = await gatewayFetch(`${base}/v1/providers/${providerId}`, {
+                method: "PATCH",
+                headers,
+                body: JSON.stringify(patch),
+            });
+            return createJsonResponse({
+                success: ok,
+                status,
+                gateway: base,
+                result: body,
+                note: ok ? "Listing updated." : "Update failed — see result.error.",
+            });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Reveal or rotate the shared key — signed
+    server.registerTool("inference_reveal_key", {
+        description: "Reveal or rotate your provider's shared key — the gateway↔endpoint credential the gateway presents when it " +
+            "calls your endpoint (NOT an ownership token; ownership is your wallet). The gateway stores it write-only, so a " +
+            "wallet signature is the only way to read it back. Pass rotate=true to issue a new one. Requires an unlocked wallet.",
+        inputSchema: {
+            providerId: z.string().describe("The provider id (from inference_list_providers)."),
+            rotate: z.boolean().optional().describe("true = generate and return a NEW key (invalidates the old one). false/omitted = reveal the current key."),
+            gateway: gatewayArg,
+            allowUnsafeGateway: allowUnsafeGatewayArg,
+        },
+    }, async ({ providerId, rotate, gateway, allowUnsafeGateway }) => {
+        try {
+            const account = requireUnlockedWallet();
+            const base = resolveGateway(gateway, allowUnsafeGateway ?? false);
+            const headers = signAuthHeaders(account, "reveal-key", providerId);
+            const { ok, status, body } = await gatewayFetch(`${base}/v1/providers/${providerId}/key`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(rotate ? { rotate: true } : {}),
+            });
+            return createJsonResponse({
+                success: ok,
+                status,
+                gateway: base,
+                result: body,
+                note: ok
+                    ? "Your endpoint must REQUIRE this key (proxy / Cloudflare Access) for it to prevent freeloading — an open endpoint ignores it."
+                    : "Reveal/rotate failed — see result.error.",
+            });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // Re-run the health/functional probe — unsigned
+    server.registerTool("inference_check_provider", {
+        description: "Re-run the marketplace's health + functional probe for a provider on demand (checks the endpoint is reachable and " +
+            "actually returns a completion). No signature required. Useful right after (re)starting your node or tunnel.",
+        inputSchema: {
+            providerId: z.string().describe("The provider id to check."),
+            gateway: gatewayArg,
+            allowUnsafeGateway: allowUnsafeGatewayArg,
+        },
+    }, async ({ providerId, gateway, allowUnsafeGateway }) => {
+        try {
+            const base = resolveGateway(gateway, allowUnsafeGateway ?? false);
+            const { ok, status, body } = await gatewayFetch(`${base}/v1/providers/${providerId}/check`, {
+                method: "POST",
+            });
+            return createJsonResponse({ success: ok, status, gateway: base, result: body });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+    // List registered providers — unsigned
+    server.registerTool("inference_list_providers", {
+        description: "List providers registered on the marketplace with their models, health/status, and flagged state. No signature " +
+            "required. Use it to find your provider id (match on payoutAddress) after registering.",
+        inputSchema: {
+            gateway: gatewayArg,
+            allowUnsafeGateway: allowUnsafeGatewayArg,
+        },
+    }, async ({ gateway, allowUnsafeGateway }) => {
+        try {
+            const base = resolveGateway(gateway, allowUnsafeGateway ?? false);
+            const { ok, status, body } = await gatewayFetch(`${base}/v1/providers`, { method: "GET" });
+            return createJsonResponse({ success: ok, status, gateway: base, result: body });
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=inference-marketplace.tools.js.map

package/dist/tools/lightning.tools.js

@@ -7,9 +7,11 @@
  * same LightningProvider singleton to auto-pay invoice challenges on 402s.
  */
 import { z } from "zod";
+import { decode as decodeBolt11 } from "light-bolt11-decoder";
 import { createJsonResponse, createErrorResponse } from "../utils/index.js";
 import { getLightningManager } from "../services/lightning-manager.js";
 import { getWalletManager } from "../services/wallet-manager.js";
+import { getSpendLimiter } from "../services/spend-limiter.js";
 import { MempoolApi, getMempoolTxUrl, } from "../services/mempool-api.js";
 import { buildAndSignBtcTransaction } from "../transactions/bitcoin-builder.js";
 import { UnisatIndexer } from "../services/unisat-indexer.js";
@@ -284,11 +286,39 @@ export function registerLightningTools(server) {
             if (!provider) {
                 throw new Error("Lightning wallet is locked. Use lightning_unlock first.");
             }
+            // Meter the invoice face value against the cumulative sats spend limit
+            // (#572). maxFeeSats only bounds the routing fee, not the payable amount,
+            // so without this a single invoice can pay out an unbounded amount.
+            // Decode the invoice to read the amount (millisats), mirroring the L402
+            // auto-pay path in x402.service.ts.
+            let decoded;
+            try {
+                decoded = decodeBolt11(bolt11);
+            }
+            catch (decodeErr) {
+                throw new Error(`BOLT-11 invoice could not be decoded: ${decodeErr instanceof Error ? decodeErr.message : String(decodeErr)}`);
+            }
+            const amountSection = decoded.sections.find((s) => s.name === "amount");
+            const amountMsat = amountSection?.value ? BigInt(amountSection.value) : 0n;
+            const amountSats = Number(amountMsat / 1000n);
+            if (amountSats === 0) {
+                throw new Error("Invoice has no amount; refusing to pay amountless invoices for safety (an unmeterable spend defeats the spending cap).");
+            }
+            // Key the sats ledger by the active Stacks address so BTC L1 / sBTC /
+            // L402 / Lightning spends share one budget. When the main wallet is
+            // locked (Lightning has its own session), fall back to a dedicated
+            // Lightning bucket so the pay is always metered. Note: a locked-STX
+            // 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);
             const result = await provider.payInvoice(bolt11, maxFeeSats);
+            await getSpendLimiter().record("sats", BigInt(amountSats), ledgerKey);
             return createJsonResponse({
                 success: true,
                 preimage: result.preimage,
                 feesPaidSats: result.feesPaid,
+                amountSats,
             });
         }
         catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.60.0",
+  "version": "1.62.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",

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.60.0 # x-release-please-version
+  version: 1.62.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---
@@ -214,6 +214,33 @@ Always probe before executing paid endpoints. Never call `execute_x402_endpoint`
 See: [references/stacks-defi.md](references/stacks-defi.md) for endpoint catalog
 See: [references/x402-inbox.md](references/x402-inbox.md) for inbox-specific flow details
 
+### Inference Marketplace (earn sBTC serving models)
+
+List an OpenAI-compatible model endpoint on the AIBTC Inference Marketplace and
+get paid per request in sBTC. Ownership is proven by a wallet signature — the
+same wallet that receives payouts — so there are no accounts or API keys. The
+tools sign locally with the unlocked wallet and call the gateway, so an agent can
+register and manage a listing in one step.
+
+```
+"Register my endpoint https://my-host/v1 serving Qwen/Qwen2.5-7B-Instruct on the inference marketplace"
+```
+
+| Tool | Description | Signed |
+|------|-------------|:------:|
+| `inference_register_provider` | Verify + list an endpoint (name, models, payout, optional apiKey) | ✅ |
+| `inference_update_provider` | Change name/models/payout/endpoint/description/apiKey in place | ✅ |
+| `inference_reveal_key` | Reveal or rotate the gateway↔endpoint shared key (`rotate: true`) | ✅ |
+| `inference_check_provider` | Re-run the health/functional probe | — |
+| `inference_list_providers` | List providers + health (find your id by `payoutAddress`) | — |
+
+The gateway verifies the signature recovers to `payoutAddress` (which also fixes
+the network), that the endpoint is reachable AND actually serving inference, and
+that model ids are real, commercially-licensed Hugging Face repos. Requires an
+unlocked wallet on the gateway's network. Every tool takes an optional `gateway`
+arg (defaults to `https://inference.aibtc.com`; use `http://localhost:8787` for
+local dev).
+
 ### Genesis Lifecycle
 
 Agent identity and reputation on Bitcoin and Stacks: