@aibtc/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,340 @@
+# @aibtc/mcp-server
+
+An MCP (Model Context Protocol) server that gives Claude its own Stacks wallet to interact with the blockchain and x402 paid API endpoints.
+
+## Features
+
+- **Agent's Own Wallet** - Claude gets its own wallet to perform blockchain transactions
+- **Secure Storage** - Wallets encrypted with AES-256-GCM and stored locally
+- **50+ Tools** - Comprehensive Stacks blockchain 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
+- **BNS Domains** - .btc domain lookups and management (V1 + V2)
+- **x402 Payments** - Automatic payment handling for paid APIs
+
+## Quick Start
+
+### One-Command Install
+
+```bash
+npx @aibtc/mcp-server@latest --install
+```
+
+That's it! This automatically configures Claude Code. Restart your terminal and start chatting.
+
+**For mainnet:**
+```bash
+npx @aibtc/mcp-server@latest --install --mainnet
+```
+
+> **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.
+
+## Giving Claude a Wallet
+
+When you first use @aibtc/mcp-server, Claude doesn't have a wallet. Here's the smooth onboarding flow:
+
+### Example Conversation
+
+```
+You: What's your wallet address?
+
+Claude: I don't have a wallet yet. Would you like to assign me one?
+        I can either create a fresh wallet or you can import an existing one.
+
+You: Create a new wallet called "agent-wallet"
+
+Claude: What password should I use to protect the wallet?
+
+You: use "secure123password"
+
+Claude: I now have a wallet! My address is ST1ABC...XYZ
+
+        IMPORTANT: Please save this recovery phrase securely:
+        "word1 word2 word3 ... word24"
+
+        This phrase will NOT be shown again. It's the only way to recover
+        the wallet if the password is forgotten.
+
+You: Send 10 STX to ST2DEF...
+
+Claude: Done! I've sent 10 STX to ST2DEF...
+        Transaction: 0x123...
+```
+
+### Wallet States
+
+| State | What Claude Says | What To Do |
+|-------|-----------------|------------|
+| No wallet | "I don't have a wallet yet" | Use `wallet_create` or `wallet_import` |
+| Locked | "My wallet is locked" | Use `wallet_unlock` with password |
+| Ready | "My address is ST..." | Claude can perform transactions |
+
+### Session Management
+
+- By default, the wallet auto-locks after 15 minutes
+- You can change this with `wallet_set_timeout` (set to 0 to disable)
+- Use `wallet_lock` to manually lock the wallet
+- Use `wallet_unlock` when you need Claude to transact again
+
+## Wallet Storage
+
+Claude's wallets are stored locally on your machine:
+
+```
+~/.aibtc/
+├── wallets.json       # Wallet index (names, addresses - no secrets)
+├── config.json        # Active wallet, settings
+└── wallets/
+    └── [wallet-id]/
+        └── keystore.json  # Encrypted mnemonic (AES-256-GCM + Scrypt)
+```
+
+**Security:**
+- AES-256-GCM encryption with Scrypt key derivation
+- Password required to unlock
+- Mnemonics never stored in plaintext
+- File permissions set to owner-only (0600)
+
+## Available Tools (50+ total)
+
+### Wallet Management
+| Tool | Description |
+|------|-------------|
+| `wallet_create` | Create a new wallet for Claude |
+| `wallet_import` | Import an existing wallet for Claude |
+| `wallet_unlock` | Unlock Claude's wallet |
+| `wallet_lock` | Lock Claude's wallet |
+| `wallet_list` | List Claude's available wallets |
+| `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_set_timeout` | Set how long wallet stays unlocked |
+
+### Wallet & Balance
+| Tool | Description |
+|------|-------------|
+| `get_wallet_info` | Get Claude's wallet address and status |
+| `get_stx_balance` | Get STX balance for any address |
+
+### STX Transfers
+| Tool | Description |
+|------|-------------|
+| `transfer_stx` | Send STX to a recipient |
+| `broadcast_transaction` | Broadcast a pre-signed transaction |
+
+### sBTC Operations
+| Tool | Description |
+|------|-------------|
+| `sbtc_get_balance` | Get sBTC balance |
+| `sbtc_transfer` | Send sBTC |
+| `sbtc_get_deposit_info` | Get BTC deposit instructions |
+| `sbtc_get_peg_info` | Get peg ratio and TVL |
+
+### Token Operations (SIP-010)
+| Tool | Description |
+|------|-------------|
+| `get_token_balance` | Get balance of any SIP-010 token |
+| `transfer_token` | Send any SIP-010 token |
+| `get_token_info` | Get token metadata |
+| `list_user_tokens` | List tokens owned by an address |
+| `get_token_holders` | Get top holders of a token |
+
+### NFT Operations (SIP-009)
+| Tool | Description |
+|------|-------------|
+| `get_nft_holdings` | List NFTs owned by an address |
+| `get_nft_metadata` | Get NFT metadata |
+| `transfer_nft` | Send an NFT |
+| `get_nft_owner` | Get NFT owner |
+| `get_collection_info` | Get NFT collection details |
+| `get_nft_history` | Get NFT transfer history |
+
+### 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 |
+
+### BNS Domains (V1 + V2)
+| Tool | Description |
+|------|-------------|
+| `lookup_bns_name` | Resolve .btc domain to address |
+| `reverse_bns_lookup` | Get .btc domain for an address |
+| `get_bns_info` | Get domain details |
+| `check_bns_availability` | Check if domain is available |
+| `get_bns_price` | Get registration price |
+| `list_user_domains` | List domains owned |
+
+### Smart Contracts
+| Tool | Description |
+|------|-------------|
+| `call_contract` | Call a smart contract function |
+| `deploy_contract` | Deploy a Clarity smart contract |
+| `get_transaction_status` | Check transaction status |
+| `call_read_only_function` | Call read-only function |
+
+### DeFi - ALEX DEX (Mainnet)
+
+Uses the official `alex-sdk` for swap operations. Supports simple token symbols like "STX", "ALEX".
+
+| Tool | Description |
+|------|-------------|
+| `alex_list_pools` | Discover all available trading pools |
+| `alex_get_swap_quote` | Get expected output for a token swap |
+| `alex_swap` | Execute a token swap (SDK handles routing) |
+| `alex_get_pool_info` | Get liquidity pool reserves |
+
+### DeFi - Zest Protocol (Mainnet)
+
+Supports 10 assets: sBTC, aeUSDC, stSTX, wSTX, USDH, sUSDT, USDA, DIKO, ALEX, stSTX-BTC
+
+| Tool | Description |
+|------|-------------|
+| `zest_list_assets` | List all supported lending assets |
+| `zest_get_position` | Get user's supply/borrow position |
+| `zest_supply` | Supply assets to earn interest |
+| `zest_withdraw` | Withdraw supplied assets |
+| `zest_borrow` | Borrow against collateral |
+| `zest_repay` | Repay borrowed assets |
+
+### Blockchain Queries
+| Tool | Description |
+|------|-------------|
+| `get_account_info` | Get account nonce, balance |
+| `get_account_transactions` | List transaction history |
+| `get_block_info` | Get block details |
+| `get_mempool_info` | Get pending transactions |
+| `get_contract_info` | Get contract ABI and source |
+| `get_contract_events` | Get contract event history |
+| `get_network_status` | Get network health status |
+
+### x402 API Endpoints
+| Tool | Description |
+|------|-------------|
+| `list_x402_endpoints` | Discover x402 endpoints |
+| `execute_x402_endpoint` | Execute x402 endpoint with auto-payment |
+
+## Usage Examples
+
+**Wallet management:**
+> "What's your wallet address?"
+> "Create a wallet for yourself"
+> "Unlock your wallet"
+> "Keep your wallet unlocked for 1 hour"
+
+**Check balances:**
+> "How much STX do you have?"
+> "What's your sBTC balance?"
+
+**Transfer tokens:**
+> "Send 2 STX to ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM"
+> "Transfer 0.001 sBTC to muneeb.btc"
+
+**NFTs:**
+> "What NFTs do you own?"
+> "Send this NFT to alice.btc"
+
+**BNS domains:**
+> "What address is satoshi.btc?"
+> "Is myname.btc available?"
+
+**DeFi trading (mainnet):**
+> "What pools are available on ALEX?"
+> "Swap 0.1 STX for ALEX"
+> "Get a quote for 100 STX to ALEX"
+> "What assets can I lend on Zest?"
+> "Supply 100 stSTX to Zest"
+> "Borrow 50 aeUSDC from Zest"
+> "Check my Zest position"
+
+**x402 endpoints:**
+> "Get trending liquidity pools"
+> "Tell me a dad joke"
+
+## Supported Tokens
+
+Well-known tokens can be referenced by symbol:
+- **sBTC** - Native Bitcoin on Stacks
+- **USDCx** - USD Coin on Stacks
+- **ALEX** - ALEX governance token
+- **wSTX** - Wrapped STX
+
+**ALEX DEX tokens:** STX, ALEX, and any token from `alex_list_pools`
+
+**Zest Protocol assets:** sBTC, aeUSDC, stSTX, wSTX, USDH, sUSDT, USDA, DIKO, ALEX, stSTX-BTC
+
+Or use any SIP-010 token by contract ID: `SP2X...::token-name`
+
+## Configuration
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `NETWORK` | `mainnet` or `testnet` | `testnet` |
+| `API_URL` | Default x402 API base URL | `https://x402.biwas.xyz` |
+| `CLIENT_MNEMONIC` | (Optional) Pre-configured mnemonic | - |
+
+**Note:** `CLIENT_MNEMONIC` is optional. The recommended approach is to let Claude create its own wallet.
+
+## Architecture
+
+```
+You ←→ Claude ←→ aibtc-mcp-server
+                        ↓
+              Claude's Wallet (~/.aibtc/)
+                        ↓
+              ┌─────────┴─────────┐
+              ↓                   ↓
+        Hiro Stacks API    x402 Endpoints
+              ↓                   ↓
+        Stacks Blockchain  Paid API Services
+```
+
+## Security Notes
+
+- Claude's wallet is stored encrypted on YOUR machine
+- Password is never stored - only the encrypted keystore
+- Mnemonics shown only once at creation
+- Auto-lock after 15 minutes (configurable)
+- Transactions signed locally before broadcast
+- For mainnet: Fund with small amounts first
+
+## Advanced: Pre-configured Mnemonic
+
+For automated setups where Claude needs immediate wallet access, set the `CLIENT_MNEMONIC` environment variable in your `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "aibtc": {
+      "command": "npx",
+      "args": ["@aibtc/mcp-server@latest"],
+      "env": {
+        "CLIENT_MNEMONIC": "your twenty four word mnemonic phrase",
+        "NETWORK": "testnet"
+      }
+    }
+  }
+}
+```
+
+This bypasses the wallet creation flow - Claude has immediate access to transact.
+
+## Development
+
+```bash
+git clone https://github.com/aibtcdev/aibtc-mcp-server.git
+cd aibtc-mcp-server
+npm install
+npm run build
+npm run dev       # Run with tsx (development)
+```
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,9 @@
+import "dotenv/config";
+import { type AxiosInstance } from "axios";
+import { type Network } from "./wallet.js";
+export declare const NETWORK: Network;
+export declare const API_URL: string;
+export declare function createApiClient(baseUrl?: string): Promise<AxiosInstance>;
+export declare function getWalletAddress(): Promise<string>;
+export declare function getAccount(): Promise<import("./wallet.js").Account>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAc,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAElD,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAE9D,eAAO,MAAM,OAAO,EAAE,OACqC,CAAC;AAC5D,eAAO,MAAM,OAAO,QAAkD,CAAC;AAKvE,wBAAsB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAgE9E;AAED,wBAAgB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAMlD;AAED,wBAAsB,UAAU,2CAM/B"}

