@aibtc/mcp-server 1.4.0 → 1.6.0

package/README.md

@@ -98,6 +98,34 @@ Claude's wallets are stored locally on your machine:
 - Mnemonics never stored in plaintext
 - File permissions set to owner-only (0600)
 
+## Bitcoin Address Derivation
+
+Each wallet automatically derives both a **Stacks address** and a **Bitcoin address** from the same mnemonic using BIP39/BIP32 standards.
+
+**Derivation Paths (BIP84):**
+- Mainnet: `m/84'/0'/0'/0/0` (Bitcoin coin type 0)
+- Testnet: `m/84'/1'/0'/0/0` (Bitcoin testnet coin type 1)
+
+**Address Format:**
+- Mainnet: `bc1q...` (Native SegWit P2WPKH)
+- Testnet: `tb1q...` (Native SegWit P2WPKH)
+
+**Current Support:**
+- Read-only Bitcoin address derivation
+- Same mnemonic produces both Stacks and Bitcoin addresses
+- Bitcoin address included in wallet status and info
+- No Bitcoin signing or transaction support (yet)
+
+**Example:**
+```
+You: Create a wallet called "my-wallet"
+Claude: I've created a wallet with:
+        Stacks address: ST1ABC...
+        Bitcoin address: bc1q...
+```
+
+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 (50+ total)
 
 ### Wallet Management
@@ -111,13 +139,13 @@ Claude's wallets are stored locally on your machine:
 | `wallet_switch` | Switch Claude to a different wallet |
 | `wallet_delete` | Delete a wallet |
 | `wallet_export` | Export wallet mnemonic |
-| `wallet_status` | Check if Claude's wallet is ready |
+| `wallet_status` | Check if Claude's wallet is ready (includes Stacks and Bitcoin addresses) |
 | `wallet_set_timeout` | Set how long wallet stays unlocked |
 
 ### Wallet & Balance
 | Tool | Description |
 |------|-------------|
-| `get_wallet_info` | Get Claude's wallet address and status |
+| `get_wallet_info` | Get Claude's wallet addresses (Stacks + Bitcoin) and status |
 | `get_stx_balance` | Get STX balance for any address |
 
 ### STX Transfers

package/dist/config/caip.d.ts

@@ -0,0 +1,66 @@
+/**
+ * CAIP-2 Chain Identifiers
+ *
+ * Chain-agnostic identifiers following the CAIP-2 specification:
+ * https://chainagnostic.org/CAIPs/caip-2
+ *
+ * Format: namespace:reference
+ * - Stacks uses "stacks" namespace with chain ID as reference
+ * - Bitcoin uses "bip122" namespace with genesis block hash prefix (32 chars)
+ */
+import type { Network } from "./networks.js";
+/**
+ * CAIP-2 chain identifier type
+ */
+export type ChainId = string;
+/**
+ * Stacks chain IDs
+ * - Mainnet: chain ID 1
+ * - Testnet: chain ID 2147483648 (0x80000000)
+ */
+export declare const STACKS_CHAIN_IDS: {
+    readonly mainnet: "stacks:1";
+    readonly testnet: "stacks:2147483648";
+};
+/**
+ * Bitcoin chain IDs (BIP122 namespace)
+ * Using first 32 characters of genesis block hash as reference
+ * - Mainnet: 000000000019d6689c085ae165831e93
+ * - Testnet: 000000000933ea01ad0ee984209779ba
+ */
+export declare const BITCOIN_CHAIN_IDS: {
+    readonly mainnet: "bip122:000000000019d6689c085ae165831e93";
+    readonly testnet: "bip122:000000000933ea01ad0ee984209779ba";
+};
+/**
+ * Get Stacks CAIP-2 chain ID for a network
+ */
+export declare function getStacksChainId(network: Network): ChainId;
+/**
+ * Get Bitcoin CAIP-2 chain ID for a network
+ */
+export declare function getBitcoinChainId(network: Network): ChainId;
+/**
+ * Parse CAIP-2 chain ID into namespace and reference
+ */
+export declare function parseChainId(chainId: ChainId): {
+    namespace: string;
+    reference: string;
+};
+/**
+ * Check if a chain ID is a Stacks chain
+ */
+export declare function isStacksChainId(chainId: ChainId): boolean;
+/**
+ * Check if a chain ID is a Bitcoin chain
+ */
+export declare function isBitcoinChainId(chainId: ChainId): boolean;
+/**
+ * Get network from Stacks chain ID
+ */
+export declare function getNetworkFromStacksChainId(chainId: ChainId): Network | null;
+/**
+ * Get network from Bitcoin chain ID
+ */
+export declare function getNetworkFromBitcoinChainId(chainId: ChainId): Network | null;
+//# sourceMappingURL=caip.d.ts.map

