@aibtc/mcp-server 1.7.0 → 1.9.0

package/skill/references/stacks-defi.md

@@ -0,0 +1,258 @@
+# Stacks L2 DeFi
+
+Stacks is a Bitcoin L2 with smart contracts. This reference covers STX transfers, DEX swaps, lending protocols, and x402 paid endpoints.
+
+## STX Transfers
+
+Transfer STX tokens to any Stacks address:
+
+```
+"Send 2 STX to ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM"
+```
+
+Uses `transfer_stx` - amounts in micro-STX (1 STX = 1,000,000 micro-STX).
+
+Check STX balance:
+
+```
+"What's my STX balance?"
+```
+
+Uses `get_stx_balance`.
+
+## ALEX DEX (Mainnet Only)
+
+Decentralized exchange for token swaps on Stacks.
+
+### Discover Pools
+
+Find available trading pairs:
+
+```
+"What pools are available on ALEX?"
+```
+
+Uses `alex_list_pools` - shows all tradable token pairs.
+
+### Get Quote
+
+Check expected output before swapping:
+
+```
+"How much ALEX for 10 STX?"
+```
+
+Uses `alex_get_swap_quote` with token symbols (STX, ALEX, etc).
+
+### Execute Swap
+
+Swap tokens:
+
+```
+"Swap 0.1 STX for ALEX"
+```
+
+Uses `alex_swap` - handles routing, wrapping, and post-conditions automatically.
+
+### ALEX Tool Reference
+
+| Tool | Description |
+|------|-------------|
+| `alex_list_pools` | List all trading pools |
+| `alex_get_swap_quote` | Get expected output |
+| `alex_swap` | Execute token swap |
+| `alex_get_pool_info` | Get pool reserves |
+
+## Zest Protocol (Mainnet Only)
+
+Lending and borrowing protocol for earning yield on assets.
+
+### Supported Assets
+
+| Symbol | Description |
+|--------|-------------|
+| sBTC | Wrapped Bitcoin |
+| aeUSDC | Bridged USDC |
+| stSTX | Staked STX |
+| wSTX | Wrapped STX |
+| USDH | Stablecoin |
+| sUSDT | Bridged USDT |
+| USDA | Arkadiko stablecoin |
+| DIKO | Arkadiko governance token |
+| ALEX | ALEX token |
+| stSTX-BTC | Staked STX/BTC LP |
+
+### Check Position
+
+View your lending position:
+
+```
+"What's my Zest position for stSTX?"
+```
+
+Uses `zest_get_position` with asset symbol.
+
+### Supply Assets
+
+Deposit to earn interest:
+
+```
+"Supply 1000 stSTX to Zest"
+```
+
+Uses `zest_supply` - amounts in smallest units (check decimals per asset).
+
+### Borrow Assets
+
+Borrow against collateral:
+
+```
+"Borrow 100 aeUSDC from Zest"
+```
+
+Uses `zest_borrow` - ensure sufficient collateral first.
+
+### Repay Loan
+
+Repay borrowed assets:
+
+```
+"Repay 50 aeUSDC on Zest"
+```
+
+Uses `zest_repay`.
+
+### Withdraw Assets
+
+Withdraw supplied assets:
+
+```
+"Withdraw 500 stSTX from Zest"
+```
+
+Uses `zest_withdraw`.
+
+### Zest Tool Reference
+
+| Tool | Description |
+|------|-------------|
+| `zest_list_assets` | List supported assets |
+| `zest_get_position` | Check supply/borrow |
+| `zest_supply` | Deposit assets |
+| `zest_withdraw` | Withdraw assets |
+| `zest_borrow` | Borrow assets |
+| `zest_repay` | Repay loan |
+
+## x402 Protocol
+
+Pay-per-use APIs with automatic micropayments. The agent handles HTTP 402 payment challenges automatically.
+
+### API Services
+
+Three complementary x402 API services are available:
+
+#### STX402 Directory (stx402.com)
+
+Meta layer for the x402 ecosystem:
+
+| Category | Endpoints |
+|----------|-----------|
+| **Registry** | `/registry/list`, `/registry/probe`, `/registry/register` |
+| **Agent Identity** | `/agent/info`, `/agent/lookup`, `/agent/metadata` |
+| **Reputation** | `/agent/reputation/summary`, `/agent/reputation/feedback` |
+| **Links** | `/links/create`, `/links/stats`, `/links/expand/{slug}` |
+
+[API Docs](https://stx402.com/docs) · [Guide](https://stx402.com/guide) · [Toolbox](https://stx402.com/toolbox)
+
+#### x402 AIBTC API (x402.aibtc.com)
+
+Utility services for agents:
+
+| Category | Endpoints |
+|----------|-----------|
+| **Inference** | `/inference/openrouter/chat`, `/inference/cloudflare/chat` |
+| **Stacks** | `/stacks/address`, `/stacks/decode`, `/stacks/profile` |
+| **Hashing** | `/hashing/sha256`, `/hashing/keccak256`, `/hashing/hash160` |
+| **Storage** | `/storage/kv/*`, `/storage/paste/*`, `/storage/db/*`, `/storage/memory/*` |
+
+[API Docs](https://x402.aibtc.com/docs) · [Staging](https://x402.aibtc.dev)
+
+#### x402 Biwas API (x402.biwas.xyz)
+
+DeFi analytics and market data:
+
+| Category | Endpoints |
+|----------|-----------|
+| **Pools** | `/api/pools/trending`, `/api/pools/all` |
+| **Market Data** | `/api/tokens/prices`, `/api/tokens/trending` |
+| **Wallet Analysis** | `/api/wallet/holdings`, `/api/wallet/history` |
+| **Security** | `/api/security/audit`, `/api/security/score` |
+
+[API Docs](https://x402.biwas.xyz/docs)
+
+### Usage
+
+Discover endpoints:
+
+```
+"List x402 endpoints for inference"
+"What storage APIs are available?"
+```
+
+Execute endpoint:
+
+```
+"Chat with Claude via x402"
+"Store this data in x402 KV"
+```
+
+Uses `list_x402_endpoints` to discover, `execute_x402_endpoint` to call.
+
+### Payment
+
+- **Tokens**: STX, sBTC, USDCx
+- **Pricing**: Standard tier (~0.001 STX) or dynamic (LLM pass-through + 20%)
+- **Flow**: Request → 402 response → sign payment → retry with proof
+
+### x402 Tool Reference
+
+| Tool | Description |
+|------|-------------|
+| `list_x402_endpoints` | Discover APIs by source/category |
+| `execute_x402_endpoint` | Call endpoint with auto-payment |
+| `scaffold_x402_endpoint` | Generate x402 API project |
+| `scaffold_x402_ai_endpoint` | Generate x402 AI API project |
+
+## Smart Contract Calls
+
+Call any Stacks smart contract:
+
+```
+"Call get-balance on token contract"
+```
+
+Uses `call_contract` for write operations, `call_read_only_function` for read-only.
+
+### Contract Tool Reference
+
+| Tool | Description |
+|------|-------------|
+| `call_contract` | Call contract function (signs tx) |
+| `call_read_only_function` | Read-only call (no signing) |
+| `deploy_contract` | Deploy Clarity contract |
+| `get_contract_info` | Get contract ABI |
+| `get_transaction_status` | Check tx status |
+
+## More Information
+
+- [Stacks Docs](https://docs.stacks.co)
+- [ALEX DEX](https://alexgo.io)
+- [Zest Protocol](https://zestprotocol.com)
+- [x402 Protocol](https://www.x402.org)
+- [STX402 Docs](https://stx402.com/docs)
+- [x402 AIBTC Docs](https://x402.aibtc.com/docs)
+- [CLAUDE.md DeFi Sections](../../CLAUDE.md#defi---alex-dex-mainnet-only)
+
+---
+
+*Back to: [SKILL.md](../SKILL.md)*

package/skill/references/troubleshooting.md

@@ -0,0 +1,211 @@
+# Troubleshooting
+
+Common issues and solutions when using the Bitcoin wallet tools.
+
+## Wallet Issues
+
+### "Wallet not unlocked"
+
+**Symptom**: Transaction fails with unlock error.
+
+**Solution**: Run `wallet_unlock` with your password before sending transactions.
+
+```
+"Unlock my wallet"
+```
+
+After completing transactions, lock for security:
+
+```
+"Lock my wallet"
+```
+
+### "No wallet configured"
+
+**Symptom**: Tools fail without wallet.
+
+**Solution**: Create or import a wallet first:
+
+```
+"Create a new wallet"
+"Import wallet from mnemonic"
+```
+
+### "Wrong password"
+
+**Symptom**: Unlock fails.
+
+**Solution**: Use `wallet_list` to find and confirm the correct wallet `id` (not just the name). If needed, run `wallet_switch <walletId>`, then retry `wallet_unlock` with that wallet ID and the correct password.
+
+## Balance Issues
+
+### "Insufficient balance"
+
+**Symptom**: Transfer fails due to low balance.
+
+**Solution**: Check balance includes fees:
+
+```
+"What's my BTC balance?"
+"What are current fees?"
+```
+
+For Bitcoin, you need: amount + (fee_rate * ~200 vBytes).
+
+### "Unconfirmed balance"
+
+**Symptom**: Balance shows but can't spend.
+
+**Solution**: Wait for confirmations. `get_btc_balance` shows confirmed vs unconfirmed. Most transfers need 1+ confirmations.
+
+## Transaction Issues
+
+### "Transaction pending"
+
+**Symptom**: Transaction broadcast but not confirmed.
+
+**Solution**: Use the `explorerUrl` returned by `transfer_btc` to check status on mempool.space. Bitcoin transactions can take 10 min to 1+ hour depending on fee rate. Use "fast" fees for quicker confirmation.
+
+### "Transaction failed"
+
+**Symptom**: Broadcast error.
+
+**Possible causes**:
+- Insufficient balance
+- Invalid address
+- Network issues
+
+**Solution**: Check error message, verify address format, retry.
+
+### "Invalid address"
+
+**Symptom**: Address rejected.
+
+**Solution**: Verify address matches network:
+
+| Network | BTC Address | STX Address |
+|---------|-------------|-------------|
+| Mainnet | `bc1...` | `SP...` |
+| Testnet | `tb1...` | `ST...` |
+
+## Network Issues
+
+### "Network timeout"
+
+**Symptom**: API calls fail.
+
+**Solution**:
+1. Check internet connection
+2. Retry after a moment
+3. Check mempool.space (BTC) or Hiro API (Stacks) status
+
+### "Rate limited"
+
+**Symptom**: Too many requests error.
+
+**Solution**: Wait a few seconds between calls. Avoid rapid polling.
+
+## Pillar Issues
+
+### Browser Handoff Mode
+
+#### "Browser didn't open"
+
+**Symptom**: Pillar operation stuck.
+
+**Solution**: Manually open https://pillarbtc.com and check if logged in.
+
+#### "Operation timed out"
+
+**Symptom**: Pillar action never completes.
+
+**Solution**:
+1. Check browser for pending approval
+2. Ensure you're logged into Pillar
+3. Cancel and retry
+
+### Agent Direct Mode
+
+#### "No signing key found"
+
+**Symptom**: `pillar_direct_*` tools fail.
+
+**Solution**: Create a signing key and wallet first:
+
+```
+"Create a Pillar wallet for my agent"
+```
+
+Uses `pillar_direct_create_wallet` - generates key, deploys wallet, registers pubkey.
+
+#### "Signing key locked"
+
+**Symptom**: Operations fail with lock error.
+
+**Solution**: Keys auto-unlock if `PILLAR_API_KEY` is set. If not:
+
+```
+"Unlock my Pillar signing key"
+```
+
+#### "Wallet pending"
+
+**Symptom**: Operations fail, wallet not ready.
+
+**Solution**: Wait 20-30 seconds after `pillar_direct_create_wallet` for on-chain deployment to complete.
+
+## Stacks/DeFi Issues
+
+### "Mainnet only"
+
+**Symptom**: ALEX or Zest tools fail on testnet.
+
+**Solution**: ALEX DEX and Zest Protocol are mainnet-only. Switch network or use testnet alternatives.
+
+### "Contract call failed"
+
+**Symptom**: Smart contract error.
+
+**Solution**: Check error message for:
+- Insufficient tokens
+- Invalid arguments
+- Contract paused
+
+### "Slippage too high"
+
+**Symptom**: Swap rejected.
+
+**Solution**:
+1. Get fresh quote
+2. Increase slippage tolerance
+3. Try smaller amount
+
+## Getting Help
+
+### Debug Information
+
+Gather this info before reporting:
+
+```
+"Check wallet status"
+"Get network status"
+```
+
+### Report Issues
+
+- [GitHub Issues](https://github.com/aibtcdev/aibtc-mcp-server/issues)
+- Include: error message, command attempted, network (mainnet/testnet)
+
+### Environment Check
+
+Verify configuration:
+
+```
+"Get wallet info"
+```
+
+Shows: wallet address, network, API URL.
+
+---
+
+*Back to: [SKILL.md](../SKILL.md)*