@aibtc/mcp-server 1.70.0 → 1.71.0

package/README.md

@@ -10,12 +10,12 @@ Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg,
 - **Bitcoin L1** - Check balances, send BTC, manage UTXOs via mempool.space
 - **Agent's Own Wallet** - Agents get their own wallet to perform blockchain transactions
 - **Secure Storage** - Wallets encrypted with AES-256-GCM and stored locally
-- **150+ Tools** - Bitcoin L1 + comprehensive Stacks L2 operations
+- **350+ Tools** - Bitcoin L1 + comprehensive Stacks L2 operations
 - **sBTC Support** - Native Bitcoin on Stacks operations
 - **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
 
@@ -276,7 +276,7 @@ Claude: Done! Transaction broadcast: abc123...
 
 Both addresses are derived from the same recovery phrase, making it easy to manage both Layer 1 (Bitcoin) and Layer 2 (Stacks) assets.
 
-## Available Tools (150+ total)
+## Available Tools (350+ total)
 
 ### Wallet Management
 | Tool | Description |
@@ -386,10 +386,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 |
@@ -542,7 +546,7 @@ Or use any SIP-010 token by contract ID: `SP2X...::token-name`
 
 | Environment Variable | Description | Default |
 |---------------------|-------------|---------|
-| `NETWORK` | `mainnet` or `testnet` | `mainnet` (installer) / `testnet` (if unset) |
+| `NETWORK` | `mainnet` or `testnet` | `mainnet` |
 | `API_URL` | Default x402 API base URL | `https://x402.biwas.xyz` |
 | `CLIENT_MNEMONIC` | (Optional) Pre-configured mnemonic | - |
 | `HIRO_API_KEY` | (Optional) Hiro API key for higher rate limits | - |
@@ -550,7 +554,7 @@ Or use any SIP-010 token by contract ID: `SP2X...::token-name`
 | `SPEND_LIMIT_DAILY_USTX` / `SPEND_LIMIT_SESSION_USTX` | STX spend cap per day / per unlock (micro-STX) | `10000000` (10 STX) |
 | `SPEND_LIMIT_DAILY_SATS` / `SPEND_LIMIT_SESSION_SATS` | BTC spend cap per day / per unlock (sats) | `50000` |
 
-**Note on `NETWORK`:** The `--install` command writes `NETWORK=mainnet` by default (pass `--testnet` to use testnet). If you omit `NETWORK` from your config entirely, the runtime fallback is `testnet`. Most users should set this explicitly.
+**Note on `NETWORK`:** The `--install` command writes `NETWORK=mainnet` by default (pass `--testnet` to use testnet). If you omit `NETWORK` from your config entirely, the runtime fallback is also `mainnet`.
 
 **Note on spending limits:** A default-on safety rail meters every outbound spend (`transfer_stx`, `transfer_btc`, x402/L402 auto-payments) against a cumulative per-session and per-day cap, so a single bad instruction or a malicious endpoint can't drain the wallet. A spend over the cap is blocked and reports the remaining budget. Raise the caps via the env vars above, or disable with `SPEND_LIMIT_ENABLED=false`. See [SECURITY.md](SECURITY.md#limit-blast-radius).
 
@@ -627,11 +631,13 @@ The skill is automatically included when you install the MCP server. Find it at:
 skill/
 ├── SKILL.md                        # Bitcoin L1 core workflows
 └── references/
+    ├── at-stake.md                 # El Salvador prediction market & side legions
     ├── genesis-lifecycle.md        # Agent registration & check-in
     ├── inscription-workflow.md     # Bitcoin inscription guide
     ├── pillar-wallet.md            # Pillar smart wallet guide
     ├── stacks-defi.md              # Stacks L2 / DeFi operations
-    └── troubleshooting.md          # Common issues and solutions
+    ├── troubleshooting.md          # Common issues and solutions
+    └── x402-inbox.md               # x402 inbox messaging
 ```
 
 ## Development

package/dist/bridge/index.js

@@ -29,7 +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";
+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,10 +9,10 @@ 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: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx-v2";
+    readonly ALEX_WSTX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2";
     readonly ZEST_MARKET: "SP1A27KFY4XERQCCRCARCYD1CC5N7M6688BSYADJ7.v0-4-market";
     readonly ZEST_DATA: "SP1A27KFY4XERQCCRCARCYD1CC5N7M6688BSYADJ7.protocol-data";
     readonly ZEST_MARKET_VAULT: "SP1A27KFY4XERQCCRCARCYD1CC5N7M6688BSYADJ7.v0-market-vault";
@@ -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,10 +72,10 @@ 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: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx-v2";
+    readonly ALEX_WSTX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2";
     readonly ZEST_MARKET: "SP1A27KFY4XERQCCRCARCYD1CC5N7M6688BSYADJ7.v0-4-market";
     readonly ZEST_DATA: "SP1A27KFY4XERQCCRCARCYD1CC5N7M6688BSYADJ7.protocol-data";
     readonly ZEST_MARKET_VAULT: "SP1A27KFY4XERQCCRCARCYD1CC5N7M6688BSYADJ7.v0-market-vault";
@@ -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";
@@ -118,7 +118,7 @@ export declare const WELL_KNOWN_TOKENS: {
         readonly sBTC: "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token";
         readonly USDCx: "SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx";
         readonly ALEX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex";
-        readonly wSTX: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx-v2";
+        readonly wSTX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2";
     };
     readonly testnet: {
         readonly STX: "native";
@@ -146,7 +146,7 @@ export declare function getWellKnownTokens(network: Network): {
     readonly sBTC: "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token";
     readonly USDCx: "SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx";
     readonly ALEX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex";
-    readonly wSTX: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx-v2";
+    readonly wSTX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2";
 } | {
     readonly STX: "native";
     readonly sBTC: "ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.sbtc-token";

package/dist/config/contracts.js

@@ -12,11 +12,11 @@ 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",
-    ALEX_WSTX: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx-v2",
+    ALEX_WSTX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2",
     // Zest Protocol v2
     ZEST_MARKET: "SP1A27KFY4XERQCCRCARCYD1CC5N7M6688BSYADJ7.v0-4-market",
     ZEST_DATA: "SP1A27KFY4XERQCCRCARCYD1CC5N7M6688BSYADJ7.protocol-data", // read-only helper for v0-4-market positions
@@ -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/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