package/dist/config/caip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caip.d.ts","sourceRoot":"","sources":["../../src/config/caip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;CAGnB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;CAGpB,CAAC;AAEX;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,CAMA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAI5E;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAI7E"}

package/dist/config/caip.js

@@ -0,0 +1,84 @@
+/**
+ * CAIP-2 Chain Identifiers
+ *
+ * Chain-agnostic identifiers following the CAIP-2 specification:
+ * https://chainagnostic.org/CAIPs/caip-2
+ *
+ * Format: namespace:reference
+ * - Stacks uses "stacks" namespace with chain ID as reference
+ * - Bitcoin uses "bip122" namespace with genesis block hash prefix (32 chars)
+ */
+/**
+ * Stacks chain IDs
+ * - Mainnet: chain ID 1
+ * - Testnet: chain ID 2147483648 (0x80000000)
+ */
+export const STACKS_CHAIN_IDS = {
+    mainnet: "stacks:1",
+    testnet: "stacks:2147483648",
+};
+/**
+ * Bitcoin chain IDs (BIP122 namespace)
+ * Using first 32 characters of genesis block hash as reference
+ * - Mainnet: 000000000019d6689c085ae165831e93
+ * - Testnet: 000000000933ea01ad0ee984209779ba
+ */
+export const BITCOIN_CHAIN_IDS = {
+    mainnet: "bip122:000000000019d6689c085ae165831e93",
+    testnet: "bip122:000000000933ea01ad0ee984209779ba",
+};
+/**
+ * Get Stacks CAIP-2 chain ID for a network
+ */
+export function getStacksChainId(network) {
+    return STACKS_CHAIN_IDS[network];
+}
+/**
+ * Get Bitcoin CAIP-2 chain ID for a network
+ */
+export function getBitcoinChainId(network) {
+    return BITCOIN_CHAIN_IDS[network];
+}
+/**
+ * Parse CAIP-2 chain ID into namespace and reference
+ */
+export function parseChainId(chainId) {
+    const [namespace, reference] = chainId.split(":");
+    if (!namespace || !reference) {
+        throw new Error(`Invalid CAIP-2 chain ID: ${chainId}`);
+    }
+    return { namespace, reference };
+}
+/**
+ * Check if a chain ID is a Stacks chain
+ */
+export function isStacksChainId(chainId) {
+    return chainId.startsWith("stacks:");
+}
+/**
+ * Check if a chain ID is a Bitcoin chain
+ */
+export function isBitcoinChainId(chainId) {
+    return chainId.startsWith("bip122:");
+}
+/**
+ * Get network from Stacks chain ID
+ */
+export function getNetworkFromStacksChainId(chainId) {
+    if (chainId === STACKS_CHAIN_IDS.mainnet)
+        return "mainnet";
+    if (chainId === STACKS_CHAIN_IDS.testnet)
+        return "testnet";
+    return null;
+}
+/**
+ * Get network from Bitcoin chain ID
+ */
+export function getNetworkFromBitcoinChainId(chainId) {
+    if (chainId === BITCOIN_CHAIN_IDS.mainnet)
+        return "mainnet";
+    if (chainId === BITCOIN_CHAIN_IDS.testnet)
+        return "testnet";
+    return null;
+}
+//# sourceMappingURL=caip.js.map

package/dist/config/caip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caip.js","sourceRoot":"","sources":["../../src/config/caip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,OAAO,EAAE,UAAU;IACnB,OAAO,EAAE,mBAAmB;CACpB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,OAAO,EAAE,yCAAyC;IAClD,OAAO,EAAE,yCAAyC;CAC1C,CAAC;AAEX;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgB;IAI3C,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClD,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,4BAA4B,OAAO,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,OAAO,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAgB;IAC1D,IAAI,OAAO,KAAK,gBAAgB,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC3D,IAAI,OAAO,KAAK,gBAAgB,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAAgB;IAC3D,IAAI,OAAO,KAAK,iBAAiB,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,iBAAiB,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC5D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/services/mempool-api.d.ts