package/dist/api.js

@@ -0,0 +1,79 @@
+import "dotenv/config";
+import axios from "axios";
+import { withPaymentInterceptor } from "x402-stacks";
+import { mnemonicToAccount } from "./wallet.js";
+export const NETWORK = process.env.NETWORK === "mainnet" ? "mainnet" : "testnet";
+export const API_URL = process.env.API_URL || "https://x402.biwas.xyz";
+// Cache clients by base URL
+const clientCache = new Map();
+export async function createApiClient(baseUrl) {
+    const url = baseUrl || API_URL;
+    // Check cache
+    const cached = clientCache.get(url);
+    if (cached) {
+        return cached;
+    }
+    const mnemonic = process.env.CLIENT_MNEMONIC || "";
+    if (!mnemonic) {
+        throw new Error("CLIENT_MNEMONIC is required in environment variables");
+    }
+    const account = await mnemonicToAccount(mnemonic, NETWORK);
+    const axiosInstance = axios.create({
+        baseURL: url,
+        timeout: 60000,
+        transformResponse: [
+            (data) => {
+                if (typeof data !== "string") {
+                    return data;
+                }
+                const trimmed = data.trim();
+                if (!trimmed) {
+                    return data;
+                }
+                try {
+                    return JSON.parse(trimmed);
+                }
+                catch {
+                    return data;
+                }
+            },
+        ],
+    });
+    // Ensure 402 payloads are parsed before x402-stacks validates them
+    axiosInstance.interceptors.response.use((response) => response, (error) => {
+        const data = error?.response?.data;
+        if (error?.response?.status === 402) {
+            console.error("x402 debug 402 payload", typeof data === "string" ? data : JSON.stringify(data));
+        }
+        if (typeof data === "string") {
+            const trimmed = data.trim();
+            if (trimmed) {
+                try {
+                    error.response.data = JSON.parse(trimmed);
+                }
+                catch {
+                    // Leave as-is if it's not JSON
+                }
+            }
+        }
+        return Promise.reject(error);
+    });
+    const client = withPaymentInterceptor(axiosInstance, account);
+    clientCache.set(url, client);
+    return client;
+}
+export function getWalletAddress() {
+    const mnemonic = process.env.CLIENT_MNEMONIC || "";
+    if (!mnemonic) {
+        throw new Error("CLIENT_MNEMONIC is required in environment variables");
+    }
+    return mnemonicToAccount(mnemonic, NETWORK).then((account) => account.address);
+}
+export async function getAccount() {
+    const mnemonic = process.env.CLIENT_MNEMONIC || "";
+    if (!mnemonic) {
+        throw new Error("CLIENT_MNEMONIC is required in environment variables");
+    }
+    return mnemonicToAccount(mnemonic, NETWORK);
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

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

package/dist/config/contracts.d.ts

@@ -0,0 +1,169 @@
+import { Network } from "./networks.js";
+/**
+ * Known contract addresses for mainnet
+ */
+export declare const MAINNET_CONTRACTS: {
+    readonly SBTC_TOKEN: "SM3VDXK3WZZSA84XXFQ5FDMR6S8N5XQSEK4KMR5E5.sbtc-token";
+    readonly SBTC_DEPOSIT: "SM3VDXK3WZZSA84XXFQ5FDMR6S8N5XQSEK4KMR5E5.sbtc-deposit";
+    readonly SBTC_REGISTRY: "SM3VDXK3WZZSA84XXFQ5FDMR6S8N5XQSEK4KMR5E5.sbtc-registry";
+    readonly USDCX: "SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-usdcx";
+    readonly BNS: "SP000000000000000000002Q6VF78.bns";
+    readonly POX_4: "SP000000000000000000002Q6VF78.pox-4";
+    readonly ALEX_AMM_POOL: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1";
+    readonly ALEX_TOKEN: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex";
+    readonly ALEX_WSTX: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx-v2";
+    readonly ZEST_POOL_BORROW: "SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.pool-borrow-v2-3";
+    readonly ZEST_POOL_RESERVE: "SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.pool-0-reserve";
+    readonly ZEST_FEES_CALCULATOR: "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.fees-calculator";
+};
+/**
+ * Zest Protocol asset configuration
+ * Each asset has: token, lpToken, oracle, decimals, symbol
+ */
+export interface ZestAssetConfig {
+    token: string;
+    lpToken: string;
+    oracle: string;
+    decimals: number;
+    symbol: string;
+    name: string;
+}
+export declare const ZEST_ASSETS: Record<string, ZestAssetConfig>;
+/**
+ * Ordered list of Zest assets for building the assets-list parameter
+ * Order matters for contract calls
+ */
+export declare const ZEST_ASSETS_LIST: ZestAssetConfig[];
+/**
+ * Known contract addresses for testnet
+ */
+export declare const TESTNET_CONTRACTS: {
+    readonly SBTC_TOKEN: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sbtc-token";
+    readonly SBTC_DEPOSIT: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sbtc-deposit";
+    readonly SBTC_REGISTRY: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sbtc-registry";
+    readonly USDCX: "ST2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-usdcx";
+    readonly BNS: "ST000000000000000000002AMW42H.bns";
+    readonly POX_4: "ST000000000000000000002AMW42H.pox-4";
+};
+/**
+ * Get contract addresses for the specified network
+ */
+export declare function getContracts(network: Network): {
+    readonly SBTC_TOKEN: "SM3VDXK3WZZSA84XXFQ5FDMR6S8N5XQSEK4KMR5E5.sbtc-token";
+    readonly SBTC_DEPOSIT: "SM3VDXK3WZZSA84XXFQ5FDMR6S8N5XQSEK4KMR5E5.sbtc-deposit";
+    readonly SBTC_REGISTRY: "SM3VDXK3WZZSA84XXFQ5FDMR6S8N5XQSEK4KMR5E5.sbtc-registry";
+    readonly USDCX: "SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-usdcx";
+    readonly BNS: "SP000000000000000000002Q6VF78.bns";
+    readonly POX_4: "SP000000000000000000002Q6VF78.pox-4";
+    readonly ALEX_AMM_POOL: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1";
+    readonly ALEX_TOKEN: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex";
+    readonly ALEX_WSTX: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx-v2";
+    readonly ZEST_POOL_BORROW: "SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.pool-borrow-v2-3";
+    readonly ZEST_POOL_RESERVE: "SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.pool-0-reserve";
+    readonly ZEST_FEES_CALCULATOR: "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.fees-calculator";
+} | {
+    readonly SBTC_TOKEN: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sbtc-token";
+    readonly SBTC_DEPOSIT: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sbtc-deposit";
+    readonly SBTC_REGISTRY: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sbtc-registry";
+    readonly USDCX: "ST2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-usdcx";
+    readonly BNS: "ST000000000000000000002AMW42H.bns";
+    readonly POX_4: "ST000000000000000000002AMW42H.pox-4";
+};
+/**
+ * Parse a contract identifier into address and name
+ */
+export declare function parseContractId(contractId: string): {
+    address: string;
+    name: string;
+};
+/**
+ * Fallback token contract IDs (used only when dynamic resolution fails)
+ * Prefer using resolveTokenSymbol() which checks user balances first
+ */
+export declare const WELL_KNOWN_TOKENS: {
+    readonly mainnet: {
+        readonly STX: "native";
+        readonly sBTC: "SM3VDXK3WZZSA84XXFQ5FDMR6S8N5XQSEK4KMR5E5.sbtc-token";
+        readonly USDCx: "SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-usdcx";
+        readonly ALEX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex";
+        readonly wSTX: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx-v2";
+    };
+    readonly testnet: {
+        readonly STX: "native";
+        readonly sBTC: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sbtc-token";
+        readonly USDCx: "ST2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-usdcx";
+    };
+};
+/**
+ * Get ALEX DEX contract addresses for the network
+ * Note: Most ALEX operations use the alex-sdk, but we need the pool contract for queries
+ */
+export declare function getAlexContracts(network: Network): {
+    ammPool: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1";
+} | null;
+/**
+ * Get Zest Protocol contract addresses for the network
+ */
+export declare function getZestContracts(network: Network): {
+    poolBorrow: "SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.pool-borrow-v2-3";
+    poolReserve: "SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.pool-0-reserve";
+    feesCalculator: "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.fees-calculator";
+} | null;
+export declare function getWellKnownTokens(network: Network): {
+    readonly STX: "native";
+    readonly sBTC: "SM3VDXK3WZZSA84XXFQ5FDMR6S8N5XQSEK4KMR5E5.sbtc-token";
+    readonly USDCx: "SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-usdcx";
+    readonly ALEX: "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex";
+    readonly wSTX: "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx-v2";
+} | {
+    readonly STX: "native";
+    readonly sBTC: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.sbtc-token";
+    readonly USDCx: "ST2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK.token-usdcx";
+};
+/**
+ * Bitflow DEX contract addresses
+ */
+export declare const BITFLOW_CONTRACTS: {
+    readonly mainnet: {
+        readonly PRIMARY: "SPQC38PW542EQJ5M11CR25P7BS1CA6QT4TBXGB3M";
+        readonly XYK: "SM1793C4R5PZ4NS4VQ4WMP7SKKYVH8JZEWSZ9HCCR";
+    };
+    readonly testnet: {
+        readonly PRIMARY: "STRP7MYBHSMFH5EGN3HGX6KNQ7QBHVTBPF1669DW";
+        readonly XYK: null;
+    };
+};
+/**
+ * Bitflow configuration
+ */
+export interface BitflowConfig {
+    apiHost: string;
+    apiKey: string | undefined;
+    readOnlyCallApiHost: string;
+    keeperApiHost?: string;
+    keeperApiKey?: string;
+}
+/**
+ * Get Bitflow configuration from environment
+ *
+ * TODO: Once API keys are obtained from Bitflow team:
+ * 1. Set BITFLOW_API_KEY and BITFLOW_API_HOST environment variables
+ * 2. Optionally set BITFLOW_KEEPER_API_KEY and BITFLOW_KEEPER_API_HOST for Keeper features
+ * 3. Consider moving keys to Cloudflare Worker proxy for secure npm distribution
+ */
+export declare function getBitflowConfig(): BitflowConfig | null;
+/**
+ * Get Bitflow contract addresses for the network
+ */
+export declare function getBitflowContracts(network: Network): {
+    readonly PRIMARY: "SPQC38PW542EQJ5M11CR25P7BS1CA6QT4TBXGB3M";
+    readonly XYK: "SM1793C4R5PZ4NS4VQ4WMP7SKKYVH8JZEWSZ9HCCR";
+} | {
+    readonly PRIMARY: "STRP7MYBHSMFH5EGN3HGX6KNQ7QBHVTBPF1669DW";
+    readonly XYK: null;
+};
+/**
+ * Bitflow public API base URL (no API key required)
+ */
+export declare const BITFLOW_PUBLIC_API = "https://bitflow-sdk-api-gateway-7owjsmt8.uc.gateway.dev";
+//# sourceMappingURL=contracts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/config/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;CAwBpB,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAiFvD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAAe,EAW7C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;CAcpB,CAAC;AAEX;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;EAE5C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMrF;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;CAapB,CAAC;AAEX;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO;;SAQhD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO;;;;SAUhD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO;;;;;;;;;;EAElD;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;CAWpB,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAiBvD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO;;;;;;EAEnD;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,4DAA4D,CAAC"}