bitget-wallet-skill
# Bitget Wallet Skill ## Overview An AI Agent skill that wraps the [Bitget Wallet API](https://web3.bitget.com/en/docs), enabling natural-language-driven on-chain data queries and swap operations. ### Design Principles | Principle | Description | |-----------|-------------| | **Domain Knowledge + Tools** | Not just API wrappers — includes swap flow (see `docs/swap.md`), signing guides, security models, and known pitfalls so agents make informed decisions | | **Zero External Dependencies** | All code is self-contained. Solana signing is pure Python (Ed25519 + base58 built-in). EVM signing uses `eth_account` (standard). Only `requests` for API calls. No pip install needed for Solana | | **API Infrastructure, Not Reimplementation** | Capabilities come from Bitget Wallet's production API. The skill provides the knowledge and tooling layer, not a parallel implementation | | **Human-in-the-Loop by Default** | Swap operations generate transaction data but never sign autonomously. User confirmation required for all fund-moving actions | ### Market Tools Architecture Market side handles **token discovery and analysis only** — no trading, wallet, or signing. Skills layer computes scores and rules; backend provides raw data. ``` Atomic Tools (Agent orchestrates) ├── bgw_token_find Find tokens (chain scan / search / rankings / sectors) ├── bgw_token_check Check tokens (security / dev / anti-manipulation / signals / market) ├── bgw_token_analyze Analyze tokens (deep: timeline / trades / holdings / smart money) ├── bgw_alpha Alpha intelligence (gems / signals) ├── bgw_address_find Find addresses (by pool / role / criteria) └── bgw_address_analyze Analyze addresses (scoring / PnL / style / operations / comparison) Smart Tools (We orchestrate) ├── bgw_combo Smart combos (token + address permutation recipes) └── bgw_monitor Continuous monitoring (token signals / address activity / price alerts) ``` ### Core Capabilities | Capability | Description | Example | |------------|-------------|---------| | **Launchpad Scanner** | Scan new pools (pump.fun, four.meme, etc.) with 15+ filters | "Scan pump.fun for launching tokens with >$10K MC" | | **Token Search (v3)** | Search by keyword/contract with market_cap ordering + risk_level | "Find PEPE on ETH sorted by market cap" | | **Token Market Info** | Price, MC, FDV, liquidity, 57 pool pairs, narratives, price changes | "Show me full market info for Lobstar" | | **Dev Analysis** | Dev address, rug history, LP lock, holdings, migration history | "Check this token's dev history" | | **Security Audit** | Honeypot/mint/proxy + buy/sell tax + risk checks (EVM & Solana) | "Is this contract safe?" | | **K-line + Smart Signals** | K-line with KOL/smart money trade markers + hot level | "Show me smart money activity on this token" | | **Trading Dynamics** | Multi-window buy/sell pressure + address quality + wash detection | "What's the trading activity like?" | | **Transaction Analysis** | Tagged transactions (smart money/KOL/dev) with filtering | "Show me KOL trades on this token" | | **Holder Analysis** | Top100 distribution + PnL + tag classification (CEX/smart/KOL) | "Who's holding this token?" | | **Smart Money Analysis** | Profitable address stats + top earners list | "Are smart money addresses in profit?" | | **Token Comparison** | Side-by-side K-line comparison of two tokens | "Compare BONK vs WIF price action" | | **Address Discovery** | Find KOL / smart money addresses by role with performance filters | "Find top smart money on Solana with >80% win rate" | | **Social Login Wallet** | Sign transactions/messages via Bitget Wallet TEE — no local private key needed | "Sign this transaction with my Bitget Wallet" | | **Balance Query** | On-chain balance per chain/address/token (native + ERC-20/SPL) | "What's my BNB balance?" | | **Balance + Price** | Batch balance with USD price in one call | "What's my portfolio worth?" | | **Token Info** | Price, market cap, holders, social links | "What's the price of SOL?" | | **K-line Data** | 1m/5m/1h/4h/1d candlestick data with buy/sell breakdown | Trend analysis, buying pressure | | **Transaction Stats** | 5m/1h/4h/24h buy/sell volume & trader count | Activity detection, whale monitoring | | **Rankings** | Top gainers / top losers / Hotpicks (curated trending) | Market scanning, alpha discovery | | **Liquidity Pools** | LP pool information | Slippage estimation, depth analysis | | **Historical Coins** | Discover new tokens by timestamp (paginated) | "What tokens launched today?" | | **Token Risk Check** | Pre-swap safety check for from/to tokens (forbidden-buy detection) | "Is this token safe to buy?" | | **Swap Quote** | Multi-market quotes for same-chain/cross-chain swaps | "How much USDC for 1 SOL?" | | **Swap Confirm** | Final quote from selected market with orderId | Lock in price and route | | **Swap MakeOrder** | Generate unsigned transaction data for signing | Execute trades via wallet signing | | **Swap Send** | Submit signed transactions | Broadcast with MEV protection | | **Order Details** | Track order lifecycle (processing→success/failed) | "Check my swap status" | | **Token Transfer** | Direct on-chain token transfer (EVM + Solana), server broadcasts | "Send 100 USDT to 0xDeF..." | | **Gasless Transfer** | Transfer tokens without native gas — gas paid from USDT/USDC balance | "Send USDC on Base with no ETH for gas" | | **x402 Payment** | Pay for x402-enabled APIs with USDC on Base | "Access this paid API endpoint" | > ⚠️ **Swap amounts are human-readable** — pass `0.1` for 0.1 USDT, NOT `100000000000000000`. The `toAmount` in responses is also human-readable. This differs from most on-chain APIs. ### ✨ Order Mode — Gasless & Cross-Chain Swaps The swap flow enables two capabilities no other AI agent swap skill offers: **⛽ Gasless Transactions (EIP-7702)** - Swap tokens with **zero native token balance** — no ETH, no BNB, no MATIC needed - Gas cost is deducted from the input token automatically - Agent only signs; a backend relayer pays gas and broadcasts the transaction - Supported on all EVM chains (Ethereum, Base, BNB Chain, Arbitrum, Polygon, Morph) **🌉 One-Step Cross-Chain Swaps** - Swap tokens across different chains in a **single order** — no manual bridging - Example: USDC on Base → USDT on BNB Chain, one API call, one signature - Combined with gasless: cross-chain swap with zero gas on the source chain **How it works:** ``` 1. quote → Get multi-market quotes 2. confirm → Final quote from chosen market, get orderId 3. makeOrder → Create unsigned transaction data 4. Sign → Agent signs with wallet key 5. send → Submit signed data 6. getOrderDetails → Track until success ``` **Example — Same-chain swap:** ```bash # Quote: BNB USDT → USDC python3 scripts/bitget-wallet-agent-api.py quote \ --from-chain bnb --from-contract 0x55d398326f99059fF775485246999027B3197955 \ --from-symbol USDT --from-amount 5 \ --to-chain bnb --to-contract 0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d \ --to-symbol USDC \ --from-address 0xYourAddress --to-address 0xYourAddress # Confirm with chosen market python3 scripts/bitget-wallet-agent-api.py confirm \ --from-chain bnb --from-contract 0x55d398326f99059fF775485246999027B3197955 \ --from-symbol USDT --from-amount 5 \ --to-chain bnb --to-contract 0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d \ --to-symbol USDC \ --from-address 0xYourAddress --to-address 0xYourAddress \ --market bgwevmaggregator --protocol bgwevmaggregator_v000 \ --slippage 0.01 --feature user_gas ``` ### 💳 x402 Payments — Pay-Per-Request API Access x402 is an open standard for HTTP-native payments. When an agent encounters a paid API (HTTP 402), it signs a USDC authorization and retries — no accounts, no API keys needed. **How it works:** ``` 1. Agent requests a resource → gets HTTP 402 + payment requirements 2. Agent signs EIP-3009 TransferWithAuthorization (gasless, off-chain) 3. Agent retries with PAYMENT-SIGNATURE header 4. Service's facilitator settles on-chain → agent gets the resource ``` **Key features:** - **Truly gasless** — agent pays only USDC, facilitator sponsors gas - **No accounts needed** — wallet address is your identity - **Works with any x402 service** — Pinata IPFS, DiamondClaws DeFi data, and [100+ more](https://www.x402.org/ecosystem) ```bash # Example: pay $0.001 for Pinata IPFS upload python3 scripts/x402_pay.py pay \ --url "https://402.pinata.cloud/v1/pin/private?fileSize=100" \ --private-key <key> --method POST --data '{"fileSize": 100}' --auto ``` See [`docs/x402-payments.md`](docs/x402-payments.md) for domain knowledge, signing details, and testing guide. ### 💸 Gasless Token Transfer Direct on-chain token transfer where the server handles transaction construction, broadcasting, and tracking. Supports **gasless mode** — gas fees paid from stablecoin balance (USDT/USDC) instead of native tokens. **How it works:** ``` transfer_make_sign_send.py / social_transfer_make_sign_send.py → makeTransferOrder + sign + submitTransferOrder (one shot) → poll getTransferOrder until SUCCESS or FAILED ``` **Key features:** - **Gasless (EIP-7702 / FeePayer)** — transfer tokens with zero native gas. Gas deducted from USDT/USDC balance - **Multi-chain** — ETH, BNB, Base, Arbitrum, Polygon, Morph, Solana - **Server-side broadcast** — client only signs, server handles nonce management and chain tracking - **Explicit fallback** — if gasless is unavailable, prompts for confirmation before falling back to standard transfer ```bash # Standard EVM token transfer python3 scripts/transfer_make_sign_send.py --private-key-file /tmp/.pk_evm \ --chain eth --contract 0xdAC17F958D2ee523a2206206994597C13D831ec7 \ --from-address 0xAbC... --to-address 0xDeF... --amount 100 # Gasless transfer (no ETH needed for gas) python3 scripts/transfer_make_sign_send.py --private-key-file /tmp/.pk_evm \ --chain base --contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \ --from-address 0xAbC... --to-address 0xDeF... --amount 50 --gasless # Poll status python3 scripts/bitget-wallet-agent-api.py get-transfer-order --order-id <orderId> ``` See [`docs/transfer.md`](docs/transfer.md) for domain knowledge, signing modes, and gasless details. ### Supported Chains Ethereum · Solana · BNB Chain · Base · Arbitrum · Tron · TON · Sui · Optimism and more. --- ## Architecture ``` Natural Language Input ↓ AI Agent (OpenClaw / Dify / Custom) ↓ bitget-wallet-agent-api.py (Python 3.9+) ↓ ← Token auth (no API key needed) Bitget Agent API (copenapi.bgwapi.io) ↓ Structured JSON → Agent interprets → Natural language response ``` **Security by Design:** - No API key or HMAC signing needed — uses token-based authentication - Swap calldata generates transaction data; signing requires explicit wallet key access - **Wallet key management:** mnemonic stored in secure storage, private keys derived on-the-fly and discarded after each signing operation (never persisted) --- ## Agent Use Cases ### 1. Personal Research Assistant > "Check if this Solana meme coin is safe, and give me a price quote." - Token info + security audit + price in a single query - For: individual traders, researchers - Platforms: Telegram Bot, Discord Bot, OpenClaw ### 2. Portfolio Management Agent > "What's my total portfolio value right now?" - Batch query across chains and tokens, calculate net value - Scheduled snapshots + K-line data for historical tracking - For: DeFi users, fund managers - Platforms: OpenClaw cron + Telegram alerts ### 3. Market Monitoring / Alert Agent > Automatically scan top gainers, detect anomalies, push alerts - Rankings + transaction volume + security audit combined - Discover trending tokens → auto-run security audit → filter honeypots → notify user - For: on-chain alpha hunters - Platforms: Cron jobs, Dify workflows ### 4. Semi-Automated Trading Agent > "Buy this token with 1 SOL" - Swap quote → show route and slippage → user confirms → generate calldata → wallet signs - **Human-in-the-loop** — the agent cannot sign independently - For: active traders wanting an AI assistant - Platforms: OpenClaw + Bitget Wallet App / hardware wallet ### 5. Arbitrage Bot Data Layer > Monitor DEX price discrepancies, discover cross-chain arbitrage opportunities - Multi-chain swap-quote comparison, calculate spreads - Combine with CEX data for DEX-CEX spread monitoring - For: quant teams - Platforms: Custom Python scripts, OpenClaw sub-agents ### 6. Community Service Bot > Someone asks "How much is XX coin?" in a group chat — bot auto-replies - Lightweight queries, fast response - Security audit feature doubles as anti-scam protection - For: Telegram/Discord communities - Platforms: Telegram Bot + OpenClaw skill ### 7. Dify / LangChain Tool Node > Integrate as a Tool in Dify workflows or LangChain agents - `bitget-wallet-agent-api.py` can serve directly as a Dify Code node or external API Tool - Can also be wrapped as an MCP Server for any MCP-compatible agent framework - For: enterprise agent platform integration --- ## Quick Start ### Prerequisites 1. Python 3.9+ 2. `requests` library (`pip install requests`) 3. For EVM signing: `eth-account` (`pip install eth-account`) > No API key needed — the Agent API uses token-based authentication with built-in headers. > Solana signing requires **no additional packages** — pure Python Ed25519 and base58 are built into `order_sign.py`. ### Examples ```bash # Get SOL price python3 scripts/bitget-wallet-agent-api.py token-price --chain sol --contract "" # Security audit for a token python3 scripts/bitget-wallet-agent-api.py security --chain sol --contract <contract_address> # Swap quote (5 USDT → USDC on BNB Chain) python3 scripts/bitget-wallet-agent-api.py quote \ --from-chain bnb --from-contract 0x55d398326f99059fF775485246999027B3197955 \ --from-symbol USDT --from-amount 5 \ --to-chain bnb --to-contract 0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d \ --to-symbol USDC \ --from-address 0xYourAddress --to-address 0xYourAddress ``` --- ## Supported Chains (Swap) | Chain | Same-chain | Cross-chain | Gasless | |-------|-----------|-------------|---------| | Ethereum | ✅ | ✅ | ✅ | | BNB Chain | ✅ | ✅ | ✅ | | Base | ✅ | ✅ | ✅ | | Arbitrum | ✅ | ✅ | ✅ | | Polygon | ✅ | ✅ | ✅ | | Morph | ✅ | ✅ | ✅ | | Solana | ✅ | ✅ | ✅ | | Tron | ✅ | ✅ | ✅ | > Market data commands support 32+ chains. See `docs/market-data.md` for the full list. ## Future Directions | Direction | Description | |-----------|-------------| | **Solana Advanced Swaps** | Solana gasless ✅ and cross-chain ✅ now fully supported (same-chain + Sol↔EVM) | | **On-chain Event Subscription** | WebSocket listeners for large transactions, new pool creation | | **Historical Data Cache** | Store K-line + price data in local SQLite to reduce API calls | | **Multi-wallet Management** | Support multi-address balance queries and batch quotes | | **Risk Rule Engine** | Security audit results + custom rules (blacklist, min liquidity thresholds) | --- ## Compatible Platforms ### ✅ Tested & Verified | Platform | Status | Notes | |----------|--------|-------| | [OpenClaw](https://openclaw.ai) | ✅ Passed | Native skill support | | [Manus](https://manus.im) | ✅ Passed | Auto-installed and executed | | [Bolt.new](https://bolt.new) | ✅ Passed | Auto-cloned repo, ran all commands | | [Devin](https://devin.ai) | ✅ Passed | Read SKILL.md, installed deps, returned correct data | | [Replit Agent](https://replit.com) | ✅ Passed | Full project setup with web frontend | ### 🔧 Should Work (file system + Python + network access) | Platform | Type | How to Use | |----------|------|------------| | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | CLI Agent | Clone repo, add SKILL.md to project context | | [Codex CLI](https://github.com/openai/codex) | CLI Agent | Clone repo, reference in AGENTS.md | | [Cursor](https://cursor.com) | IDE Agent | Clone into project, or use [MCP version](https://github.com/bitget-wallet-ai-lab/bitget-wallet-mcp) | | [Windsurf](https://codeium.com/windsurf) | IDE Agent | Clone into project, or use [MCP version](https://github.com/bitget-wallet-ai-lab/bitget-wallet-mcp) | | [Cline](https://github.com/cline/cline) | VS Code Agent | Clone into project workspace | | [Aider](https://aider.chat) | CLI Agent | Add scripts to project | | [OpenHands](https://github.com/All-Hands-AI/OpenHands) | Coding Agent | Docker sandbox with full file system | | [SWE-agent](https://github.com/princeton-nlp/SWE-agent) | Coding Agent | Shell access in sandbox | | [Dify](https://dify.ai) | Workflow Platform | Use as Code node or external API Tool | | [Coze](https://www.coze.com) | Agent Platform | Import as plugin or API Tool | | [LangChain](https://langchain.com) / [CrewAI](https://crewai.com) | Frameworks | Wrap `bitget-wallet-agent-api.py` as a Tool | ### 💡 Compatibility Rule Any AI agent that can **read files + run Python + access the internet** should work with this skill. --- ## Related Projects - [bitget-wallet-mcp](https://github.com/bitget-wallet-ai-lab/bitget-wallet-mcp) — MCP Server for Claude Desktop / Cursor / Windsurf - [bitget-wallet-cli](https://github.com/bitget-wallet-ai-lab/bitget-wallet-cli) — CLI tool for terminal users --- ## Security Notes - No API keys needed — uses token-based authentication (no secrets to manage) - Swap functions generate quotes and transaction data — signing requires explicit wallet access - Wallet mnemonic is the only persistent secret; private keys are derived per-operation and discarded - Large operations require explicit user confirmation (human-in-the-loop) - Always run a security audit (`security` command) before interacting with any token ## Security - **Zero external dependencies for Solana** — pure Python Ed25519 (RFC 8032) and base58 built into `order_sign.py`. EVM uses `eth_account`. No obscure packages, no supply-chain risk. - Only communicates with `https://copenapi.bgwapi.io` (Agent API) and x402 resource servers — no other external endpoints - No `eval()` / `exec()` or dynamic code execution - No file system access outside the skill directory - No data collection, telemetry, or analytics - No access to sensitive files (SSH keys, credentials, wallet files, etc.) - We recommend auditing the source yourself before installation ## License MIT