@@ -0,0 +1,183 @@
+/**
+ * mempool.space API client for Bitcoin UTXO and fee data
+ *
+ * Public API endpoints (no authentication required):
+ * - Mainnet: https://mempool.space/api
+ * - Testnet: https://mempool.space/testnet/api
+ *
+ * Documentation: https://mempool.space/docs/api
+ */
+import type { Network } from "../config/networks.js";
+/**
+ * UTXO (Unspent Transaction Output) from mempool.space API
+ */
+export interface UTXO {
+    /**
+     * Transaction ID containing this UTXO
+     */
+    txid: string;
+    /**
+     * Output index within the transaction
+     */
+    vout: number;
+    /**
+     * UTXO status (confirmed or unconfirmed)
+     */
+    status: {
+        confirmed: boolean;
+        block_height?: number;
+        block_hash?: string;
+        block_time?: number;
+    };
+    /**
+     * Value in satoshis
+     */
+    value: number;
+}
+/**
+ * Fee estimates from mempool.space API (sat/vB)
+ */
+export interface FeeEstimates {
+    /**
+     * Fee rate for fastest confirmation (~10 min)
+     */
+    fastestFee: number;
+    /**
+     * Fee rate for fast confirmation (~30 min)
+     */
+    halfHourFee: number;
+    /**
+     * Fee rate for standard confirmation (~1 hour)
+     */
+    hourFee: number;
+    /**
+     * Fee rate for economy confirmation (~24 hours)
+     */
+    economyFee: number;
+    /**
+     * Minimum relay fee rate
+     */
+    minimumFee: number;
+}
+/**
+ * Simplified fee tiers for user selection
+ */
+export interface FeeTiers {
+    /**
+     * Fast: ~10 minute confirmation
+     */
+    fast: number;
+    /**
+     * Medium: ~30 minute confirmation
+     */
+    medium: number;
+    /**
+     * Slow: ~1 hour confirmation
+     */
+    slow: number;
+}
+/**
+ * Get the mempool.space API base URL for a network
+ */
+export declare function getMempoolApiUrl(network: Network): string;
+/**
+ * Get the mempool.space explorer URL for a network
+ */
+export declare function getMempoolExplorerUrl(network: Network): string;
+/**
+ * Get transaction explorer URL
+ */
+export declare function getMempoolTxUrl(txid: string, network: Network): string;
+/**
+ * Get address explorer URL
+ */
+export declare function getMempoolAddressUrl(address: string, network: Network): string;
+/**
+ * mempool.space API client
+ */
+export declare class MempoolApi {
+    private readonly baseUrl;
+    private readonly network;
+    constructor(network: Network);
+    /**
+     * Get UTXOs for a Bitcoin address
+     *
+     * @param address - Bitcoin address (bc1... for mainnet, tb1... for testnet)
+     * @returns Array of UTXOs with txid, vout, value, and confirmation status
+     * @throws Error if API request fails
+     *
+     * @example
+     * ```typescript
+     * const api = new MempoolApi('mainnet');
+     * const utxos = await api.getUtxos('bc1q...');
+     * const total = utxos.reduce((sum, u) => sum + u.value, 0);
+     * ```
+     */
+    getUtxos(address: string): Promise<UTXO[]>;
+    /**
+     * Get current recommended fee estimates
+     *
+     * @returns Fee estimates in sat/vB for different confirmation targets
+     * @throws Error if API request fails
+     *
+     * @example
+     * ```typescript
+     * const api = new MempoolApi('mainnet');
+     * const fees = await api.getFeeEstimates();
+     * console.log(`Fast fee: ${fees.fastestFee} sat/vB`);
+     * ```
+     */
+    getFeeEstimates(): Promise<FeeEstimates>;
+    /**
+     * Get simplified fee tiers for user selection
+     *
+     * Maps mempool.space fee estimates to fast/medium/slow tiers:
+     * - Fast: fastestFee (~10 min)
+     * - Medium: halfHourFee (~30 min)
+     * - Slow: hourFee (~1 hour)
+     *
+     * @returns Fee tiers in sat/vB
+     * @throws Error if API request fails
+     */
+    getFeeTiers(): Promise<FeeTiers>;
+    /**
+     * Get balance for a Bitcoin address (sum of UTXOs)
+     *
+     * @param address - Bitcoin address
+     * @returns Balance in satoshis
+     * @throws Error if API request fails
+     */
+    getBalance(address: string): Promise<number>;
+    /**
+     * Get confirmed balance for a Bitcoin address
+     *
+     * @param address - Bitcoin address
+     * @returns Confirmed balance in satoshis (excludes unconfirmed UTXOs)
+     * @throws Error if API request fails
+     */
+    getConfirmedBalance(address: string): Promise<number>;
+    /**
+     * Broadcast a signed transaction to the Bitcoin network
+     *
+     * @param txHex - Signed transaction as hex string
+     * @returns Transaction ID (txid)
+     * @throws Error if broadcast fails
+     *
+     * @example
+     * ```typescript
+     * const api = new MempoolApi('mainnet');
+     * const txid = await api.broadcastTransaction(signedTxHex);
+     * console.log(`Broadcast: ${getMempoolTxUrl(txid, 'mainnet')}`);
+     * ```
+     */
+    broadcastTransaction(txHex: string): Promise<string>;
+    /**
+     * Get the network this client is configured for
+     */
+    getNetwork(): Network;
+}
+/**
+ * Create a mempool.space API client for the given network
+ */
+export declare function createMempoolApi(network: Network): MempoolApi;
+//# sourceMappingURL=mempool-api.d.ts.map

