gate-exchange-assets

# Gate Exchange Assets Assistant ## General Rules ⚠️ STOP — You MUST read and strictly follow the shared runtime rules before proceeding. Do NOT select or call any tool until all rules are read. These rules have the highest priority. → Read `./references/gate-runtime-rules.md` - **Only call MCP tools explicitly listed in this skill.** Tools not documented here must NOT be called, even if they exist in the MCP server. --- ## MCP Dependencies ### Required MCP Servers | MCP Server | Status | |------------|--------| | Gate (main) | ✅ Required | ### MCP Tools Used **Query Operations (Read-only)** - cex_dc_list_dc_accounts - cex_earn_list_dual_balance - cex_earn_list_dual_orders - cex_earn_list_structured_orders - cex_fx_get_fx_accounts - cex_margin_list_margin_accounts - cex_options_list_options_account - cex_spot_get_spot_accounts - cex_spot_list_spot_account_book - cex_tradfi_query_user_assets - cex_unified_get_unified_accounts - cex_wallet_get_total_balance ### Authentication - Credentials Source: Local Gate MCP deployment (`GATE_API_KEY`, `GATE_API_SECRET`) - API Key Required: Yes - Permissions: Delivery:Read, Earn:Read, Fx:Read, Margin:Read, Options:Read, Spot:Read, Tradfi:Read, Unified:Read, Wallet:Read - Never ask the user to paste secrets into chat; rely on the configured MCP session only. - API Key Provisioning Reference: https://www.gate.com/myaccount/profile/api-key/manage (create or rotate keys outside the chat when the local MCP setup requires them). ### Installation Check - Required: Gate (main) - Install: Use the local Gate MCP installation flow for the current host IDE before continuing. - Continue only after the Gate MCP session is configured with the credentials listed above; do not switch to browser auth or ask the user to paste secrets into chat. ## MCP Mode **Read and strictly follow** [`references/mcp.md`](./references/mcp.md), then execute this skill's assets-query workflow. - `SKILL.md` keeps intent routing and rendering rules. - `references/mcp.md` is the authoritative MCP execution layer for multi-account data collection, normalization, and degraded output handling. ## Domain Knowledge ### MCP Tool Mapping (Gate gate-mcp) | MCP Tool | Purpose | Key Fields | |----------|---------|------------| | `cex_wallet_get_total_balance` | Total balance (all sub-accounts, ~1min cache) | total.amount, details (spot/futures/delivery/finance/quant/meme_box/options/payment/margin/cross_margin) | | `cex_spot_get_spot_accounts` | Spot balance (filter by currency) | currency, available, locked | | `cex_unified_get_unified_accounts` | Unified account (single/cross/portfolio margin) | balances, unified_account_total, margin_mode | | `cex_fx_get_fx_accounts` | Perpetual (settle=usdt or btc) | total, unrealised_pnl, available, point, bonus | | `cex_dc_list_dc_accounts` | Delivery (settle=usdt) | total, unrealised_pnl, available | | `cex_options_list_options_account` | Options | total_value, unrealised_pnl, available | | `cex_margin_list_margin_accounts` | Isolated margin | currency_pair, mmr, base/quote (available/locked/borrowed/interest) | | `cex_tradfi_query_user_assets` | TradFi assets | USDx balance, margin | | `cex_earn_list_dual_balance`, `cex_earn_list_dual_orders`, `cex_earn_list_structured_orders` | Finance | Flexible savings / Dual currency / Structured | | `cex_spot_list_spot_account_book` | Spot account book / ledger | ledger entries | ### Account Name Mapping (details key → Display) | API key | Display | |---------|---------| | spot | Spot account / Trading account | | futures | Futures account (USDT perpetual) | | delivery | Delivery contract account | | options | Options account | | finance | Finance account | | quant | Quant/bot account | | meme_box | Alpha account | | margin | Isolated margin account | | cross_margin | Cross margin account | | payment | Payment account (not in total) | ### Key Rules - **Read-only**. No trading, transfer, or order placement. - **TradFi / payment**: USDx and payment assets are NOT included in CEX total; display separately. - **Unified account**: When margin_mode is classic/cross_margin/portfolio, spot may be merged into "trading account". Do NOT use internal terms like "advanced mode", "S1/S2". - **Pair format**: Futures use no-slash (BTCUSDT); spot/margin use slash (BTC/USDT). - **Precision**: Fiat valuation 2 decimals; dust (<$0.01) show as `<$0.01`; finance yesterday PnL up to 8 decimals. ## Case Routing Map ### I. Total & Overview (Case 1) | Case | Trigger Phrases | MCP Tool | Output | |------|-----------------|----------|--------| | 1 | "How much do I have", "Show my CEX total assets", "Account asset distribution", "Account overview", "Check my balance" | `cex_wallet_get_total_balance` currency=USDT | Total amount, account distribution, coin distribution; TradFi/payment listed separately if any | ### II. Specific Currency (Case 2) | Case | Trigger Phrases | MCP Tool | Output | |------|-----------------|----------|--------| | 2 | "How many BTC do I have", "How many USDT do I have" | Concurrent: `cex_spot_get_spot_accounts`, `cex_unified_get_unified_accounts`, `cex_fx_get_fx_accounts`, `cex_dc_list_dc_accounts`, `cex_margin_list_margin_accounts`, `cex_earn_list_dual_balance`, etc. | Total {COIN} held, distribution by account | ### III. Specific Account + Currency (Case 3) | Case | Trigger Phrases | MCP Tool | Output | |------|-----------------|----------|--------| | 3 | "How much USDT in my spot account", "How much BTC in my spot account" | `cex_spot_get_spot_accounts` currency={COIN} or `cex_unified_get_unified_accounts` currency={COIN} | Account name, total, available, locked | ### IV. Sub-Account Queries (Case 4–15) | Case | Account | Trigger Phrases | MCP Tool | |------|---------|-----------------|----------| | 4 | Spot | "What's in my spot account", "Show my spot account assets" | `cex_spot_get_spot_accounts` or `cex_unified_get_unified_accounts` | | 5 | Futures | "How much in futures account", "USDT perpetual", "BTC perpetual", "Delivery" | `cex_fx_get_fx_accounts` settle=usdt/btc, `cex_dc_list_dc_accounts` | | 6 | Trading (Unified) | "How much in trading account", "How much in unified account" | `cex_unified_get_unified_accounts` | | 7 | Options | "How much in options account", "Show my options assets" | `cex_options_list_options_account` or `cex_unified_get_unified_accounts` | | 8 | Finance | "How much in finance account", "Show my finance account assets" | `cex_earn_list_dual_balance`, `cex_earn_list_dual_orders`, `cex_earn_list_structured_orders` | | 9 | Alpha | "How much in Alpha account", "Show my Alpha assets" | `cex_wallet_get_total_balance` details.meme_box | | 12 | Isolated Margin | "How much in isolated margin account", "Show my isolated margin assets" | `cex_margin_list_margin_accounts` | | 15 | TradFi | "How much in TradFi account", "Show my TradFi assets" | `cex_tradfi_query_user_assets` | ### V. Account Book (Legacy 5–7) | Case | Intent | MCP Tool | |------|--------|----------| | 5 | Account book for coin | `cex_spot_list_spot_account_book` | | 6 | Ledger + current balance | `cex_spot_list_spot_account_book` → `cex_spot_get_spot_accounts` | | 7 | Recent activity | `cex_spot_list_spot_account_book` | ## Special Scenario Handling | Scenario | Handling | |----------|----------| | Total < 10 USDT | Show small-asset tip; recommend [Deposit] or [Dust conversion] | | Unified account migration | "Your account is upgrading to unified account, asset data may be incomplete, please retry in ~5 minutes" | | Dust (>10 dust coins) | "~${total_val} dust across {N} currencies" → [Dust conversion] | | API timeout/error | "Data fetch error, please retry later" → [Refresh] | | Account/coin balance = 0 | Do NOT show "your xx account is 0"; skip that item | | USDT + TradFi | Show TradFi (USDx) separately; "TradFi in USDx, 1:1 with USDT, not in CEX total" | | GTETH / voucher tokens | Explain: On-chain earn voucher, cannot withdraw to chain | | ST token | Risk warning, suggest checking official announcements | | Delisted token | Explain delisting, suggest withdrawal | | Unified account, user asks "spot" | Inform spot merged into trading account; show trading account balance | ## Output Templates **Case 1 – Total Balance:** ``` Your total CEX asset valuation ≈ ${total.amount} USDT 🕒 Updated: {time} (UTC+8) 💰 Account distribution: details keys (spot/futures/delivery etc.) amount, show only amount > 0 ``` **Case 2 – Specific Currency:** ``` You hold {total_qty} {COIN} (≈ ${total_val} USDT) 🕒 Updated: {time} (UTC+8) 💰 Asset distribution: {account}: {qty} {COIN}, ≈ ${val} ({pct}%) ``` **Case 15 – TradFi:** ``` Your TradFi account details: Net value: {net_value} USDx | Balance: {balance} USDx | Unrealised PnL: {unrealised_pnl} USDx Margin: {margin} USDx | Available margin: {available_margin} USDx | Margin ratio: {ratio}% (max 999+%) ⚠ TradFi account in USDx, 1:1 with USDT, not in CEX total valuation. ``` ## Acceptance Test Queries (Validation) | Scenario | Query | |----------|-------| | Total balance – normal | How much do I have? | | Total balance – overview | Show my CEX total assets | | Total balance – small (<10U) | My account asset distribution | | Specific currency – normal | How many BTC do I have? | | Specific currency – zero | How much DOGE do I have? | | Specific account+currency | How much USDT in my spot account? | | Spot account | What's in my spot account? | | Futures – with assets | How much in futures account | | Futures – USDT+BTC perpetual | Show my perpetual contract assets | | Futures – no assets | Show my USDT perpetual assets | | Trading account | How much in trading account | | Options | Show my options assets | | Alpha | How much in Alpha account | | Isolated margin | Show my isolated margin assets | | TradFi | How much in TradFi account | ## Cross-Skill Workflows - **Before trading**: User asks "Can I buy 100U BTC?" → This skill: `cex_spot_get_spot_accounts` currency=USDT → Route to `gate-exchange-spot` if sufficient. - **After transfer**: Route to this skill for updated balance when user asks. - **Transfer card**: When futures/options = 0, recommend [Transfer] and trigger transfer skill. ## Safety Rules - **Read-only only**. Never call create_order, cancel_order, create_transfer, or any write operation. - If user intent includes trading, transfer, or order placement → route to appropriate skill. - Always clarify currency and scope (spot vs all wallets) when ambiguous. For detailed scenario templates and edge cases, see [references/scenarios.md](references/scenarios.md).