bitget-wallet

What this skill does

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

| Business Domain | Must Load First | Before Calling |
|----------------|----------------|----------------|
| Swap / Trade | [`docs/swap.md`](docs/swap.md) | quote, confirm, make-order, send, get-order-details |
| Market Data / Token Analysis | [`docs/market-data.md`](docs/market-data.md) | coin-market-info, security, coin-dev, kline, tx-info, liquidity, rankings, launchpad-tokens, search-tokens-v3 |
| Alpha Intelligence | [`docs/alpha.md`](docs/alpha.md) | alpha-gems, alpha-signals, alpha-hunter-find, alpha-hunter-detail, agent-alpha-tags, agent-alpha-hunter-find, multi-agent-signal |
| Token Deep Analysis | [`docs/token-analyze.md`](docs/token-analyze.md) | simple-kline, trading-dynamics, transaction-list, holders-info, profit-address-analysis, top-profit, compare-tokens |
| Address Discovery | [`docs/address-find.md`](docs/address-find.md) | recommend-address-list |
| Wallet / Signing | [`docs/wallet-signing.md`](docs/wallet-signing.md) | Any signing operation, key derivation, order_sign.py, order_make_sign_send.py |
| Social Login Wallet | [`docs/social-wallet.md`](docs/social-wallet.md) | social-wallet.py sign_transaction, sign_message, get_address |
| RWA Stock Trading | [`docs/rwa.md`](docs/rwa.md) | Any RWA stock discovery, config, order, holdings |
| x402 Payments | [`docs/x402-payments.md`](docs/x402-payments.md) | x402_pay.py, HTTP 402 payment flow |
| Token Transfer / Gasless | [`docs/transfer.md`](docs/transfer.md) | transfer_make_sign_send.py, social_transfer_make_sign_send.py, get-transfer-order |
| First-Time Setup | [`docs/first-time-setup.md`](docs/first-time-setup.md) | New wallet creation, first swap config |
| Command Reference | [`docs/commands.md`](docs/commands.md) | When unsure about subcommand parameters or usage |

**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>
   ```

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.
   ```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`](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

| Use Case | Command | Description |
|----------|---------|-------------|
| Scan new pools | `launchpad-tokens` | Filter by platform/stage/MC/LP/holders/progress |
| Search tokens | `search-tokens-v3` | Keyword or contract search with ordering |
| Rankings | `rankings` | topGainers / topLosers / Hotpicks |
| New launches | `historical-coins` | Discover tokens by timestamp, paginated |

**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

| Use Case | Command | Description |
|----------|---------|-------------|
| Security audit | `security` | Honeypot/mint/proxy + buy/sell tax + risk level |
| Dev analysis | `coin-dev` | Dev's historical projects + rug status + migration info |
| Market overview | `coin-market-info` | Price/MC/FDV/pool list/price changes/narratives |
| Token info | `token-info` | Basic info + social links |
| K-line | `kline` | OHLC + buy/sell volume |
| Tx stats | `tx-info` | Buy/sell volume and trader count |
| Liquidity | `liquidity` | Pool details |

**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`](docs/market-data.md).

### bgw_alpha — Alpha Intelligence

**Use when:** User asks for AI-curated token picks, alpha signals, smart money address discovery, or b