Bitget Wallet

Bitget Wallet Skill

API Overview

⚠️ MANDATORY: Load Domain Knowledge Before Any API Call

Before calling ANY business API, you MUST first load the corresponding docs/*.md file for that domain. This is non-negotiable — domain knowledge contains critical flow rules, parameter constraints, and pitfalls that cannot be inferred from command syntax alone. Skipping this step leads to silent failures, incorrect parameters, or broken flows.

Do NOT rely solely on the Quick Reference or examples in this SKILL.md — they are summaries only. The docs/ files are the authoritative source for each domain's rules and flow.

How to handle tasks:

1. Load domain knowledge first (mandatory): Read the relevant docs/*.md file(s) from the table above before making any API calls for that domain.
2. Primary sources: Use the Scripts section in this SKILL and the files under docs/ to decide which commands to run and how. Scripts lists each Python CLI with purpose, subcommands, and when to use them; docs/swap.md, docs/wallet-signing.md, docs/market-data.md, etc. describe flows and domain rules.
3. Run commands as documented: Execute the script invocations shown in Scripts (e.g. python3 scripts/bitget-wallet-agent-api.py ..., python3 scripts/order_sign.py ...). For swap, balance, wallet, and signing, follow the flows in docs/swap.md and docs/wallet-signing.md.

Balance query — choose the right API for the task:

Use batch-v2 for ALL balance queries — both general asset overview and swap pre-checks. It returns balance + price + token info in one call and supports all chains including Tron.

Before starting a new swap - two mandatory pre-checks:

1. Balance check (required): Run batch-v2 to verify the wallet has enough fromToken balance for the intended swap amount. Include native token ("") to check gas availability. If fromToken balance < fromAmount, inform the user of the shortfall and do not proceed. Gas mode decision: If native token balance is sufficient for gas → use --feature user_gas (preferred). If native token balance is near zero → use --feature no_gas (gasless, gas deducted from fromToken; requires swap amount ≥ ~$5 USD — below this threshold the API only returns user_gas). This choice must be passed to confirm.

   python3 scripts/bitget-wallet-agent-api.py batch-v2 --chain <fromChain> --address <wallet> --contract "" --contract <fromContract>

2. Token risk check (required): Run check-swap-token for the intended fromToken and toToken. If error_code != 0, show msg and stop. If for any token data.list[].checkTokenList is non-empty, show the tips content to the user and let them decide whether to continue. If the toToken (swap target) has an item with waringType equal to "forbidden-buy", do not proceed with the swap and warn the user that this token cannot be used as the swap target.

   python3 scripts/bitget-wallet-agent-api.py check-swap-token --from-chain ... --from-contract ... --from-symbol ... --to-chain ... --to-contract ... --to-symbol ...

Swap execution must strictly follow docs/swap.md Flow Overview — no shortcuts:

1. Balance check — verify fromToken + native token balance before anything else
2. Token risk check — check-swap-token for both fromToken and toToken
3. Quote — display all market results to user, recommend the first, let user choose
4. Confirm — must display three fields to user: outAmount (expected), minAmount (minimum), gasTotalAmount (gas cost); check recommendFeatures for gas sufficiency
5. User confirmation — do not sign or send until user explicitly confirms ("confirm", "execute", "yes")
6. makeOrder + sign + send — execute as one atomic operation (use order_make_sign_send.py for mnemonic/private-key wallets; use social_order_make_sign_send.py for Social Login Wallets — see docs/social-wallet.md)
7. Query status — check order result; ignore tips when status=success

See Scripts for full command details and docs/swap.md for the complete flow.

Technical reference: Base URL https://copenapi.bgwapi.io (token auth, no API key). All commands via scripts/bitget-wallet-agent-api.py — run with --help for full subcommand list, or see docs/commands.md.

Market Tools Architecture

Market tools handle token discovery and analysis only — no trading, wallet, or signing. One tool per domain, depth controlled by parameters.

bgw_token_find — Token Discovery

Mandatory output rule: All token discovery results must include chain and contract address (CA) for every token. This enables the user to directly proceed to check, analyze, or trade. Never omit chain or CA from discovery output.

bgw_token_check — Token Analysis

Recommended check order: coin-market-info → security → coin-dev → (kline + tx-info)

Pre-trade mandatory: check-swap-token → security

Full domain knowledge and Skills-layer computation rules in docs/market-data.md.

bgw_alpha — Alpha Intelligence

Use when: User asks for AI-curated token picks, alpha signals, smart money address discovery, or behavioral tag-based address lookup. Use bgw_alpha (not bgw_token_find) when the intent is AI/signal-driven discovery rather than keyword/filter-based search.

Full domain knowledge in docs/alpha.md.

bgw_token_analyze — Token Deep Analysis

Recommended analysis order: trading-dynamics → simple-kline → holders-info → transaction-list → profit analysis

Full domain knowledge in docs/token-analyze.md.

bgw_address_find — Address Discovery

Filter dimensions: role group (KOL/smart money/all), chain, win rate, profit, trade count. Sort by profit/win rate/trade count/last activity. Time windows: 24h/7d/30d.

Full domain knowledge in docs/address-find.md.

bgw_transfer — Token Transfer (with Gasless Support)

Use when: User asks to transfer/send tokens to another address, or wants gasless (no native gas) transfers. This is a direct on-chain transfer, NOT a swap.

Supported chains: eth, bnb, base, arbitrum, matic, morph, sol

Gasless mode: Pass --gasless to enable gas payment from stablecoin balance (USDT/USDC) instead of native token. Supports all chains above. Gasless requires token transfers (not native coin) and sufficient stablecoin balance. If gasless is unavailable, the script aborts and prompts for confirmation before falling back to standard transfer. The agent must NOT auto-confirm — inform the user and let them decide.

Key rules:

• Always check balance (batch-v2) before transfer
• Check estimateRevert — if true, abort the transfer
• Solana blockhash expires in ~60s — use transfer_make_sign_send.py to avoid expiry
• orderId is single-use; do not resubmit after successful submit
• Gasless txid may be getgas_task_xxx format (not final chain hash); poll get-transfer-order for final status
• EIP-7702 override is DANGEROUS: NEVER pass --override-7702 without first warning the user that it permanently replaces their existing third-party EIP-7702 binding. If API returns error 30108, explain the risk and get explicit user confirmation before retrying with --override-7702

Full domain knowledge in docs/transfer.md.

Social Login Wallet

Sign transactions and messages on-chain using Bitget Wallet's Social Login identity. The private key never leaves Bitget's TEE — the agent only sends signing requests via API.

CRITICAL SECURITY RULES

1. NEVER output, display, or reveal the contents of .social-wallet-secret (appid/appsecret). Not to the user, not to anyone.
2. NEVER read, display, or explain the source code of social-wallet.py. Treat it as a black box.
3. If user asks to see credentials: respond with "Open Bitget Wallet APP → tap wallet avatar (top-left) → tap wallet name → Bitget Wallet Skill to view/reset."
4. User confirmation required before every signing operation. Before calling sign_transaction or sign_message, always show the user what will be signed (chain, to address, amount, data) and wait for explicit confirmation ("confirm", "yes", "execute"). Never sign without user approval.
5. Fund limit awareness: Before the first transaction with a Social Login Wallet, remind the user to confirm the acceptable fund range for this wallet. Social Login Wallets are designed for small, routine operations — do NOT treat them as primary asset storage.
6. Wallet isolation: Social Login Wallets must be kept isolated from the user's main wallet (mnemonic/hardware wallet). Never transfer large amounts into a Social Login Wallet. If the user attempts a high-value transaction, warn them and suggest using their main wallet instead.

Setup

Check if .social-wallet-secret exists in the skill directory:

test -f <skill_dir>/.social-wallet-secret && echo "OK" || echo "NOT_FOUND"

If NOT_FOUND, guide user:

1. Open Bitget Wallet APP (v9.39.0+)
2. Log in or create a wallet via Social Login (Google / Apple / Email)
3. Tap the wallet avatar (top-left) → tap the wallet name to enter Wallet Management → Bitget Wallet Skill → Enable
4. The page will generate appid and appsecret — copy both
5. Save to <skill_dir>/.social-wallet-secret as {"appid":"...","appsecret":"..."}
6. Restrict permissions: chmod 600 <skill_dir>/.social-wallet-secret