bitget-wallet

What this skill does

# Bitget Wallet Skill

Bitget Wallet is a **multi-chain crypto wallet** with unified APIs for balance, swap, market data, token analysis, RWA stock trading, and Social Login signing. Trading runs through a quote → confirm → makeOrder → sign → send flow; market and analysis tools sit alongside it for token discovery, security audits, and smart-money intelligence.

---

## Key Constants

Always use these exact values. Do not guess or substitute.

| Constant | Value |
|----------|-------|
| API base URL | `https://copenapi.bgwapi.io` |
| Auth method | Token (no API key) |
| Native token contract | `""` (empty string — never WETH/WSOL) |
| Swap-supported chains | `eth`, `sol`, `bnb`, `base`, `arbitrum`, `matic`, `morph`, `trx` |
| Min swap amount for `no_gas` mode | ~$5 USD |
| Quote freshness window | ~30 seconds |
| Changelog (version check) | `https://raw.githubusercontent.com/bitget-wallet-ai-lab/bitget-wallet-skill/main/CHANGELOG.md` |

---

## Tool Routing — Use This First

Before acting, look up the task here to know which script and command to use.

| Task | Correct tool |
|------|--------------|
| Check wallet balance (any chain, incl. Tron) | `bitget-wallet-agent-api.py batch-v2` |
| Pre-swap balance + gas check | `bitget-wallet-agent-api.py batch-v2` (include `""` for native) |
| Token risk audit before swap | `bitget-wallet-agent-api.py check-swap-token` |
| Get swap quote | `bitget-wallet-agent-api.py quote` |
| Confirm swap (slippage, gas mode) | `bitget-wallet-agent-api.py confirm` |
| Execute swap (mnemonic / private key) | `order_make_sign_send.py` |
| Execute swap (Social Login Wallet) | `social_order_make_sign_send.py` |
| Query order status | `bitget-wallet-agent-api.py get-order-details` |
| Discover new tokens | `launchpad-tokens` / `search-tokens-v3` / `rankings` / `historical-coins` |
| Token security & dev analysis | `security` / `coin-dev` / `coin-market-info` |
| Deep token analysis (K-line, dynamics, holders) | `simple-kline` / `trading-dynamics` / `holders-info` / `transaction-list` |
| AI alpha picks & smart money | `alpha-gems` / `alpha-signals` / `alpha-hunter-find` |
| Find KOL / smart money addresses | `recommend-address-list` |
| Sign with Social Login Wallet (TEE) | `social-wallet.py` |
| HTTP 402 / x402 payments | `x402_pay.py` |
| RWA stock discovery & trading | See [`docs/rwa.md`](docs/rwa.md) |

> Trading commands (`quote`, `confirm`, `make-order`, `send`) **always** route through `bitget-wallet-agent-api.py` or the one-shot `order_make_sign_send.py` / `social_order_make_sign_send.py` wrappers. There are no other entry points.

---

## Prerequisites — Check Before Any Action

1. **Domain knowledge loaded?** Read the relevant `docs/*.md` file from the table in **Step 1** *before* any API call in that domain. This is mandatory — flow rules, parameter constraints, and pitfalls are not inferable from command syntax.
2. **Wallet configured?** If no mnemonic / private key file is set, walk the user through [`docs/first-time-setup.md`](docs/first-time-setup.md). For Social Login, verify `<skill_dir>/.social-wallet-secret` exists.
3. **Wallet funded?** Run `batch-v2` for the from-token AND native token (`""`). If balance is insufficient, tell the user the shortfall and stop.

---

## Step 1 — Load Domain Knowledge (Mandatory)

**Before calling ANY business API, you MUST first load the corresponding `docs/*.md` file for that domain.** This is non-negotiable. The `docs/` files are the authoritative source — the tables in this SKILL.md are summaries only.

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

> When an API call returns an error, **re-read the corresponding `docs/*.md` file** before retrying. Most errors are already documented there.

---

## Step 2 — Pre-Swap Checks (Mandatory Before Every Swap)

### 2a. Balance check

Verify the wallet has enough fromToken AND native token (for gas).

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

If `fromToken balance < fromAmount` → tell the user the shortfall and **stop**.

**Gas mode decision:**

| Native balance | Use | Notes |
|----------------|-----|-------|
| Sufficient for gas | `--feature user_gas` | Preferred |
| Near zero | `--feature no_gas` | Gasless. **Requires swap amount ≥ ~$5 USD**. Below that, the API only returns `user_gas`. |

This choice must be passed to `confirm`.

### 2b. Token risk check

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

| Result | What to do |
|--------|------------|
| `error_code != 0` | Show `msg`, stop |
| `data.list[].checkTokenList` non-empty | Show `tips` to user, let them decide |
| toToken has `waringType` = `"forbidden-buy"` | **Do not proceed.** Warn the user this token cannot be a swap target. |

---

## Step 3 — Execute a Swap

> All trading must follow the full flow in [`docs/swap.md`](docs/swap.md). No shortcuts.

### Swap lifecycle

```
balance check → token risk check → quote → display + user picks market →
confirm (show outAmount/minAmount/gasTotalAmount) → user explicit confirm →
makeOrder + sign + send (atomic) → get-order-details
```

| Step | Command | Notes |
|------|---------|-------|
| 1. Quote | `bitget-wallet-agent-api.py quote` | Show **all** market results, recommend the first, let user choose |
| 2. Confirm | `bitget-wallet-agent-api.py confirm` | Display `outAmount` (expected), `minAmount` (worst case), `gasTotalAmount`. Check `recommendFeatures` for gas sufficiency |
| 3. **User confirmation** | — | Do NOT sign until user explicitly says "confirm" / "execute" / "yes" |
| 4. makeOrder + sign + send | `order_make_sign_send.py` (mnemonic) **or** `social_order_make_sign_send.py` (Social Login) | Atomic — avoids 60s expiry |
| 5. Status | `bitget-wallet-agent-api.py get-order-details` | Ignore `tips` when status = success |

### Swap example (mnemonic / private key wallet)

```bash
# Quote
python3 scripts/bitget-wallet-agent-api.py quote \
  --from-chain bnb --from-contract <addr> --from-symbol USDT --from-amount 5 \
  --to-chain bnb --to-contract "" --to-symbol BNB \
  --from-address <wallet> --to-address <wallet>

# Confirm
python3 scripts/bitget-wallet-agent-api.py confirm \
  ... --market <id> --protocol <proto> --slippage <val> --feature user_gas

#