package/dist/services/mempool-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mempool-api.d.ts","sourceRoot":"","sources":["../../src/services/mempool-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,MAAM,EAAE;QACN,SAAS,EAAE,OAAO,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAIzD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAI9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAEtE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAE9E;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAEtB,OAAO,EAAE,OAAO;IAK5B;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAchD;;;;;;;;;;;;OAYG;IACG,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC;IAc9C;;;;;;;;;;OAUG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC;IAStC;;;;;;OAMG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKlD;;;;;;OAMG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO3D;;;;;;;;;;;;;OAaG;IACG,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB1D;;OAEG;IACH,UAAU,IAAI,OAAO;CAGtB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAE7D"}

package/dist/services/mempool-api.js

@@ -0,0 +1,179 @@
+/**
+ * mempool.space API client for Bitcoin UTXO and fee data
+ *
+ * Public API endpoints (no authentication required):
+ * - Mainnet: https://mempool.space/api
+ * - Testnet: https://mempool.space/testnet/api
+ *
+ * Documentation: https://mempool.space/docs/api
+ */
+/**
+ * Get the mempool.space API base URL for a network
+ */
+export function getMempoolApiUrl(network) {
+    return network === "mainnet"
+        ? "https://mempool.space/api"
+        : "https://mempool.space/testnet/api";
+}
+/**
+ * Get the mempool.space explorer URL for a network
+ */
+export function getMempoolExplorerUrl(network) {
+    return network === "mainnet"
+        ? "https://mempool.space"
+        : "https://mempool.space/testnet";
+}
+/**
+ * Get transaction explorer URL
+ */
+export function getMempoolTxUrl(txid, network) {
+    return `${getMempoolExplorerUrl(network)}/tx/${txid}`;
+}
+/**
+ * Get address explorer URL
+ */
+export function getMempoolAddressUrl(address, network) {
+    return `${getMempoolExplorerUrl(network)}/address/${address}`;
+}
+/**
+ * mempool.space API client
+ */
+export class MempoolApi {
+    baseUrl;
+    network;
+    constructor(network) {
+        this.network = network;
+        this.baseUrl = getMempoolApiUrl(network);
+    }
+    /**
+     * Get UTXOs for a Bitcoin address
+     *
+     * @param address - Bitcoin address (bc1... for mainnet, tb1... for testnet)
+     * @returns Array of UTXOs with txid, vout, value, and confirmation status
+     * @throws Error if API request fails
+     *
+     * @example
+     * ```typescript
+     * const api = new MempoolApi('mainnet');
+     * const utxos = await api.getUtxos('bc1q...');
+     * const total = utxos.reduce((sum, u) => sum + u.value, 0);
+     * ```
+     */
+    async getUtxos(address) {
+        const response = await fetch(`${this.baseUrl}/address/${address}/utxo`);
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Failed to fetch UTXOs for ${address}: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+        const utxos = await response.json();
+        return utxos;
+    }
+    /**
+     * Get current recommended fee estimates
+     *
+     * @returns Fee estimates in sat/vB for different confirmation targets
+     * @throws Error if API request fails
+     *
+     * @example
+     * ```typescript
+     * const api = new MempoolApi('mainnet');
+     * const fees = await api.getFeeEstimates();
+     * console.log(`Fast fee: ${fees.fastestFee} sat/vB`);
+     * ```
+     */
+    async getFeeEstimates() {
+        const response = await fetch(`${this.baseUrl}/v1/fees/recommended`);
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Failed to fetch fee estimates: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+        const fees = await response.json();
+        return fees;
+    }
+    /**
+     * Get simplified fee tiers for user selection
+     *
+     * Maps mempool.space fee estimates to fast/medium/slow tiers:
+     * - Fast: fastestFee (~10 min)
+     * - Medium: halfHourFee (~30 min)
+     * - Slow: hourFee (~1 hour)
+     *
+     * @returns Fee tiers in sat/vB
+     * @throws Error if API request fails
+     */
+    async getFeeTiers() {
+        const estimates = await this.getFeeEstimates();
+        return {
+            fast: estimates.fastestFee,
+            medium: estimates.halfHourFee,
+            slow: estimates.hourFee,
+        };
+    }
+    /**
+     * Get balance for a Bitcoin address (sum of UTXOs)
+     *
+     * @param address - Bitcoin address
+     * @returns Balance in satoshis
+     * @throws Error if API request fails
+     */
+    async getBalance(address) {
+        const utxos = await this.getUtxos(address);
+        return utxos.reduce((sum, utxo) => sum + utxo.value, 0);
+    }
+    /**
+     * Get confirmed balance for a Bitcoin address
+     *
+     * @param address - Bitcoin address
+     * @returns Confirmed balance in satoshis (excludes unconfirmed UTXOs)
+     * @throws Error if API request fails
+     */
+    async getConfirmedBalance(address) {
+        const utxos = await this.getUtxos(address);
+        return utxos
+            .filter((utxo) => utxo.status.confirmed)
+            .reduce((sum, utxo) => sum + utxo.value, 0);
+    }
+    /**
+     * Broadcast a signed transaction to the Bitcoin network
+     *
+     * @param txHex - Signed transaction as hex string
+     * @returns Transaction ID (txid)
+     * @throws Error if broadcast fails
+     *
+     * @example
+     * ```typescript
+     * const api = new MempoolApi('mainnet');
+     * const txid = await api.broadcastTransaction(signedTxHex);
+     * console.log(`Broadcast: ${getMempoolTxUrl(txid, 'mainnet')}`);
+     * ```
+     */
+    async broadcastTransaction(txHex) {
+        const response = await fetch(`${this.baseUrl}/tx`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "text/plain",
+            },
+            body: txHex,
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Failed to broadcast transaction: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+        // Response is the txid as plain text
+        const txid = await response.text();
+        return txid.trim();
+    }
+    /**
+     * Get the network this client is configured for
+     */
+    getNetwork() {
+        return this.network;
+    }
+}
+/**
+ * Create a mempool.space API client for the given network
+ */
+export function createMempoolApi(network) {
+    return new MempoolApi(network);
+}
+//# sourceMappingURL=mempool-api.js.map

