bitget-wallet-ai-lab/bitget-wallet-skill/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.

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

1. 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.

``bash 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: Chosen automatically by the server based on the sender's native-coin balance — there is no CLI flag to request or force it. The scripts never send gasAccountSelected; check the response's data.gasAccount.selected to see which path was taken. Gasless requires token transfers (not native coin). Availability per chain/token/amount is not guaranteed — if it's unavailable and the sender also has no native gas, the transfer will fail; inform the user rather than silently retrying.