@aibtc/mcp-server 1.64.1 → 1.65.0

package/dist/index.js

@@ -7,6 +7,7 @@ import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerAllTools } from "./tools/index.js";
+import { installBountyHint } from "./tools/bounty-hint.js";
 import { NETWORK, API_URL } from "./config/index.js";
 import { redactSensitive } from "./utils/redact.js";
 import { initializeStorage } from "./utils/storage.js";
@@ -253,9 +254,26 @@ else {
     const server = new McpServer({
         name: "aibtc-mcp-server",
         version: packageJson.version,
+    }, {
+        instructions: [
+            "This server lets an agent earn and move real Bitcoin/sBTC on Stacks.",
+            "",
+            "Hunt bounties. The most direct way to earn here is the sBTC bounty board:",
+            "call bounty_list to see open bounties, bounty_get for the task detail, do",
+            "the work, then bounty_submit your deliverable. Accepted submissions are paid",
+            "in sBTC. Check periodically for new open bounties.",
+            "",
+            "For the full menu of ways to put assets to work (stacking, DeFi yield,",
+            "trading, paid endpoints), call earning_opportunities. Submitting to a bounty",
+            "requires a Registered (L1+) on-chain identity — see identity_register.",
+        ].join("\n"),
     });
+    // Append a bounty-board hint to spend/onboarding-tool output.
+    // Must wrap registerTool before registration; restore it after.
+    const restoreBountyHint = installBountyHint(server);
     // Register all tools from the modular registry
     registerAllTools(server);
+    restoreBountyHint();
     async function main() {
         await initializeStorage();
         const transport = new StdioServerTransport();

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

@@ -1,4 +1,5 @@
 import { type AxiosInstance } 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";
 /**
@@ -34,6 +35,12 @@ export interface CreateApiClientOptions {
      */
     onBeforePayment?: (requirements: PaymentRequirements) => Promise<void>;
     toolName?: string;
+    /**
+     * Which asset to pay with when the endpoint offers several — an asset
+     * identifier ("SM3V....sbtc-token") or a symbol ("sBTC", "STX", "USDCx").
+     * Unset means the first entry this client can pay for.
+     */
+    asset?: string;
 }
 /**
  * Create an API client with x402 payment interceptor.
@@ -64,9 +71,13 @@ export type ProbeResultPaymentRequired = {
     type: 'payment_required';
     amount: string;
     asset: string;
+    /** Display symbol for `asset` (e.g. "USDCx"), when derivable. */
+    symbol?: string;
     recipient: string;
     network: string;
     endpoint: string;
+    /** Every asset the endpoint accepts, so the caller can pick another. */
+    accepts?: PaymentOptionSummary[];
     resource?: {
         url: string;
         description?: string;
@@ -76,18 +87,70 @@ export type ProbeResultPaymentRequired = {
 };
 export type ProbeResult = ProbeResultFree | ProbeResultPaymentRequired;
 /**
- * Detect token type from asset identifier
+ * Token rails this client can actually build and sign a payment for.
+ * Anything else is `unsupported` — see detectTokenType.
+ */
+export type PaymentTokenType = 'STX' | 'sBTC' | 'unsupported';
+/**
+ * Detect token type from asset identifier.
+ *
+ * STX must be identified POSITIVELY, never as a fallback. This function used
+ * to return 'STX' for any unrecognized asset, which meant a USDCx-denominated
+ * 402 (asset `SP120...usdcx`, amount `29000000`) was routed to the interceptor's
+ * native-STX branch and signed as a 29 STX transfer — real funds, wrong asset,
+ * and the endpoint never credits it. Unknown assets are now `unsupported` so
+ * the payment is refused instead of silently mis-sent (#613).
+ *
  * @param asset - Full contract identifier or token name
- * @returns 'STX' for native STX, 'sBTC' for sBTC token
  */
-export declare function detectTokenType(asset: string): 'STX' | 'sBTC';
+export declare function detectTokenType(asset: string): PaymentTokenType;
 /**
- * Format payment amount into human-readable string with token symbol
- * @param amount - Raw amount string (microSTX or satoshis)
+ * Best-effort display symbol for an asset. Servers advertise a friendly name in
+ * `extra.tokenType` (arc0btc sends "USDCx"); otherwise fall back to the contract
+ * name, then the raw identifier.
+ */
+export declare function resolveAssetSymbol(asset: string, extra?: Record<string, unknown>): string;
+/**
+ * Format payment amount into human-readable string with token symbol.
+ *
+ * Only STX and sBTC have known decimal scales here. For any other asset the
+ * amount is rendered in raw base units with an explicit marker rather than
+ * being run through the STX formatter — dividing a USDCx amount by 1e6 and
+ * labelling it "STX" is how `29000000` USDCx base units got reported as
+ * "29 STX" (#613).
+ *
+ * @param amount - Raw amount string (microSTX, satoshis, or token base units)
  * @param asset - Token asset identifier
- * @returns Formatted string like "0.000001 sBTC" or "0.001 STX"
+ * @param extra - Scheme-specific `extra` block from the accepts[] entry
+ * @returns Formatted string like "0.000001 sBTC", "0.001 STX", or "29000000 USDCx (base units)"
  */
-export declare function formatPaymentAmount(amount: string, asset: string): string;
+export declare function formatPaymentAmount(amount: string, asset: string, extra?: Record<string, unknown>): string;
+/** One payment option, summarised for callers choosing between them. */
+export interface PaymentOptionSummary {
+    asset: string;
+    symbol: string;
+    amount: string;
+    formatted: string;
+    payTo: string;
+    /** False when this client cannot build a transaction for the asset. */
+    payable: boolean;
+}
+export declare function summarizePaymentOptions(accepts: PaymentRequirementsV2[]): PaymentOptionSummary[];
+/**
+ * Choose which entry of `accepts[]` to pay.
+ *
+ * Previously this was hardcoded to the first Stacks-network entry, so on a
+ * multi-asset endpoint the caller got whatever the server happened to list
+ * first — USDCx on arc0btc — with no way to ask for anything else (#613).
+ *
+ * - `preferredAsset` set: that asset or an explicit error naming what IS on
+ *   offer. Never silently substitutes a different asset than the one asked for.
+ * - unset: the first entry this client can actually pay for, in the server's
+ *   own preference order. Deliberately NOT balance-aware — auto-selecting by
+ *   wallet contents would let a manifest reorder change which asset leaves the
+ *   wallet without the caller ever naming it.
+ */
+export declare function selectPaymentOption(accepts: PaymentRequirementsV2[], preferredAsset?: string): PaymentRequirementsV2;
 /**
  * Probe an endpoint without payment interceptor
  * Returns either free response data or payment requirements
@@ -97,6 +160,8 @@ export declare function probeEndpoint(options: {
     url: string;
     params?: Record<string, string>;
     data?: Record<string, unknown>;
+    /** Asset to quote (identifier or symbol). Defaults to the first payable entry. */
+    asset?: string;
 }): Promise<ProbeResult>;
 /**
  * Generate a stable deduplication key for a request

package/dist/services/x402.service.js

@@ -473,12 +473,18 @@ export async function createApiClient(baseUrl, options) {
             if (!paymentRequired || !paymentRequired.accepts || paymentRequired.accepts.length === 0) {
                 return Promise.reject(new Error("Invalid x402 402 response: missing or empty payment-required header"));
             }
-            // Select first Stacks-compatible payment option
-            const selectedOption = paymentRequired.accepts.find((opt) => opt.network?.startsWith("stacks:"));
-            if (!selectedOption) {
-                const networks = paymentRequired.accepts.map((a) => a.network).join(", ");
-                return Promise.reject(new Error(`No compatible Stacks payment option found. Available networks: ${networks}`));
+            // Select the payment option: the caller's requested asset, else the
+            // first entry this client can actually sign for. Throws with the list
+            // of accepted assets rather than falling back to a different one.
+            let selectedOption;
+            try {
+                selectedOption = selectPaymentOption(paymentRequired.accepts, options?.asset);
             }
+            catch (selectionError) {
+                return Promise.reject(selectionError);
+            }
+            // Guaranteed non-'unsupported' by selectPaymentOption, so the branch
+            // below can never route a third-party token into the native-STX path.
             const tokenType = detectTokenType(selectedOption.asset);
             const amount = BigInt(selectedOption.amount);
             const isSbtc = tokenType === "sBTC";
@@ -624,9 +630,16 @@ export async function getAccount() {
     return mnemonicToAccount(mnemonic, NETWORK);
 }
 /**
- * Detect token type from asset identifier
+ * Detect token type from asset identifier.
+ *
+ * STX must be identified POSITIVELY, never as a fallback. This function used
+ * to return 'STX' for any unrecognized asset, which meant a USDCx-denominated
+ * 402 (asset `SP120...usdcx`, amount `29000000`) was routed to the interceptor's
+ * native-STX branch and signed as a 29 STX transfer — real funds, wrong asset,
+ * and the endpoint never credits it. Unknown assets are now `unsupported` so
+ * the payment is refused instead of silently mis-sent (#613).
+ *
  * @param asset - Full contract identifier or token name
- * @returns 'STX' for native STX, 'sBTC' for sBTC token
  */
 export function detectTokenType(asset) {
     const assetLower = asset.trim().toLowerCase();
@@ -636,27 +649,133 @@ export function detectTokenType(asset) {
     if (assetLower === 'sbtc' || assetLower.endsWith('::token-sbtc') || assetLower.endsWith('.sbtc-token')) {
         return 'sBTC';
     }
-    return 'STX';
+    // Native STX: the bare symbol, or a CAIP-19-style native reference
+    // ("stacks:1/native" / ".../slip44:5773") used by some manifests.
+    if (assetLower === 'stx' || /(^|\/)(native|slip44:5773)$/.test(assetLower)) {
+        return 'STX';
+    }
+    return 'unsupported';
+}
+/**
+ * Best-effort display symbol for an asset. Servers advertise a friendly name in
+ * `extra.tokenType` (arc0btc sends "USDCx"); otherwise fall back to the contract
+ * name, then the raw identifier.
+ */
+export function resolveAssetSymbol(asset, extra) {
+    const advertised = extra?.tokenType;
+    if (typeof advertised === 'string' && advertised.trim()) {
+        return advertised.trim();
+    }
+    const tokenType = detectTokenType(asset);
+    if (tokenType !== 'unsupported') {
+        return tokenType;
+    }
+    // "SP120....usdcx" -> "usdcx"; strip any "::asset-name" suffix first.
+    const withoutAssetName = asset.split('::')[0];
+    const contractName = withoutAssetName.split('.')[1];
+    return contractName || asset;
 }
 /**
- * Format payment amount into human-readable string with token symbol
- * @param amount - Raw amount string (microSTX or satoshis)
+ * Format payment amount into human-readable string with token symbol.
+ *
+ * Only STX and sBTC have known decimal scales here. For any other asset the
+ * amount is rendered in raw base units with an explicit marker rather than
+ * being run through the STX formatter — dividing a USDCx amount by 1e6 and
+ * labelling it "STX" is how `29000000` USDCx base units got reported as
+ * "29 STX" (#613).
+ *
+ * @param amount - Raw amount string (microSTX, satoshis, or token base units)
  * @param asset - Token asset identifier
- * @returns Formatted string like "0.000001 sBTC" or "0.001 STX"
+ * @param extra - Scheme-specific `extra` block from the accepts[] entry
+ * @returns Formatted string like "0.000001 sBTC", "0.001 STX", or "29000000 USDCx (base units)"
  */
-export function formatPaymentAmount(amount, asset) {
+export function formatPaymentAmount(amount, asset, extra) {
     const tokenType = detectTokenType(asset);
     if (tokenType === 'sBTC') {
         return formatSbtc(amount);
     }
+    if (tokenType === 'unsupported') {
+        // Decimals are unknown, so do not invent a scaled figure.
+        return `${amount} ${resolveAssetSymbol(asset, extra)} (base units)`;
+    }
     return formatStx(amount);
 }
+/**
+ * Does `requested` name this accepts[] entry? Matches on the full asset
+ * identifier or on the display symbol, both case-insensitively, so callers can
+ * say "sBTC", "usdcx", or the full "SM3V....sbtc-token".
+ */
+function assetMatches(option, requested) {
+    const want = requested.trim().toLowerCase();
+    if (!want)
+        return false;
+    if (option.asset.trim().toLowerCase() === want)
+        return true;
+    if (resolveAssetSymbol(option.asset, option.extra).toLowerCase() === want)
+        return true;
+    // "sbtc" should also match the full sbtc-token contract id, and "stx" the
+    // native entry, without the caller needing the exact string.
+    const tokenType = detectTokenType(option.asset);
+    return tokenType !== 'unsupported' && tokenType.toLowerCase() === want;
+}
+export function summarizePaymentOptions(accepts) {
+    return accepts.map((opt) => ({
+        asset: opt.asset,
+        symbol: resolveAssetSymbol(opt.asset, opt.extra),
+        amount: opt.amount,
+        formatted: formatPaymentAmount(opt.amount, opt.asset, opt.extra),
+        payTo: opt.payTo,
+        payable: detectTokenType(opt.asset) !== 'unsupported',
+    }));
+}
+/**
+ * Choose which entry of `accepts[]` to pay.
+ *
+ * Previously this was hardcoded to the first Stacks-network entry, so on a
+ * multi-asset endpoint the caller got whatever the server happened to list
+ * first — USDCx on arc0btc — with no way to ask for anything else (#613).
+ *
+ * - `preferredAsset` set: that asset or an explicit error naming what IS on
+ *   offer. Never silently substitutes a different asset than the one asked for.
+ * - unset: the first entry this client can actually pay for, in the server's
+ *   own preference order. Deliberately NOT balance-aware — auto-selecting by
+ *   wallet contents would let a manifest reorder change which asset leaves the
+ *   wallet without the caller ever naming it.
+ */
+export function selectPaymentOption(accepts, preferredAsset) {
+    const stacksOptions = accepts.filter((opt) => opt.network?.startsWith('stacks:'));
+    if (stacksOptions.length === 0) {
+        const networks = accepts.map((a) => a.network).join(', ') || 'none';
+        throw new Error(`No compatible Stacks payment option found. Available networks: ${networks}`);
+    }
+    const describe = (opts) => opts
+        .map((o) => `${resolveAssetSymbol(o.asset, o.extra)} (${o.asset})`)
+        .join(', ');
+    if (preferredAsset) {
+        const match = stacksOptions.find((opt) => assetMatches(opt, preferredAsset));
+        if (!match) {
+            throw new Error(`Endpoint does not accept "${preferredAsset}". Accepted assets: ${describe(stacksOptions)}.`);
+        }
+        if (detectTokenType(match.asset) === 'unsupported') {
+            throw new Error(`Payment in ${resolveAssetSymbol(match.asset, match.extra)} (${match.asset}) is not supported — ` +
+                `this client can only sign STX and sBTC payments. ` +
+                `Accepted assets: ${describe(stacksOptions)}.`);
+        }
+        return match;
+    }
+    const payable = stacksOptions.find((opt) => detectTokenType(opt.asset) !== 'unsupported');
+    if (!payable) {
+        throw new Error(`No payable asset offered: this client can only sign STX and sBTC payments, ` +
+            `but the endpoint accepts ${describe(stacksOptions)}.`);
+    }
+    return payable;
+}
 /**
  * Probe an endpoint without payment interceptor
  * Returns either free response data or payment requirements
  */
 export async function probeEndpoint(options) {
-    const { method, url, params, data } = options;
+    const { method, url, params, data, asset: preferredAsset } = options;
     const axiosInstance = createBaseAxiosInstance();
     try {
         const response = await axiosInstance.request({ method, url, params, data });
@@ -675,18 +794,22 @@ export async function probeEndpoint(options) {
             const paymentRequired = decodePaymentRequired(headerValue);
             // If v2 header is successfully parsed, use it
             if (paymentRequired?.accepts?.length) {
-                const acceptedPayment = paymentRequired.accepts[0];
+                // Pick the requested asset, or the first one we can actually pay —
+                // NOT blindly accepts[0], which quoted USDCx to sBTC-only wallets (#613).
+                const acceptedPayment = selectPaymentOption(paymentRequired.accepts, preferredAsset);
                 // Convert CAIP-2 network identifier to human-readable format
                 const network = getNetworkFromStacksChainId(acceptedPayment.network) ?? NETWORK;
                 return {
                     type: 'payment_required',
                     amount: acceptedPayment.amount,
                     asset: acceptedPayment.asset,
+                    symbol: resolveAssetSymbol(acceptedPayment.asset, acceptedPayment.extra),
                     recipient: acceptedPayment.payTo,
                     network,
                     endpoint: url,
                     resource: paymentRequired.resource,
                     maxTimeoutSeconds: acceptedPayment.maxTimeoutSeconds,
+                    accepts: summarizePaymentOptions(paymentRequired.accepts),
                 };
             }
             // Fall back to v1 body parsing
@@ -750,6 +873,11 @@ export function recordTransaction(key, txid) {
 export async function checkSufficientBalance(account, amount, asset, sponsored = false) {
     const tokenType = detectTokenType(asset);
     const requiredAmount = BigInt(amount);
+    if (tokenType === 'unsupported') {
+        // No balance rail for third-party tokens. Refuse rather than falling
+        // through to the STX check, which would validate the wrong asset (#613).
+        throw new Error(`Cannot validate balance for asset ${asset}: this client only supports STX and sBTC payments.`);
+    }
     if (tokenType === 'sBTC') {
         const sbtcService = getSbtcService(account.network);
         const balanceInfo = await sbtcService.getBalance(account.address);

package/dist/tools/bounty-hint.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Bounty hint injector.
+ *
+ * Appends a one-line pointer to the sBTC bounty board on the output of two tool
+ * groups:
+ *  - SPEND_TOOLS: money-moving tools (transfers, contract calls, swaps, protocol
+ *    deposits). When an agent has just moved value, remind it the board pays sBTC.
+ *  - ONBOARDING_TOOLS: identity registration and wallet creation/import. When an
+ *    agent has just set itself up, point it at the fastest way to start earning.
+ *
+ * Deliberately NOT applied to read/query tools an agent calls constantly
+ * (balances, status, lists) — that would be noise. Only these two groups get it.
+ *
+ * The hint is a separate text content block, static (no network call), and only
+ * added to successful results — never to errors, and never touching the tool's
+ * own JSON payload.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Tools that move or spend value. A hint is appended to their successful output.
+ */
+export declare const SPEND_TOOLS: ReadonlySet<string>;
+/**
+ * Onboarding tools. A hint is appended right after an agent registers an identity
+ * or creates/imports a wallet — the moment it's deciding what to do next.
+ */
+export declare const ONBOARDING_TOOLS: ReadonlySet<string>;
+/**
+ * Monkey-patch `server.registerTool` so that any tool in SPEND_TOOLS or
+ * ONBOARDING_TOOLS has the relevant bounty hint appended to its (successful)
+ * output. Must be called BEFORE registering the tools. No-op for every other tool.
+ *
+ * Returns a cleanup function that restores the original method, mirroring
+ * `withSkillMeta` in tools/index.ts — call it once registration is done.
+ */
+export declare function installBountyHint(server: McpServer): () => void;
+//# sourceMappingURL=bounty-hint.d.ts.map

package/dist/tools/bounty-hint.js

@@ -0,0 +1,121 @@
+/**
+ * Tools that move or spend value. A hint is appended to their successful output.
+ */
+export const SPEND_TOOLS = new Set([
+    // Core transfers / contract / swap chokepoints
+    "transfer_stx",
+    "transfer_btc",
+    "transfer_token",
+    "transfer_nft",
+    "transfer_rune",
+    "sbtc_transfer",
+    "call_contract",
+    "deploy_contract",
+    "bitflow_swap",
+    "alex_swap",
+    "lightning_pay_invoice",
+    // Stacking / PoX
+    "stack_stx",
+    "extend_stacking",
+    "dual_stacking_enroll",
+    // Zest lending
+    "zest_supply",
+    "zest_borrow",
+    "zest_repay",
+    // Pillar smart wallet (browser-handoff)
+    "pillar_supply",
+    "pillar_boost",
+    "pillar_unwind",
+    "pillar_send",
+    "pillar_fund",
+    "pillar_auto_compound",
+    // Pillar smart wallet (agent-signed direct)
+    "pillar_direct_supply",
+    "pillar_direct_boost",
+    "pillar_direct_unwind",
+    "pillar_direct_send",
+    "pillar_direct_stack_stx",
+    // JingSwap batch auction
+    "jingswap_deposit_stx",
+    "jingswap_deposit_sbtc",
+    // Styx BTC→sBTC
+    "styx_deposit",
+    // StackSpot lottery
+    "stackspot_join_pot",
+    "stackspot_start_pot",
+    // sBTC peg
+    "sbtc_deposit",
+    "sbtc_withdraw",
+    "sbtc_initiate_withdrawal",
+    // Inbox (direct sBTC send)
+    "send_inbox_message_direct",
+]);
+/**
+ * Onboarding tools. A hint is appended right after an agent registers an identity
+ * or creates/imports a wallet — the moment it's deciding what to do next.
+ */
+export const ONBOARDING_TOOLS = new Set([
+    "identity_register",
+    "wallet_create",
+    "wallet_import",
+]);
+const SPEND_HINT = "💰 Tip: the AIBTC bounty board pays sBTC for completed tasks — " +
+    "call bounty_list to see open bounties you could earn from.";
+const ONBOARDING_HINT = "💰 You're set up. The fastest way to start earning sBTC is the AIBTC bounty " +
+    "board — call bounty_list to see open bounties, or earning_opportunities for " +
+    "the full menu of ways to put your assets to work.";
+/** Resolve the hint text for a tool, or null if the tool gets no hint. */
+function hintFor(name) {
+    if (SPEND_TOOLS.has(name))
+        return SPEND_HINT;
+    if (ONBOARDING_TOOLS.has(name))
+        return ONBOARDING_HINT;
+    return null;
+}
+function appendHint(result, hint) {
+    // Never annotate an error result — the agent should see the failure cleanly.
+    if (!result || result.isError)
+        return result;
+    const content = Array.isArray(result.content) ? result.content : [];
+    return {
+        ...result,
+        content: [...content, { type: "text", text: hint }],
+    };
+}
+/**
+ * Monkey-patch `server.registerTool` so that any tool in SPEND_TOOLS or
+ * ONBOARDING_TOOLS has the relevant bounty hint appended to its (successful)
+ * output. Must be called BEFORE registering the tools. No-op for every other tool.
+ *
+ * Returns a cleanup function that restores the original method, mirroring
+ * `withSkillMeta` in tools/index.ts — call it once registration is done.
+ */
+export function installBountyHint(server) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const original = server.registerTool;
+    const hasOwn = Object.prototype.hasOwnProperty.call(server, "registerTool");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    server.registerTool = function (name, config, cb) {
+        const hint = hintFor(name);
+        if (!hint) {
+            return original.call(server, name, config, cb);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const wrapped = async (...args) => {
+            const result = await cb(...args);
+            return appendHint(result, hint);
+        };
+        return original.call(server, name, config, wrapped);
+    };
+    return () => {
+        if (hasOwn) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            server.registerTool = original;
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            delete server.registerTool;
+        }
+    };
+}
+//# sourceMappingURL=bounty-hint.js.map

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

@@ -11,9 +11,63 @@ import { createJsonResponse, createErrorResponse } from "../utils/index.js";
 const DUAL_STACKING_ADDRESS = "SP1HFCRKEJ8BYW4D0E3FAWHFDX8A25PPAA83HWWZ9";
 const DUAL_STACKING_CONTRACT = "dual-stacking-v2_0_4";
 const DUAL_STACKING_CONTRACT_ID = `${DUAL_STACKING_ADDRESS}.${DUAL_STACKING_CONTRACT}`;
+/** APR fields are fixed-point, scaled by 1e6 (500000 => 0.5%). */
+const APR_DIVISOR = 1_000_000;
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+/**
+ * Unwrap a `cvToJSON` tuple into its field map.
+ *
+ * cvToJSON renders a tuple as `{ type: "(tuple ...)", value: { FIELD: { type, value } } }`
+ * — the fields sit one level down under `.value`, keyed by their on-wire Clarity
+ * name. Reading them off the top-level object silently yields `undefined` for
+ * every field, which is how #611 turned real APR/cycle data into zeros.
+ */
+function tupleFields(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const inner = raw.value;
+    if (!inner || typeof inner !== "object")
+        return null;
+    return inner;
+}
+/**
+ * Read a uint field out of a tuple field map. Returns null and records the key
+ * in `missing` when absent or non-numeric, so a decode miss surfaces as a
+ * warning instead of a plausible-looking zero.
+ */
+function tupleUint(fields, key, missing) {
+    const raw = fields?.[key]?.value;
+    if (raw === undefined || raw === null) {
+        missing.push(key);
+        return null;
+    }
+    const num = Number(raw);
+    if (!Number.isFinite(num)) {
+        missing.push(key);
+        return null;
+    }
+    return num;
+}
+/**
+ * Unwrap a `cvToJSON` optional. `(some u123)` renders as
+ * `{ type: "(optional uint)", value: { type: "uint", value: "123" } }` and
+ * `none` as a null/undefined `.value`, so the payload needs one extra hop.
+ */
+function optionalUint(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const inner = raw.value;
+    if (inner === undefined || inner === null)
+        return null;
+    // `some` wraps the payload in another {type, value} envelope.
+    const scalar = typeof inner === "object" ? inner.value : inner;
+    if (scalar === undefined || scalar === null)
+        return null;
+    const num = Number(scalar);
+    return Number.isFinite(num) ? num : null;
+}
 /**
  * Call a read-only function on the dual-stacking contract and return a JSON-friendly value.
  */
@@ -91,41 +145,53 @@ Note: Dual Stacking is only available on mainnet.`,
                 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,
-                maxApr: 0,
-                unit: "%",
-                note: "Multiplier up to 10x with stacked STX",
-            };
-            if (aprDataRaw && typeof aprDataRaw === "object") {
-                const aprObj = aprDataRaw;
-                const minAprRaw = aprObj["min-apr"]?.value;
-                const maxAprRaw = aprObj["max-apr"]?.value;
+            // Parse APR data — tuple {MAX_APR: uint, MIN_APR: uint, MULTIPLIER: uint}.
+            // Keys are the uppercase on-wire Clarity names, not the camelCase output
+            // names. A field that fails to decode stays null and is named in
+            // `warnings` — a zero here reads as "0% APR, don't enroll" (#611).
+            let apr = null;
+            if (aprDataRaw) {
+                const missing = [];
+                const fields = tupleFields(aprDataRaw);
+                const minApr = tupleUint(fields, "MIN_APR", missing);
+                const maxApr = tupleUint(fields, "MAX_APR", missing);
+                const multiplier = tupleUint(fields, "MULTIPLIER", missing);
+                if (missing.length > 0) {
+                    warnings.push(`get-apr-data: could not decode tuple field(s): ${missing.join(", ")}`);
+                }
                 apr = {
-                    minApr: minAprRaw !== undefined ? Number(minAprRaw) / 1_000_000 : 0,
-                    maxApr: maxAprRaw !== undefined ? Number(maxAprRaw) / 1_000_000 : 0,
+                    minApr: minApr === null ? null : minApr / APR_DIVISOR,
+                    maxApr: maxApr === null ? null : maxApr / APR_DIVISOR,
+                    multiplier,
                     unit: "%",
-                    note: "Multiplier up to 10x with stacked STX",
+                    note: `Multiplier up to ${multiplier ?? 10}x with stacked STX`,
                 };
             }
-            // Parse cycle overview — returns tuple with cycle-id, snapshot-index, snapshots-per-cycle
-            let cycleOverview = { currentCycleId: 0, snapshotIndex: 0, snapshotsPerCycle: 0 };
-            if (cycleOverviewRaw && typeof cycleOverviewRaw === "object") {
-                const co = cycleOverviewRaw;
+            // Parse cycle overview — tuple {cycle-id, snapshot-index, snapshots-per-cycle}
+            let cycleOverview = null;
+            if (cycleOverviewRaw) {
+                const missing = [];
+                const fields = tupleFields(cycleOverviewRaw);
                 cycleOverview = {
-                    currentCycleId: co["cycle-id"]?.value !== undefined ? Number(co["cycle-id"].value) : 0,
-                    snapshotIndex: co["snapshot-index"]?.value !== undefined ? Number(co["snapshot-index"].value) : 0,
-                    snapshotsPerCycle: co["snapshots-per-cycle"]?.value !== undefined
-                        ? Number(co["snapshots-per-cycle"].value)
-                        : 0,
+                    currentCycleId: tupleUint(fields, "cycle-id", missing),
+                    snapshotIndex: tupleUint(fields, "snapshot-index", missing),
+                    snapshotsPerCycle: tupleUint(fields, "snapshots-per-cycle", missing),
                 };
+                if (missing.length > 0) {
+                    warnings.push(`current-overview-data: could not decode tuple field(s): ${missing.join(", ")}`);
+                }
             }
-            // Parse minimum enrollment amount
-            let minimumEnrollmentSats = 0;
+            // Parse minimum enrollment amount (plain uint — one {type, value} level)
+            let minimumEnrollmentSats = null;
             if (minimumAmountRaw !== null && minimumAmountRaw !== undefined) {
-                const raw = minimumAmountRaw;
-                minimumEnrollmentSats = raw.value !== undefined ? Number(raw.value) : 0;
+                const raw = minimumAmountRaw.value;
+                const num = Number(raw);
+                if (raw === undefined || raw === null || !Number.isFinite(num)) {
+                    warnings.push("get-minimum-enrollment-amount: could not decode uint result");
+                }
+                else {
+                    minimumEnrollmentSats = num;
+                }
             }
             // Parse boolean enrollment flags. A failed read stays null (unknown)
             // rather than collapsing to a misleading `false`.
@@ -192,12 +258,10 @@ Note: Dual Stacking is only available on mainnet.`,
                 uintCV(BigInt(rollbackValue)),
                 principalCV(resolvedAddress),
             ]);
-            let rewardSats = 0;
-            if (rewardRaw !== null && rewardRaw !== undefined) {
-                const raw = rewardRaw;
-                rewardSats = raw.value !== undefined ? Number(raw.value) : 0;
-            }
-            const rewardBtc = rewardSats / 100_000_000;
+            // Contract returns `(optional uint)` — `none` means no reward recorded
+            // for this cycle/address, which is distinct from a zero reward.
+            const rewardSats = optionalUint(rewardRaw);
+            const rewardBtc = rewardSats === null ? null : rewardSats / 100_000_000;
             return createJsonResponse({
                 address: resolvedAddress,
                 cycle,

package/dist/tools/endpoint.tools.js

@@ -60,6 +60,9 @@ function buildCallWith(options) {
         callWith.params = options.params;
     if (options.data && Object.keys(options.data).length > 0)
         callWith.data = options.data;
+    // Echo the asset so executing the quote pays in the asset that was quoted.
+    if (options.asset)
+        callWith.asset = options.asset;
     return callWith;
 }
 /**
@@ -98,18 +101,29 @@ function formatProbeResponse(result, method, fullUrl, callWithOptions, messagePr
             response: result.data,
         });
     }
+    // Derive the message from the same asset the machine-readable block reports.
+    // These used to disagree — the text said "29 STX" while payment.asset was
+    // USDCx — because the formatter treated every unknown token as STX (#613).
     const formattedCost = formatPaymentAmount(result.amount, result.asset);
     const prefix = messagePrefix ?? 'No payment made. ';
+    const alternatives = (result.accepts ?? []).filter((o) => o.asset !== result.asset);
+    const altNote = alternatives.length > 0
+        ? ` This endpoint also accepts ${alternatives
+            .map((o) => `${o.formatted}${o.payable ? '' : ' [not payable by this client]'}`)
+            .join(', ')} — pass the \`asset\` parameter to pay with one of those instead.`
+        : '';
     return createJsonResponse({
         type: 'payment_required',
         endpoint: `${method} ${fullUrl}`,
-        message: `${prefix}This endpoint costs ${formattedCost}. To execute and pay, call execute_x402_endpoint with autoApprove: true and the parameters shown in callWith below.`,
+        message: `${prefix}This endpoint costs ${formattedCost}. To execute and pay, call execute_x402_endpoint with autoApprove: true and the parameters shown in callWith below.${altNote}`,
         payment: {
             amount: result.amount,
             asset: result.asset,
+            ...(result.symbol && { symbol: result.symbol }),
             recipient: result.recipient,
             network: result.network,
         },
+        ...(result.accepts && result.accepts.length > 0 && { accepts: result.accepts }),
         callWith: buildCallWith(callWithOptions),
     });
 }
@@ -249,16 +263,20 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
                 .optional()
                 .default(false)
                 .describe("Skip cost probe and execute immediately. When false (default), probes first and returns cost info for paid endpoints. When true, executes atomically like before. Free endpoints always execute transparently."),
+            asset: z
+                .string()
+                .optional()
+                .describe("Which asset to pay with when the endpoint accepts several. Accepts a symbol (\"sBTC\", \"STX\") or a full contract identifier. Defaults to the first asset this client can pay. Only STX and sBTC can be signed; requesting any other asset returns an error listing what is accepted."),
         },
-    }, async ({ method, url, path, apiUrl, params, data, autoApprove }) => {
+    }, async ({ method, url, path, apiUrl, params, data, autoApprove, asset }) => {
         let fullUrl = "";
         try {
             const parsed = parseEndpointUrl({ url, path, apiUrl, params });
             fullUrl = parsed.fullUrl;
             params = parsed.params;
             if (!autoApprove) {
-                const probeResult = await probeEndpoint({ method, url: fullUrl, params, data });
-                return formatProbeResponse(probeResult, method, fullUrl, { method, url, path, apiUrl, params, data });
+                const probeResult = await probeEndpoint({ method, url: fullUrl, params, data, asset });
+                return formatProbeResponse(probeResult, method, fullUrl, { method, url, path, apiUrl, params, data, asset });
             }
             // autoApprove=true: check dedup cache before any network request, then execute
             // with a single request. Balance validation happens inside the onBeforePayment
@@ -275,6 +293,7 @@ For aibtc.com inbox messages, use send_inbox_message_direct instead — it signs
             }
             const api = await createApiClient(parsed.baseUrl, {
                 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).
@@ -444,15 +463,19 @@ Supported sources:
                 .record(z.string(), z.unknown())
                 .optional()
                 .describe("Request body for POST/PUT requests"),
+            asset: z
+                .string()
+                .optional()
+                .describe("Quote the cost in this asset when the endpoint accepts several. Accepts a symbol (\"sBTC\", \"STX\") or a full contract identifier. Defaults to the first asset this client can pay; the full accepts[] list is always returned."),
         },
-    }, async ({ method, url, path, apiUrl, params, data }) => {
+    }, async ({ method, url, path, apiUrl, params, data, asset }) => {
         let fullUrl = "";
         try {
             const parsed = parseEndpointUrl({ url, path, apiUrl, params });
             fullUrl = parsed.fullUrl;
             params = parsed.params;
-            const result = await probeEndpoint({ method, url: fullUrl, params, data });
-            return formatProbeResponse(result, method, fullUrl, { method, url, path, apiUrl, params, data });
+            const result = await probeEndpoint({ method, url: fullUrl, params, data, asset });
+            return formatProbeResponse(result, method, fullUrl, { method, url, path, apiUrl, params, data, asset });
         }
         catch (error) {
             return formatEndpointError(error, fullUrl || "unknown");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.64.1",
+  "version": "1.65.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.64.1 # x-release-please-version
+  version: 1.65.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---