package/dist/services/mempool-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mempool-api.js","sourceRoot":"","sources":["../../src/services/mempool-api.ts"],"names":[],"mappings":"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"}

package/dist/services/wallet-manager.d.ts

@@ -63,6 +63,7 @@ declare class WalletManager {
     getSessionInfo(): {
         walletId: string;
         address: string;
+        btcAddress?: string;
         expiresAt: Date | null;
     } | null;
     /**

package/dist/services/wallet-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wallet-manager.d.ts","sourceRoot":"","sources":["../../src/services/wallet-manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAcL,KAAK,cAAc,EAEpB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAY1D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,cAAM,aAAa;IACjB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAgB;IACvC,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO;IAEP;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,aAAa;IAOnC;;OAEG;YACW,iBAAiB;IAO/B;;OAEG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,kBAAkB,CAAC;IAuD9B;;OAEG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,kBAAkB,CAAC;IAyD9B;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAuElE;;OAEG;IACH,IAAI,IAAI,IAAI;IAKZ;;OAEG;IACH,gBAAgB,IAAI,OAAO,GAAG,IAAI;IAclC;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,cAAc,IAAI;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;KACxB,GAAG,IAAI;IAkBR;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAM9C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAMpC;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMjD;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBnD;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CrE;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0BzE;;OAEG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBxD;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAM3B;AAGD,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD"}
+{"version":3,"file":"wallet-manager.d.ts","sourceRoot":"","sources":["../../src/services/wallet-manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAcL,KAAK,cAAc,EAEpB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAa1D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,cAAM,aAAa;IACjB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAgB;IACvC,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO;IAEP;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,aAAa;IAOnC;;OAEG;YACW,iBAAiB;IAO/B;;OAEG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,kBAAkB,CAAC;IA2D9B;;OAEG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,kBAAkB,CAAC;IA6D9B;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiFlE;;OAEG;IACH,IAAI,IAAI,IAAI;IAKZ;;OAEG;IACH,gBAAgB,IAAI,OAAO,GAAG,IAAI;IAclC;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,cAAc,IAAI;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;KACxB,GAAG,IAAI;IAmBR;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAM9C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAMpC;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMjD;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBnD;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CrE;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0BzE;;OAEG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBxD;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAM3B;AAGD,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD"}

package/dist/services/wallet-manager.js

@@ -4,6 +4,7 @@ import { wordlist } from "@scure/bip39/wordlists/english.js";
 import { encrypt, decrypt, generateWalletId, initializeStorage, readWalletIndex, readKeystore, writeKeystore, readAppConfig, writeAppConfig, addWalletToIndex, removeWalletFromIndex, deleteWalletStorage, updateWalletMetadata, } from "../utils/index.js";
 import { WalletNotFoundError, InvalidPasswordError, InvalidMnemonicError, } from "../utils/errors.js";
 import { NETWORK } from "../config/networks.js";
+import { deriveBitcoinAddress, deriveBitcoinKeyPair } from "../utils/bitcoin.js";
 /**
  * Wallet manager singleton - handles wallet creation, encryption, and session management
  */
@@ -46,6 +47,8 @@ class WalletManager {
         });
         const stacksAccount = wallet.accounts[0];
         const address = getStxAddress(stacksAccount, walletNetwork);
