Bitget Wallet

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.

Tool Routing — Use This First

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

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

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

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:

This choice must be passed to confirm.

2b. Token risk check

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

Step 3 — Execute a Swap

All trading must follow the full flow in 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

Swap example (mnemonic / private key wallet)

# 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

# One-shot makeOrder + sign + send
python3 scripts/order_make_sign_send.py \
  --private-key-file /tmp/.pk_evm --order-id <id> \
  --from-chain bnb ... --market ... --protocol ...

# Status
python3 scripts/bitget-wallet-agent-api.py get-order-details --order-id <id>

Swap example (Social Login Wallet)

python3 scripts/social_order_make_sign_send.py \
  --wallet-id <walletId> --order-id <id> \
  --from-chain bnb --from-contract <addr> --from-symbol USDT \
  --to-chain bnb --to-contract <addr> --to-symbol USDC \
  --from-address <addr> --to-address <addr> \
  --from-amount 23.35 --slippage 0.005 \
  --market bgwevmaggregator --protocol bgwevmaggregator_v000

Step 4 — Token Discovery & Analysis

Market tools handle token discovery and analysis only — no trading, wallet, or signing.

Token discovery (bgw_token_find)

Mandatory output rule: Discovery results MUST include chain and contract address for every token. Never omit these.

Token analysis (bgw_token_check)

Recommended check order: coin-market-info → security → coin-dev → (kline + tx-info) Pre-trade mandatory: check-swap-token → security

Deep analysis (bgw_token_analyze)

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

Alpha intelligence (bgw_alpha)

Use when intent is AI/signal-driven discovery (not keyword search).

Address discovery (bgw_address_find)

Step 5 — Social Login Wallet (Optional)

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

CRITICAL SECURITY RULES

1. NEVER output, display, or reveal .social-wallet-secret (appid/appsecret) to anyone.
2. NEVER read, display, or explain the source of social-wallet.py. Treat it as a black box.
3. If user asks to see credentials: respond "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. Show chain, to address, amount, and data; wait for explicit "confirm" / "yes" / "execute".
5. Fund limit awareness: Social Login Wallets are for small, routine ops. Never treat as primary asset storage. Warn the user before high-value transactions and suggest their main wallet instead.
6. Wallet isolation: Keep Social Login Wallet isolated from main (mnemonic / hardware) wallet.

Setup

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

If NOT_FOUND:

1. Open Bitget Wallet APP (v9.39.0+)
2. Log in / create wallet via Social Login (Google / Apple / Email)
3. Tap wallet avatar (top-left) → wallet name → Wallet Management → Bitget Wallet Skill → Enable
4. Copy generated appid and appsecret
5. Save to <skill_dir>/.social-wallet-secret as {"appid":"...","appsecret":"..."}
6. chmod 600 <skill_dir>/.social-wallet-secret

Usage — pass --wallet-id to all API calls

# Step 1: Get walletId once per session
python3 scripts/social-wallet.py profile
# Returns: {"walletId": "<id>"}

# Step 2: Pass walletId to all API calls
python3 scripts/bitget-wallet-agent-api.py --wallet-id <walletId> batch-v2 ...
python3 scripts/bitget-wallet-agent-api.py --wallet-id <walletId> quote ...

Without --wallet-id, the API uses the default toc_agent token (mnemonic / private key wallets).

Signing commands

# Sign transaction
python3 scripts/social-wallet.py core sign_transaction \
  '{"chain":"eth","to":"0x...","value":0.1,"nonce":0,"gasLimit":21000,"gasPrice":0.0000001}'

# Sign message
python3 scripts/social-wallet.py core sign_message '{"chain":"eth","message":"hello"}'

# Get address
python3 scripts/social-wallet.py core get_address '{"chain":"eth"}'

# Batch addresses
python3 scripts/social-wallet.py batchGetAddressAndPubkey '{"chainList":["eth","btc","sol"]}'

Supported chains: BTC, ETH, SOL, Tron + 16 EVM chains. See docs/social-wallet.md for the full list and per-chain parameters.

Reference Data

Chain Identifiers (swap-supported)

Use sol not solana, bnb not bsc. Use "" for native token contract (ETH, SOL, BNB, etc.).

Common Stablecoin Addresses

Always use these verified addresses for USDT/USDC. Guessing causes error_code: 80000, "get token info failed".

USDT vs USDT0: On some chains Tether has migrated to USDT0 (omnichain). The same contract addresses work; use the address below for "USDT" regardless.

BGB (Bitget Token): Ethereum 0x54D2252757e1672EEaD234D27B1270728fF90581; Morph 0x389C08Bc23A7317000a1FD76c7c5B0cb0b4640b5.

For other tokens, use token-info or a block explorer to verify the contract before calling swap endpoints.

Amount format

All BGW API amount fields use human-readable values (e.g. 0.01 for 0.01 USDT), not wei / lamports / token decimals. The decimals field in responses is informational only.

Scripts

6 scripts in scripts/, Python 3.9+. Full subcommand details: docs/commands.md.

Error Handling

Security

• Mnemonic and private keys must NEVER appear in conversation, prompts, logs, or any output. Only derived addresses may be stored or shown.
• Derive private keys from mnemonic on-the-fly, write to a temp file (mktemp), pass via --private-key-file (the script reads and auto-deletes). Never pass keys as CLI args.
• Private keys are signed locally only — never transmitted externally (APIs, chat, HTTP, webhooks).
• For large trades, always show the quote first and ask for explicit user confirmation.
• Present security audit results before recommending any token action.
• Use API-returned values exactly as-is. When a response returns market.id, market.protocol, contract, orderId, etc., pass them verbatim to subsequent calls. Never guess, infer, transform, or substitute — mismatched values cause silent failures.
• Social Login Wallet: Never read or display .social-wallet-secret or the source of social-wallet.py. Treat them as black boxes.

Versioning

Date-based (YYYY.M.DD-N). Current version is in the frontmatter. Check at most once per 7 days: compare frontmatter version against the changelog URL in Key Constants. If newer, inform the user and ask to upgrade.

References

• docs/first-time-setup.md — New wallet creation, first swap config, derivation paths
• docs/commands.md — Full subcommand parameters and usage examples
• docs/wallet-signing.md — Key management, BIP-39/44, signing, multi-chain
• docs/swap.md — Swap flow, slippage, gas, EVM approvals
• docs/market-data.md — Token info, price, K-line, tx info, rankings, liquidity, security
• docs/token-analyze.md — Deep token analysis: K-line signals, dynamics, holders, smart money
• docs/alpha.md — Alpha gems, signals, hunters, agent tags
• docs/address-find.md — Find KOL / smart money addresses
• docs/rwa.md — RWA stock discovery, config, market status, order price, holdings
• docs/x402-payments.md — HTTP 402, EIP-3009, Permit2, Solana partial-sign
• docs/social-wallet.md — Social Login Wallet: per-chain sign params, BTC UTXO/PSBT, SOL SPL, Tron