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.

| 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, ordersign.py, ordermakesignsend.py | | Social Login Wallet | [docs/social-wallet.md](docs/social-wallet.md) | social-wallet.py signtransaction, signmessage, getaddress | | 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) | x402pay.py, HTTP 402 payment flow | | Token Transfer / Gasless | [docs/transfer.md](docs/transfer.md) | transfermakesignsend.py, socialtransfermakesign_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 --address --contract "" --contract

```

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

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

bgwtokencheck — 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 behavioral tag-based address lookup. Use bgwalpha (not bgwtoken_find) when the intent is AI/signal-driven discovery rather than keyword/filter-based search.

| Use Case | Command | Description | |----------|---------|-------------| | Alpha gems | alpha-gems | AI-curated high-potential tokens with strategy labels | | Alpha signals | alpha-signals | Smart money/KOL/growth signals with filtering | | Alpha hunter find | alpha-hunter-find | Smart money address list with multi-dimensional scoring | | Alpha hunter detail | alpha-hunter-detail | Detailed scoring factors for a specific address | | Agent alpha tags | agent-alpha-tags | List available Agent tag labels | | Agent alpha hunter find | agent-alpha-hunter-find | Find addresses by Agent tag with scores | | Multi-agent signal | multi-agent-signal | Tokens currently bought by Agent-tagged addresses (cross-strategy consensus) |

Full domain knowledge in [docs/alpha.md](docs/alpha.md).

bgwtokenanalyze — Token Deep Analysis

| Use Case | Command | Description | |----------|---------|-------------| | K-line + signals | simple-kline | K-line with KOL/smart money trade signals + hot level | | Trading dynamics | trading-dynamics | 4-window (5m/1h/4h/24h) buy/sell pressure + address quality | | Transactions | transaction-list | Tagged trades (smart money/KOL/dev), direction/time filtering | | Holders | holders-info | Top100 distribution + PnL + tag classification | | Profit analysis | profit-address-analysis | Profitable address stats + position dynamics | | Top profit | top-profit | Top profitable address list with PnL details | | Compare | compare-tokens | Side-by-side K-line comparison of two tokens |

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

Full domain knowledge in [docs/token-analyze.md](docs/token-analyze.md).

bgwaddressfind — Address Discovery

| Use Case | Command | Description | |----------|---------|-------------| | Find by role | recommend-address-list | Find KOL / smart money addresses with performance filters (win rate, profit, chain, trade count) |

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

| Use Case | Command / Script | Description | |----------|-----------------|-------------| | Transfer (mnemonic/private-key) | transfer_make_sign_send.py | makeTransferOrder + sign + submit in one run | | Transfer (Social Login Wallet) | social_transfer_make_sign_send.py | makeTransferOrder + sign (TEE) + submit. No local key needed. | | Poll status | get-transfer-order | Real-time chain query for order status |

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](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 /.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 /.social-wallet-secret as {"appid":"...","appsecret":"..."}
6. Restrict permissions: chmod 600 /.social-wallet-secret

Using Social Login Wallet with API Calls

When the user is using a Social Login Wallet, all bitget-wallet-agent-api.py calls must include --wallet-id to identify the wallet session. The walletId is obtained from the profile endpoint.

Step 1: Get walletId (once per session)

python3 scripts/social-wallet.py profile
# Returns: {"walletId": ""}

Step 2: Pass walletId to all API calls

python3 scripts/bitget-wallet-agent-api.py --wallet-id  batch-v2 --chain eth --address  --contract ""
python3 scripts/bitget-wallet-agent-api.py --wallet-id  quote --from-chain ... --to-chain ...
# ... all other commands

Without --wallet-id, the API uses the default toc_agent token (for mnemonic/private-key wallets). With --wallet-id, the API routes requests to the Social Login Wallet's backend identity.

Commands

# Get wallet profile (walletId)
python3 scripts/social-wallet.py profile

# Sign transaction (ETH/BTC/SOL/Tron + all EVM chains)
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 get 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](docs/social-wallet.md) for full chain list and per-chain parameters.

---

Domain Knowledge

Skill Domain Knowledge

Version

Date-based versioning (YYYY.M.DD-N). Current version in frontmatter. Check at most once per 7 days: compare frontmatter version against https://raw.githubusercontent.com/bitget-wallet-ai-lab/bitget-wallet-skill/main/CHANGELOG.md. If newer, inform user and ask to upgrade.

---

Wallet Domain Knowledge

> First-time wallet setup & swap configuration: See [docs/first-time-setup.md](docs/first-time-setup.md).

Key rules (always apply):

• On

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bitget-wallet-ai-lab
• Source: bitget-wallet-ai-lab/bitget-wallet-skill
• License: MIT
• Homepage: https://web3.bitget.com

Install and usage instructions live in the source repository linked above.