+        // Derive Bitcoin address
+        const { address: btcAddress } = deriveBitcoinAddress(mnemonic, walletNetwork);
         // Encrypt mnemonic
         const encrypted = await encrypt(mnemonic, password);
         // Generate wallet ID
@@ -63,6 +66,7 @@ class WalletManager {
             id: walletId,
             name,
             address,
+            btcAddress,
             network: walletNetwork,
             createdAt: new Date().toISOString(),
         };
@@ -95,6 +99,8 @@ class WalletManager {
         });
         const stacksAccount = wallet.accounts[0];
         const address = getStxAddress(stacksAccount, walletNetwork);
+        // Derive Bitcoin address
+        const { address: btcAddress } = deriveBitcoinAddress(normalizedMnemonic, walletNetwork);
         // Encrypt mnemonic
         const encrypted = await encrypt(normalizedMnemonic, password);
         // Generate wallet ID
@@ -112,6 +118,7 @@ class WalletManager {
             id: walletId,
             name,
             address,
+            btcAddress,
             network: walletNetwork,
             createdAt: new Date().toISOString(),
         };
@@ -159,9 +166,14 @@ class WalletManager {
         });
         const stacksAccount = wallet.accounts[0];
         const address = getStxAddress(stacksAccount, walletMeta.network);
+        // Derive Bitcoin key pair (includes private key for signing)
+        const { address: btcAddress, privateKey: btcPrivateKey, publicKeyBytes: btcPublicKey, } = deriveBitcoinKeyPair(mnemonic, walletMeta.network);
         const account = {
             address,
+            btcAddress,
             privateKey: stacksAccount.stxPrivateKey,
+            btcPrivateKey,
+            btcPublicKey,
             network: walletMeta.network,
         };
         // Update last used timestamp
@@ -229,6 +241,7 @@ class WalletManager {
         return {
             walletId: this.session.walletId,
             address: this.session.account.address,
+            btcAddress: this.session.account.btcAddress,
             expiresAt: this.session.expiresAt,
         };
     }