@aibtc/mcp-server 1.70.1 → 1.72.0

package/README.md

@@ -15,7 +15,7 @@ Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg,
 - **Token Operations** - SIP-010 fungible token transfers and queries
 - **NFT Support** - SIP-009 NFT holdings, transfers, and metadata
 - **DeFi Trading** - ALEX DEX swaps and Zest Protocol lending/borrowing
-- **Stacking/PoX** - Stacking status and delegation
+- **Stacking/PoX-5** - Stake STX with a signer manager, extend, unstake, claim sBTC rewards
 - **BNS Domains** - .btc domain lookups and management (V1 + V2)
 - **x402 Payments** - Automatic payment handling for paid APIs
 
@@ -27,7 +27,9 @@ Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg,
 npx @aibtc/mcp-server@latest --install
 ```
 
-That's it! This automatically configures Claude Code. Restart your terminal and start chatting.
+This configures Claude Code and creates the agent's wallet: it prints the Stacks and Bitcoin addresses, a generated password and the 24-word mnemonic **once**. Write both down. The mnemonic is stored only encrypted (AES-256-GCM) in `~/.aibtc/` on this machine, and the password is not saved anywhere; the agent asks for it to unlock, and you can change it with `wallet_rotate_password`. If a wallet for the network already exists it is kept. The wallet is only created when the install runs in an interactive terminal (never into a pipe or CI log). Pass `--no-wallet` to skip it and create or import one from the agent instead.
+
+Restart your terminal, send a little STX to the printed address, and ask the agent to unlock the wallet and make a paid inference call.
 
 ### Claude Desktop (App)
 
@@ -114,6 +116,37 @@ npx @aibtc/mcp-server@latest --install --cursor --testnet   # Cursor, testnet
 
 > **Why npx?** Using `npx @aibtc/mcp-server@latest` ensures you always get the newest version automatically. Global installs (`npm install -g`) won't auto-update.
 
+### Tool Profiles
+
+Every tool definition is loaded into the model's context, so `--install` writes `AIBTC_TOOLS=core`: a lean core of 25 tools: wallet (including `wallet_rotate_password`), balances, STX/BTC/sBTC transfers, x402 (`list_x402_endpoints`, `probe_x402_endpoint`, `execute_x402_endpoint`) and earning (`earning_opportunities`, `bounty_list/get/submit`, `identity_register`).
+
+Add groups with `AIBTC_TOOLS=core,defi,ordinals` in the server's `env` (the core is always included), or load everything with `AIBTC_TOOLS=all` / `--profile full`. If `AIBTC_TOOLS` is not set at all, every tool is loaded, so configs written by earlier versions keep all their tools:
+
+```bash
+npx @aibtc/mcp-server@latest --install --profile full   # writes AIBTC_TOOLS=all
+```
+
+| Group | Tools |
+|-------|-------|
+| `wallet` | Wallet management extras, encrypted credential store |
+| `stacks` | Stacks transactions, contracts, tokens, NFTs, chain queries, nonce tools |
+| `sbtc` | sBTC deposit/withdraw, Styx BTC→sBTC |
+| `bitcoin` | Bitcoin L1 UTXOs, mempool watch |
+| `lightning` | Lightning (Spark) wallet and L402 payments |
+| `stacking` | PoX stacking, dual stacking, StackSpot |
+| `defi` | ALEX, Zest, Bitflow, Jingswap, yield hunter/dashboard, Tenero analytics |
+| `pillar` | Pillar smart wallet |
+| `ordinals` | Inscriptions, runes, PSBT, ordinals marketplace/P2P, taproot multisig |
+| `bns` | BNS names |
+| `identity` | ERC-8004 identity and reputation, message signing |
+| `social` | Nostr, AIBTC inbox |
+| `earn` | Bounty board (create, accept, pay, my views) |
+| `legion` | AIBTC News Legion |
+| `markets` | Stacks prediction market, At Stake |
+| `dev` | Scaffolding, OpenRouter, settings, inference marketplace, arXiv |
+
+The server's instructions list the groups that are off, so the agent can tell you which one to enable. The OpenRouter `bridge` starts from the full set and narrows it with its own `--read-only`/`--allow`/`--block` flags.
+
 ### Manual Configuration
 
 If you prefer to configure manually, add the following to your client's config file. The `-y` flag stops npx from prompting for confirmation.
@@ -181,7 +214,7 @@ NETWORK = "mainnet"
 
 ## Giving Claude a Wallet
 
-When you first use @aibtc/mcp-server, Claude doesn't have a wallet. Here's the smooth onboarding flow:
+`--install` creates a wallet for you (see [Quick Start](#quick-start)). If you installed with `--no-wallet`, configured the client by hand, or want another wallet, the agent can create or import one:
 
 ### Example Conversation
 
@@ -386,10 +419,14 @@ Both addresses are derived from the same recovery phrase, making it easy to mana
 ### Stacking / PoX
 | Tool | Description |
 |------|-------------|
-| `get_pox_info` | Get current PoX cycle info |
-| `get_stacking_status` | Check stacking status |
-| `stack_stx` | Lock STX for stacking |
-| `extend_stacking` | Extend stacking period |
+| `get_pox_info` | Current PoX-5 cycle, burn height, prepare phase |
+| `get_stacking_status` | Locked amount, signer manager, unlock height |
+| `list_stacking_signers` | Signer managers in the next cycle's signer set |
+| `stack_stx` | Lock STX with a signer manager |
+| `extend_stacking` | Extend, increase, switch signer or payout (stake-update) |
+| `unstake_stx` | Stop early; unlocks next cycle |
+| `get_stacking_rewards` | Unclaimed sBTC rewards for a cycle |
+| `claim_stacking_rewards` | Claim a cycle's rewards through the signer manager |
 
 ### BNS Domains (V1 + V2)
 | Tool | Description |
@@ -543,7 +580,7 @@ Or use any SIP-010 token by contract ID: `SP2X...::token-name`
 | Environment Variable | Description | Default |
 |---------------------|-------------|---------|
 | `NETWORK` | `mainnet` or `testnet` | `mainnet` |
-| `API_URL` | Default x402 API base URL | `https://x402.biwas.xyz` |
+| `AIBTC_TOOLS` | `core`, `core,<group,...>`, or `all` (see [Tool Profiles](#tool-profiles)). `--install` writes `core` | all tools when unset |
 | `CLIENT_MNEMONIC` | (Optional) Pre-configured mnemonic | - |
 | `HIRO_API_KEY` | (Optional) Hiro API key for higher rate limits | - |
 | `SPEND_LIMIT_ENABLED` | Set `false` to disable the wallet spending limit | `true` |

package/dist/bridge/index.js

@@ -27,9 +27,9 @@
  *   --network <net>        mainnet|testnet for the spawned server (default mainnet)
  *   --max-turns <n>        tool-call loop cap (default 10)
  */
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { ALL_ENDPOINTS } from "../endpoints/registry.js";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { Client } from "@modelcontextprotocol/client";
+import { STATIC_ENDPOINTS } from "../endpoints/registry.js";
 const OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions";
 const DEFAULT_MODEL = "anthropic/claude-3.5-haiku";
 /**
@@ -154,7 +154,7 @@ function printSafetyReceipt(opts, exposed, 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}`,
+        `  x402_static_endpoints=${STATIC_ENDPOINTS.length}`,
         "  (reports configured execution boundaries only; no value has moved)",
     ];
     console.error(lines.join("\n"));

package/dist/config/contracts.d.ts

@@ -9,7 +9,7 @@ export declare const MAINNET_CONTRACTS: {
     readonly SBTC_WITHDRAWAL: "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-withdrawal";
     readonly USDCX: "SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx";
     readonly BNS: "SP000000000000000000002Q6VF78.bns";
-    readonly POX_4: "SP000000000000000000002Q6VF78.pox-4";
+    readonly POX_5: "SP000000000000000000002Q6VF78.pox-5";
     readonly ALEX_AMM_POOL: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1";
     readonly ALEX_TOKEN: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex";
     readonly ALEX_WSTX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2";
@@ -57,7 +57,7 @@ export declare const TESTNET_CONTRACTS: {
     readonly SBTC_WITHDRAWAL: "ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.sbtc-withdrawal";
     readonly USDCX: "ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.usdcx";
     readonly BNS: "ST000000000000000000002AMW42H.bns";
-    readonly POX_4: "ST000000000000000000002AMW42H.pox-4";
+    readonly POX_5: "ST000000000000000000002AMW42H.pox-5";
     readonly IDENTITY_REGISTRY: "ST3YT0XW92E6T2FE59B2G5N2WNNFSBZ6MZKQS5D18.identity-registry-v2";
     readonly REPUTATION_REGISTRY: "ST3YT0XW92E6T2FE59B2G5N2WNNFSBZ6MZKQS5D18.reputation-registry-v2";
     readonly VALIDATION_REGISTRY: "ST3YT0XW92E6T2FE59B2G5N2WNNFSBZ6MZKQS5D18.validation-registry-v2";
@@ -72,7 +72,7 @@ export declare function getContracts(network: Network): {
     readonly SBTC_WITHDRAWAL: "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-withdrawal";
     readonly USDCX: "SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx";
     readonly BNS: "SP000000000000000000002Q6VF78.bns";
-    readonly POX_4: "SP000000000000000000002Q6VF78.pox-4";
+    readonly POX_5: "SP000000000000000000002Q6VF78.pox-5";
     readonly ALEX_AMM_POOL: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1";
     readonly ALEX_TOKEN: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex";
     readonly ALEX_WSTX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2";
@@ -96,7 +96,7 @@ export declare function getContracts(network: Network): {
     readonly SBTC_WITHDRAWAL: "ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.sbtc-withdrawal";
     readonly USDCX: "ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.usdcx";
     readonly BNS: "ST000000000000000000002AMW42H.bns";
-    readonly POX_4: "ST000000000000000000002AMW42H.pox-4";
+    readonly POX_5: "ST000000000000000000002AMW42H.pox-5";
     readonly IDENTITY_REGISTRY: "ST3YT0XW92E6T2FE59B2G5N2WNNFSBZ6MZKQS5D18.identity-registry-v2";
     readonly REPUTATION_REGISTRY: "ST3YT0XW92E6T2FE59B2G5N2WNNFSBZ6MZKQS5D18.reputation-registry-v2";
     readonly VALIDATION_REGISTRY: "ST3YT0XW92E6T2FE59B2G5N2WNNFSBZ6MZKQS5D18.validation-registry-v2";

package/dist/config/contracts.js

@@ -12,7 +12,7 @@ export const MAINNET_CONTRACTS = {
     // BNS
     BNS: "SP000000000000000000002Q6VF78.bns",
     // Stacking
-    POX_4: "SP000000000000000000002Q6VF78.pox-4",
+    POX_5: "SP000000000000000000002Q6VF78.pox-5",
     // ALEX DEX (SDK handles most operations, but we need pool contract for queries)
     ALEX_AMM_POOL: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1",
     ALEX_TOKEN: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex",
@@ -112,7 +112,7 @@ export const TESTNET_CONTRACTS = {
     // BNS
     BNS: "ST000000000000000000002AMW42H.bns",
     // Stacking
-    POX_4: "ST000000000000000000002AMW42H.pox-4",
+    POX_5: "ST000000000000000000002AMW42H.pox-5",
     // ERC-8004 Identity & Reputation
     IDENTITY_REGISTRY: "ST3YT0XW92E6T2FE59B2G5N2WNNFSBZ6MZKQS5D18.identity-registry-v2",
     REPUTATION_REGISTRY: "ST3YT0XW92E6T2FE59B2G5N2WNNFSBZ6MZKQS5D18.reputation-registry-v2",

package/dist/config/networks.js

@@ -1,5 +1,8 @@
 export const NETWORK = process.env.NETWORK === "testnet" ? "testnet" : "mainnet";
-export const API_URL = process.env.API_URL || "https://x402.biwas.xyz";
+// Base URL for bare-path x402 calls. Fixed per network, not read from the
+// environment: the server loads the .env of whatever directory the client
+// starts it in, and a project's generic API_URL must not redirect payments.
+export const API_URL = NETWORK === "mainnet" ? "https://x402.aibtc.com" : "https://x402.aibtc.dev";
 export function getStacksNetwork(network) {
     return network === "mainnet" ? "mainnet" : "testnet";
 }

package/dist/endpoints/registry.d.ts

@@ -1,41 +1,23 @@
 /**
- * Known x402 endpoints registry
- * Endpoints from x402.biwas.xyz, x402.aibtc.com, stx402.com, and aibtc.com
+ * Static x402 endpoint entries for hosts that do not publish an OpenAPI spec.
+ *
+ * x402.aibtc.com and stx402.com publish `openapi.json`, so their endpoints are
+ * discovered live (see services/x402-discovery.service.ts) instead of listed here.
  */
-export type X402Source = "x402.biwas.xyz" | "x402.aibtc.com" | "stx402.com" | "aibtc.com";
+export type StaticX402Source = "x402.biwas.xyz" | "aibtc.com";
 export interface X402Endpoint {
     path: string;
     method: "GET" | "POST" | "PUT" | "DELETE";
     description: string;
     cost: string;
     category: string;
-    source: X402Source;
+    source: string;
     params?: Record<string, string>;
     body?: Record<string, string>;
 }
-export declare const ALL_ENDPOINTS: X402Endpoint[];
-/**
- * Search endpoints by keyword
- */
-export declare function searchEndpoints(query: string): X402Endpoint[];
-/**
- * Get endpoints by source
- */
-export declare function getEndpointsBySource(source: X402Source): X402Endpoint[];
+export declare const STATIC_ENDPOINTS: X402Endpoint[];
 /**
- * Format endpoints for display
+ * Format endpoints for display, grouped by category and source.
  */
 export declare function formatEndpointsTable(endpoints: X402Endpoint[]): string;
-/**
- * Get all unique categories
- */
-export declare function getCategories(): string[];
-/**
- * Lookup an endpoint in the registry by method, path, and source URL.
- * Used to determine if an endpoint is known-FREE or known-PAID before
- * deciding whether to use a payment-capable client.
- *
- * Supports path patterns with placeholders like {address}, {messageId}, etc.
- */
-export declare function lookupEndpoint(method: string, path: string, sourceUrl: string): X402Endpoint | undefined;
 //# sourceMappingURL=registry.d.ts.map