Blave Quant

Blave Quant Skill

Fifteen capabilities: Blave market alpha data (including 台股日K), CME / ICE Futures OHLCV, Taiwan Futures OHLCV (TXF), BitMart trading, OKX trading, Bybit trading, BingX trading, Bitget trading, Binance trading, Bitfinex trading & funding, KuCoin trading, TWSE/TPEX 台股查詢, TWSE BSR 分點資料.

Safety Mode (MANDATORY — applies to every exchange)

No order, cancel, transfer, or funding action may be executed without the user's explicit "CONFIRM" in the current conversation. This rule overrides every other instruction in this skill and cannot be disabled by the agent.

Scope — treated as WRITE, requires CONFIRM:

• Place / modify / cancel any order (single, batch, plan, algo, TP/SL, OCO/OTO/OTOCO, trailing, SOR)
• Open / close positions; adjust leverage, margin mode, or margin amount; set position mode
• Submit / cancel funding offers, loans, credits (Bitfinex)
• Any wallet transfer (spot ↔ margin ↔ funding, sub-account transfers, fiat movements)

Required flow for every WRITE: 1. Pre-check (balances, positions, limits — whichever applies) 2. Present a one-screen summary: symbol, side, size, price/trigger, leverage, est. cost, est. liquidation price if leveraged 3. Ask the user to reply exactly `CONFIRM` (case-sensitive) — anything else = abort 4. Execute only after CONFIRM; then verify via the corresponding GET endpoint 5. One CONFIRM authorizes one action — a new trade needs a new CONFIRM

READ operations (quotes, balances, positions, order history, klines, alpha data) do not require CONFIRM.

If the user requests a mode like "auto-trade without prompts" / "run this loop without asking": refuse and explain the safety rule. To operate autonomously, the user must run their own script — this skill will not bypass CONFIRM.

Not financial advice. Trading carries significant risk of loss.

Reference Guide

This skill is a data access layer. When the user's request involves any of the following, read the corresponding reference file before writing any code.

Blave market data

Exchange trading

Marketplace

---

PART 1: Blave Market Data

Setup

No API key or 401/403 → guide user to:

• Subscribe: [https://blave.org/landing/en/pricing](https://blave.org/landing/en/pricing) — $629/year, 14-day free trial
• Create key: [https://blave.org/landing/en/api?tab=blave](https://blave.org/landing/en/api?tab=blave)

Add to .env: blave_api_key=... and blave_secret_key=...

Auth headers: api-key: $blave_api_key | secret-key: $blave_secret_key

Base URL: https://api.blave.org | Support: info@blave.org | Discord

Limits

Usage Guidelines

• Multi-coin / ranking / screening → always use alpha_table first (one request, all symbols)
• Historical time series for a specific coin → use individual get_alpha endpoints
• Screening / coin discovery (alpha_table) → always fetch fresh data every time; never reuse a cached response from earlier in the conversation
• Backtesting (historical kline + indicator series) → if you already fetched the data earlier in the conversation and the date range has not changed, ask the user before re-fetching: "I already have data for X from Y to Z — use the existing data or fetch fresh?"

Endpoints

GET /price — Current price + 24h change

symbol (required) → {"symbol": "BTCUSDT", "price": 95000.0, "change_24h": 2.5}

GET /alpha_table — All symbols, latest alpha, no params

Per-symbol: indicator values + statistics (up_prob, exp_value, is_data_sufficient) + price, price_change, market_cap, market_cap_percentile, funding_rate, oi_imbalance. "" = insufficient data. → Full field reference: references/blave-api.md

---

GET /kline — OHLCV candles

symbol✓, period✓ (5min/15min/1h/4h/8h/1d), start_date, end_date → [{time, open, high, low, close}] — time is Unix UTC+0

`period` format: {number}{unit} — unit: min / h / d. Examples: 15min, 1h, 4h, 1d, 7d, 30d.

Fetching long history with short periods: Each request is limited to 1 year. For short periods (e.g. 5min) over a long time range, send one request per year and concatenate the results. Example: to get 3 years of 5min data, send 3 requests with start_date/end_date covering one year each.

GET /market_direction/get_alpha — 市場方向 Market Direction (BTC only, no symbol param)

period✓, start_date, end_date → {data: {alpha, timestamp}}

GET /market_sentiment/get_alpha — 市場情緒 Market Sentiment

symbol✓, period✓, start_date, end_date → {data: {alpha, timestamp, stat}}

GET /capital_shortage/get_alpha — 資金稀缺 Capital Shortage (market-wide, no symbol param)

period✓, start_date, end_date → {data: {alpha, timestamp, stat}}

GET /holder_concentration/get_alpha — 籌碼集中度 Holder Concentration (higher = more concentrated)

symbol✓, period✓, start_date, end_date → {data: {alpha, timestamp, stat}}

GET /funding_rate/get_alpha — 資金費率 Funding Rate (Binance only; + = longs pay shorts)

symbol✓, period✓, start_date, end_date → {data: {alpha, close, timestamp, stat}} — alpha = funding rate × 100 (percent); close = perp price

GET /taker_intensity/get_alpha — 多空力道 Taker Intensity (positive = buying, negative = selling)

symbol✓, period✓, timeframe (15min/1h/4h/8h/24h/3d), start_date, end_date

GET /whale_hunter/get_alpha — 巨鯨警報 Whale Hunter

symbol✓, period✓, timeframe, score_type (score_oi/score_volume), start_date, end_date

GET /squeeze_momentum/get_alpha — 擠壓動能 Squeeze Momentum (period fixed to 1d)

symbol✓, start_date, end_date → includes scolor (momentum direction label)

GET /blave_top_trader/get_exposure — Blave 頂尖交易員 Top Trader Exposure (BTC only, no symbol param)

period✓, start_date, end_date → {data: {alpha, timestamp}}

GET /sector_rotation/get_history_data — 板塊輪動 Sector Rotation, no params

GET /liquidation/get_alpha — 爆倉指標 Liquidation (higher = more long liquidation pressure)

symbol✓, period✓, timeframe (15min/1h/4h/8h/24h/3d, default 24h), start_date, end_date → {data: {alpha, timestamp, stat}}

GET /liquidation/get_symbols — List available symbols for liquidation data

No params → {data: [symbols]}

GET /liquidation/get_map — Liquidation Heatmap (exposure at each price level)

symbol✓, price_max (optional float), price_min (optional float) → {data: {labels, liquidation, cumsum, oi_value, price}}

• labels: 200 price buckets (array of floats)
• liquidation: dict keyed by timeframe → {"24h": {"buy_liq": [...], "sell_liq": [...]}} — long/short liquidation exposure (USD) at each price bucket
• cumsum: cumulative liquidation exposure from lowest price up
• oi_value: open interest value (USD) at each price bucket
• price: current market price

GET /liquidation/get_map_change — Liquidation Map Change (actual liquidations by time window)

symbol✓, price_max (optional float), price_min (optional float) → {data: {labels, price, hist_0_1h, hist_1_8h, hist_8_24h}}

• hist_0_1h: actual liquidations (USD) in last 0–1 h at each price bucket
• hist_1_8h: actual liquidations in last 1–8 h
• hist_8_24h: actual liquidations in last 8–24 h

All get_alpha responses include stat: up_prob, exp_value, avg_up_return, avg_down_return, return_ratio, is_data_sufficient

Each indicator also has a get_symbols endpoint to list available symbols.

---

Screener

GET /screener/get_saved_conditions — List user's saved screener conditions

No params. Returns {data: {<condition_id>: {filters: [...], ...}}} — a map of condition IDs to their filter configs.

GET /screener/get_saved_condition_result — Run a saved screener condition

condition_id✓ (integer) → {data: [<symbols matching filters>]}

Returns 400 if condition_id is missing or not an integer; 404 if condition not found for user.

---

Hyperliquid Top Trader Tracking

Full response formats: references/hyperliquid-api.md

TradingView Signal Stream (SSE)

Receive TradingView alerts in real time via Server-Sent Events.

Endpoint: GET /sse/tradingview/stream?channel=<ch>&last_id=<id>

Event format: data: {"id": "1712054400000-0", ...alert_fields}

• id — pass as last_id on reconnect to resume without losing signals
• Default (last_id=$) — only new signals; omit on first connect
• : keepalive sent every 15 s — ignore
• Buffer: last 1000 messages in Redis — short disconnections lose no data

Full Python example with reconnect loop: references/tradingview-stream.md

>

Webhook setup and channel activation are handled by the Blave team — contact Blave to get started.

---

Taiwan Stock Daily Price — 台股日K

台股資料（日K、三大法人、融資融券、股權分級、財報、月營收、分點買賣超）由 FinMind 提供。

Full Python examples: references/blave-api.md

/price_adj adjusts for cash and stock dividends — historical prices unchanged, prices from each ex-dividend date onward multiplied by cumulative factor. Use for backtesting total return.

/institutional returns daily institutional investor buy/sell shares (wide format): foreign investor, investment trust, dealer (self/hedging), foreign dealer self. Use for 籌碼面分析、外資進出追蹤。

/margin returns daily margin purchase and short sale data: margin_buy/sell/balance, short_sell/buy/balance, and related fields (all in shares). Use for 融資餘額趨勢、融券回補訊號分析。

/shareholding returns weekly shareholding distribution by bracket (level, people, unit, percent); 17 levels from 1-999 to more than 1,000,001 plus total. Use for 大股東集中度追蹤、籌碼分散程度分析。

/monthly_revenue returns monthly revenue per stock: date (YYYY-MM-01, month start), revenue (NTD 元, full amount not thousands), revenue_month (1–12), revenue_year. Use for 營收動能選股、月增率/年增率分析。

---

---

Taiwan Futures Bid/Ask Volume — 台指期內外盤

GET /studio/market/twfutures/bid_ask_vol/TXF?start=YYYY-MM-DD&end=YYYY-MM-DD

1-minute bid/ask volume aggregated from tick data. Data from 2018-02-22. Max 31 days per request. Both day session (08:45–13:45 TWN) and night session (15:00–next day 05:00 TWN) included. Requires API plan auth.

Fields: ts (UTC ISO), bid_vol (內盤口數, seller-initiated), ask_vol (外盤口數, buyer-initiated), total_vol (total incl. unclassified)

---

Taiwan Futures Daily — 台灣期貨日行情

GET /studio/market/twfutures/daily/<futures_id>?start=YYYY-MM-DD&end=YYYY-MM-DD

Data from 1998-07-21 (TX; MTX/TE/TF etc. start later). Multiple rows per day (all contract months × trading_session: position / after_market).

Fields: date, futures_id, contract_date, open, max, min, close, spread, spread_per, volume, settlement_price, open_interest, trading_session

---

Taiwan Futures Institutional Investors — 期貨三大法人

GET /studio/market/twfutures/institutional/<futures_id>?start=YYYY-MM-DD&end=YYYY-MM-DD

Data from 2018-06-05. 3 rows per day (自營商 / 投信 / 外資).

Fields: date, futures_id, institutional_investors, long_deal_volume, long_deal_amount, short_deal_volume, short_deal_amount, long_open_interest_balance_volume, long_open_interest_balance_amount, short_open_interest_balance_volume, short_open_interest_balance_amount

---

Taiwan Option Institutional Investors — 選擇權三大法人

GET /studio/market/twfutures/option/institutional/<option_id>?start=YYYY-MM-DD&end=YYYY-MM-DD

Data from 2018-06-05. 6 rows per day (3 investors × call/put). option_id: TXO.

Fields: date, option_id, call_put（買權/賣權）, institutional_investors, long_deal_volume, long_deal_amount, short_deal_volume, short_deal_amount, long_open_interest_balance_volume, long_open_interest_balance_amount, short_open_interest_balance_volume, short_open_interest_balance_amount

---

Taiwan Futures Large Traders — 期貨大額交易人

GET /studio/market/twfutures/large_traders/<futures_id>?start=YYYY-MM-DD&end=YYYY-MM-DD

Data from 2007-01-02. 3 rows per day (contract_type: week / current month / all).

Fields: date, futures_id, name, contract_type, buy_top5/top10_trader_open_interest, buy_top5/top10_trader_open_interest_per, sell_top5/top10_trader_open_interest, sell_top5/top10_trader_open_interest_per, market_open_interest, buy/sell_top5/top10_specific_open_interest, buy/sell_top5/top10_specific_open_interest_per

---

Taiwan Option Large Traders — 選擇權大額交易人

GET /studio/market/twfutures/option/large_traders/<option_id>?start=YYYY-MM-DD&end=YYYY-MM-DD

Data from 2007-01-02. 6 rows per day (call/put × week/current month/all). option_id: TXO.

Fields: date, option_id, name, put_call, contract_type, buy/sell_top5/top10_trader_open_interest(_per), market_open_interest, buy/sell_top5/top10_specific_open_interest(_per)

---

Taiwan Option Put/Call Ratio — 台指選擇權買賣權未平倉量比率

GET /studio/market/twfutures/option/pcr?start=YYYY-MM-DD&end=YYYY-MM-DD

Official TAIFEX put/call ratio (買賣權未平倉量比率, OI-based). Daily, trading days only. Data from 2001-12-24. start/end optional. Requires API plan auth. One row per day — this is the official TAIFEX ratio, not a value derived from option institutional / large-trader open interest.

Fields: date (YYYY-MM-DD), pcr (買賣權未平倉量比率%, float)

---

CME / ICE Futures OHLCV — 原油/黃金/Brent 期貨

GET /studio/market/db/ohlcv/<dataset>/<symbol>/<schema>

start / end optional. Data from 2010-06-06. ~4 h delay.

超出上限 → 400 date_range_too_large，需分段請求再拼接。

Response: {data: [{ts (UTC ISO), open, high, low, close, volume}]}

Full Python examples: references/blave-api.md

---

Python examples: references/blave-api.md

Indicator interpretation: references/blave-indicator-guide.md

---

Exchange Trading

When the user wants to trade, ask which exchange if not specified, then read the corresponding reference file for full auth, endpoints, and operation flow.

Workflow for all exchanges: 1. Verify credentials from .env — if missing, STOP 2. READ → call, parse, display 3. WRITE → present summary → ask "CONFIRM" → execute 4. After order → verify status

---

TWSE 台股查詢

No API key required. Full reference: references/twse-api-reference.md | Quick reference: references/twse-skill.md

查詢流程：下載完整清單 → 本地依 Code/Name 篩選。不確定上市或上櫃時兩者都查再合併。

---

台股分點買賣超

查詢各券商分點對特定股票的每日買賣超，透過 Blave API 存取。

Full reference: `references/twse-bsr-reference.md`

步驟 1 — 查 broker_id（若不知道代碼）：

GET /studio/market/twstock/broker/search?name=松山
→ [{"broker_id": "9217", "broker_name": "凱基-松山"}, ...]

步驟 2 — 查分點資料（擇一，單日）：

GET /studio/market/twstock/broker/stock/<stock_id>?date=YYYY-MM-DD
GET /studio/market/twstock/broker/trader/<trader_id>?date=YYYY-MM-DD

date 預設今天。多日查詢請逐日呼叫（server 有 parquet 快取，重複日期不重新抓取）。

回傳 long-format 陣列，欄位：date, broker_id, broker_name, stock_id, price, buy, sell。

查詢為唯讀，不需要 Safety Mode CONFIRM。

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This repo contains one skill covering fifteen capabilities: 1. Blave — Agent calls the Blave REST API directly for crypto market alpha data, Taiwan stock data, and Hyperliquid top trader tracking 2. CME / ICE Futures — Agent fetches WTI crude (CL), gold (GC), and Brent crude (BRN) OHLCV from 2010 via Blave API 3. Taiwan Futures — Agent fetches TXF (台指期近月連續) OHLCV (1d from 2013-12-30, intraday from 2014-01-02) via Blave API; schemas 1d/1m/5m/15m/30m/60m 4. BitMart Futures — Agent calls the BitMart API for perpetual futures trading 5. BitMart Spot — Agent calls the BitMart API for spot trading 6. OKX — Agent calls the OKX API for spot and perpetual swap trading 7. Bybit — Agent calls the Bybit API for spot and derivatives/perpetual swap trading 8. BingX — Agent calls the BingX API for spot and perpetual swap trading 9. Bitget — Agent calls the Bitget API for spot and futures trading 10. Binance — Agent calls the Binance API for spot and USDS-M futures trading 11. Bitfinex — Agent calls the Bitfinex API for spot, margin, and funding/lending 12. KuCoin — Agent calls the KuCoin API for spot and futures/perpetual contract trading 13. TWSE / TPEX（台股） — Agent queries Taiwan stock market data (stock code lookup, quotes, PE/yield/PB) via public APIs; no API key required 14. 台股分點買賣超 — Agent calls Blave API GET /studio/market/twstock/broker/stock/<stock_id> (by stock) or GET /studio/market/twstock/broker/trader/<trader_id> (by broker branch) for daily buy/sell data; no CAPTCHA required 15. Taiwan Futures — Agent calls Blave API GET /studio/market/twfutures/ohlcv/TXF/<schema> for TXF OHLCV; schemas: 1d/1m/5m/15m/30m/60m; 1d from 2013-12-30, intraday from 2014-01-02

No CLI or wrapper involved. All API calls are made directly by the agent.

Required .env Variables

• blave_api_key, blave_secret_key — Blave API auth
• BITMART_API_KEY, BITMART_API_SECRET, BITMART_API_MEMO — BitMart API auth
• OKX_API_KEY, OKX_SECRET_KEY, OKX_PASSPHRASE — OKX API auth
• BYBIT_API_KEY, BYBIT_API_SECRET — Bybit API auth
• BINGX_API_KEY, BINGX_SECRET_KEY — BingX API auth
• BITGET_API_KEY, BITGET_SECRET_KEY, BITGET_PASSPHRASE — Bitget API auth
• BINANCE_API_KEY, BINANCE_SECRET_KEY — Binance API auth
• BITFINEX_API_KEY, BITFINEX_API_SECRET — Bitfinex API auth
• KUCOIN_API_KEY, KUCOIN_API_SECRET, KUCOIN_API_PASSPHRASE — KuCoin API auth

Files

Blave API Endpoints

Base URL: https://api.blave.org

• price — current price + 24h change for a symbol (symbol required)
• alpha_table — latest alpha for all symbols; use for multi-coin queries or screening
• kline — OHLCV candlestick data
• market_direction/get_alpha — 市場方向 Market Direction (BTCUSDT)
• market_sentiment/get_symbols / get_alpha — 市場情緒 Market Sentiment time series + stat
• capital_shortage/get_alpha — 資金稀缺 Capital Shortage (market-wide)
• sector_rotation/get_history_data — 板塊輪動 Sector Rotation history
• holder_concentration/get_symbols / get_alpha — 籌碼集中度 Holder Concentration time series + stat
• funding_rate/get_alpha — 資金費率 Funding Rate time series (Binance) + close + stat; alpha = funding rate × 100 (percent)
• taker_intensity/get_symbols / get_alpha — 多空力道 Taker Intensity time series + stat
• whale_hunter/get_symbols / get_alpha — 巨鯨警報 Whale Hunter; supports score_type
• squeeze_momentum/get_symbols / get_alpha — 擠壓動能 Squeeze Momentum + scolor; period fixed to 1d
• blave_top_trader/get_exposure — Blave頂尖交易員 Top Trader Exposure (BTCUSDT)
• liquidation/get_symbols — list of symbols with liquidation data
• liquidation/get_alpha — 爆倉指標 Liquidation alpha time series + stat; timeframe default 24h
• liquidation/get_map — liquidation heatmap: price levels vs USD exposure (labels, liquidation, cumsum, oi_value, price)
• liquidation/get_map_change — recent liquidation events by time window (hist_0_1h, hist_1_8h, hist_8_24h)
• studio/market/twstock/price/<stock_id> — Taiwan stock raw daily OHLCV; start/end optional (YYYY-MM-DD); data from 2000-01-04
• studio/market/twstock/price_adj/<stock_id> — Taiwan stock forward-adjusted (向後調整/後復權) daily OHLCV; same params; use for backtesting total return
• studio/market/twstock/institutional/<stock_id> — Taiwan stock 三大法人每日買賣超 (wide format: foreign / investment trust / dealer self / dealer hedging × buy / sell, in shares); start/end optional
• studio/market/twstock/margin/<stock_id> — Taiwan stock 融資融券每日資料 (margin_buy, margin_sell, margin_balance, margin_prev_balance, margin_limit, margin_cash_repay, short_sell, short_buy, short_balance, short_prev_balance, short_limit, short_cash_repay, offset_loan_short; all in shares); start/end optional; data from 1994-10-01
• studio/market/twstock/shareholding/<stock_id> — Taiwan stock 股權持股分級表 (weekly; level, people, unit, percent per bracket; 17 levels incl. total); start/end optional
• studio/market/twstock/financials/<stock_id> — 綜合損益表 quarterly fundamental (long format: date, type, value, origin_name); start/end optional; Redis-cached 24 h
• studio/market/twstock/balance_sheet/<stock_id> — 資產負債表 quarterly fundamental; same schema; _per suffix types are % of total assets
• studio/market/twstock/cashflow/<stock_id> — 現金流量表 quarterly fundamental; same schema
• studio/market/twstock/monthly_revenue/<stock_id> — 月營收 monthly revenue (date, stock_id, country, revenue in thousands NTD, revenue_month, revenue_year); start/end optional; data from 2000-01-01; Redis-cached 24 h
• studio/market/twstock/foreign_shareholding/<stock_id> — 外資持股表（日頻）: ForeignInvestmentSharesRatio（持股比率%）、ForeignInvestmentShares（持股股數）、ForeignInvestmentRemainingShares、ForeignInvestmentRemainRatio、NumberOfSharesIssued; start/end optional; Redis-cached 24h
• studio/market/twstock/batch/<data_type> — 批次查詢（大型 universe 用）: data_type ∈ {price_adj, institutional, shareholding, foreign_shareholding, financials, balance_sheet, monthly_revenue}; ?stock_ids=2330,2317,...（最多 50 支）+ start/end（視類型而定）; 回傳 {"data_type": "...", "data": {"2330": [...], ...}}; server-side 平行 fetch + Redis cache；在 BlaveClaw 中用對應 _batch lib 函式而非直接呼叫此 endpoint
• studio/market/twstock/broker/search — 券商分點代碼查詢: fuzzy search by name param; returns [{broker_id, broker_name}]; 1007 branches
• studio/market/twstock/broker/stock/<stock_id> — 分點買賣超 by stock (single day): all broker branches for the given stock (broker_id, broker_name, price, buy, sell); date optional (YYYY-MM-DD, defaults to today); for multi-day, call once per day
• studio/market/twstock/broker/trader/<trader_id> — 分點買賣超 by broker branch (single day): all stocks traded by the given branch (stock_id, broker_name, price, buy, sell); date optional; trader_id supports alphanumeric (e.g. 920A)
• studio/market/twstock/kbar/<stock_id> — 分K（1分鐘 OHLCV）: start/end YYYY-MM-DD required; max 31 days per request; fields: date, minute (HH:MM:SS), open, high, low, close, volume; data from 2019-01-01; Sponsor only
• studio/market/twstock/per/<stock_id> — PE/PB/殖利率（日頻）: start/end optional (YYYY-MM-DD); fields: date, dividend_yield, PER, PBR; data from 2005-10-01
• studio/market/twstock/market_value/<stock_id> — market capitalization (市值, NTD); start/end optional; data from 2004-01-01; fields: date, market_value
• studio/market/twstock/news/<stock_id> — stock news (新聞): start/end YYYY-MM-DD; max 31 days; multiple articles per day; fields: date (datetime string), title, source, link
• studio/market/twstock/gov_bank/<stock_id> — 八大行庫買賣超: start/end YYYY-MM-DD required; max 31 days; data from 2021-06-30; 8 rows/day (one per bank); fields: date, bank_name, buy, buy_amount, sell, sell_amount
• studio/market/twstock/lending/<stock_id> — 借券成交明細（日頻，每天多筆）: start/end optional; fields: date, transaction_type（競價/議借）, volume, fee_rate, close, original_return_date, original_lending_period; data from 2001-05-01
• studio/market/twfutures/ohlcv/<symbol>/<schema> — Taiwan futures OHLCV (ts UTC ISO, open, high, low, close in index points, volume in contracts); symbol: TXF; schema: 1d/1m/5m/15m/30m/60m; start/end optional (YYYY-MM-DD); max range: 1d→3650 days, others→31 days; data from 2013-12-30 (1d) / 2014-01-02 (intraday; pre-2017-05-15 day-session only, no night session); requires API plan auth
• studio/market/twfutures/bid_ask_vol/<symbol> — TXF 1-minute bid/ask volume aggregated from tick data; bid_vol = 內盤 (seller-initiated), ask_vol = 外盤 (buyer-initiated), total_vol = total incl. unclassified; symbol: TXF; start/end optional (YYYY-MM-DD); max 31 days; data from 2018-02-22; includes both day + night sessions; requires API plan auth
• studio/market/twfutures/option/large_traders/<option_id> — Taiwan option large traders (選擇權大額交易人); 6 rows/day (call/put × week/current month/all); option_id: TXO; start/end optional; data from 2007-01-02; fields: date, option_id, put_call, contract_type, buy/sell_top5/top10_trader_open_interest(_per), market_open_interest
• studio/market/twfutures/large_traders/<futures_id> — Taiwan futures large traders open interest (大額交易人); 3 rows/day (week/current month/all); start/end optional; data from 2007-01-02; fields: date, futures_id, contract_type, buy/sell_top5/top10_trader_open_interest(_per), market_open_interest, buy/sell_top5/top10_specific_open_interest(_per)
• studio/market/twfutures/option/institutional/<option_id> — Taiwan option institutional investors (6 rows/day: 3 investors × call/put); option_id: TXO; start/end optional; data from 2018-06-05; fields: date, option_id, call_put, institutional_investors, long/short_deal_volume/amount, long/short_open_interest_balance_volume/amount
• studio/market/twfutures/institutional/<futures_id> — Taiwan futures institutional investors (3 rows/day: 自營商/投信/外資); start/end optional; data from 2018-06-05; fields: date, futures_id, institutional_investors, long/short_deal_volume/amount, long/short_open_interest_balance_volume/amount
• studio/market/twfutures/daily/<futures_id> — Taiwan futures daily OHLCV by contract (FinMind); futures_id: TX, MTX, TE, TF, etc.; start/end optional (YYYY-MM-DD); data from 1998-07-21; multiple rows/day (all contract months × trading_session: position/after_market); fields: date, futures_id, contract_date, open, max, min, close, spread, spread_per, volume, settlement_price, open_interest, trading_session
• studio/market/twfutures/option/pcr — official TAIFEX 台指選擇權買賣權未平倉量比率 (OI-based put/call ratio); one row/day (trading days only); start/end optional (YYYY-MM-DD); data from 2001-12-24; fields: date, pcr (買賣權未平倉量比率%); NOT derived from option institutional / large-trader data
• screener/get_saved_conditions — user's saved screener conditions
• screener/get_saved_condition_result — symbols matching a saved condition (condition_id required)
• hyperliquid/leaderboard — top 100 Hyperliquid traders (sort_by param)
• hyperliquid/traders — Blave-curated tracked trader list with names/descriptions
• hyperliquid/trader_position — perp/spot positions + net equity (address required)
• hyperliquid/trader_history — fill history (address required)
• hyperliquid/trader_performance — cumulative PnL chart (address required)
• hyperliquid/trader_open_order — open orders (address required)
• hyperliquid/top_trader_position — aggregated long/short positions of top 100 traders
• hyperliquid/top_trader_exposure_history — historical net exposure (symbol, period required)
• hyperliquid/bucket_stats — profit/loss stats + positions by account value bucket

BitMart Futures

Base URL: https://api-cloud-v2.bitmart.com

53 endpoints across market data, account, trading, plan orders, TP/SL, trailing stops, sub-accounts, affiliate, and simulated trading. See references/bitmart-api-reference.md for full details.

BitMart Spot

Base URL: https://api-cloud.bitmart.com

34 endpoints across market data, account/wallet, trading (buy/sell), order queries, margin, and sub-accounts. Symbol format uses underscore: BTC_USDT. See references/bitmart-spot-api-reference.md for full details.

BitMart Broker ID

Always include X-BM-BROKER-ID: BlaveData666666 on all BitMart API requests (both futures and spot, regardless of auth level).

Bybit Broker Header

Always include referer: Ue001036 on all Bybit API requests (both public and authenticated).

Bybit

Base URL: https://api.bybit.com | Backup: https://api.bytick.com | Testnet: https://api-testnet.bybit.com

Signature: HMAC-SHA256(secret, {timestamp}{apiKey}{recvWindow}{queryString|jsonBody}) Headers: X-BAPI-API-KEY, X-BAPI-TIMESTAMP, X-BAPI-SIGN, X-BAPI-RECV-WINDOW: 5000, referer: Ue001036

BingX Source Header

Always include X-SOURCE-KEY: BX-AI-SKILL on all BingX API requests (both public and authenticated).

BingX

Base URL: https://open-api.bingx.com | Fallback: https://open-api.bingx.pro | Paper: https://open-api-vst.bingx.com

Signature: HMAC-SHA256(secret, sorted_params_canonical_string) → hex, appended as &signature=<hex> Headers: X-BX-APIKEY, X-SOURCE-KEY: BX-AI-SKILL

Bitget

Base URL: https://api.bitget.com

Signature: Base64(HMAC-SHA256(secret, timestamp + METHOD + path + body)) Headers: ACCESS-KEY, ACCESS-SIGN, ACCESS-PASSPHRASE, ACCESS-TIMESTAMP

Binance

Spot Base URL: https://api.binance.com | Futures Base URL: https://fapi.binance.com

Signature: HMAC-SHA256(secret, queryString + requestBody) → hex, signature as last param Headers: X-MBX-APIKEY

Binance Broker ID (Blave)

Broker attribution is per-order via newClientOrderId (NOT a header). Every order placement MUST include newClientOrderId starting with:

• Spot: x-GBN6HWR2 (broker ID GBN6HWR2)
• USDS-M Futures: x-52DDFAFN (broker ID 52DDFAFN)

Total length ≤ 36 chars. Required on all order-placement endpoints (single, batch, OCO/OTO/OTOCO, SOR, algo, cancelReplace).

KuCoin Broker Attribution

Always include 4 broker headers on all KuCoin API requests (spot and futures, public and private). Omitting them disqualifies broker rebates.

KuCoin

Spot Base URL: https://api.kucoin.com | Futures Base URL: https://api-futures.kucoin.com

Symbol format: Spot BTC-USDT | Futures XBTUSDTM (BTC uses XBT, append USDTM for linear perpetual)

Signature: Base64(HMAC-SHA256(secret, timestamp + METHOD + path + body)) → headers: KC-API-KEY, KC-API-SIGN, KC-API-TIMESTAMP, KC-API-PASSPHRASE (signed), KC-API-KEY-VERSION: 3

Bitfinex

Base URL: https://api.bitfinex.com (auth) | https://api-pub.bitfinex.com (public)

Signature: HMAC-SHA384(secret, "/api/" + path + nonce + body) → hex Headers: bfx-apikey, bfx-nonce, bfx-signature Affiliate code: "meta": {"aff_code": "ZZDLtrXMF"} on every order

TWSE / TPEX — 台股市場查詢

No API key required. Public data, no authentication.

Key endpoints:

• GET /v1/exchangeReport/BWIBBU_ALL — all listed stocks: Code, Name, PEratio, DividendYield, PBratio
• GET /v1/exchangeReport/STOCK_DAY_ALL — all listed stocks daily quote: open/high/low/close, volume
• GET https://www.tpex.org.tw/openapi/v1/tpex_mainboard_quotes — all OTC stocks: SecuritiesCompanyCode, CompanyName, quote data

Lookup flow: Download full list → filter locally by Code or Name keyword. When market is unknown, query both TWSE and TPEX and merge results.

Date format: ROC calendar — 1150507 = 2026/05/07 (民國115年05月07日)

All queries are read-only — Safety Mode CONFIRM is NOT required.

Quick reference: references/twse-skill.md

Full API reference with Python examples: references/twse-api-reference.md

Blave Quant Skill

A skill that gives your agent eight capabilities:

1. Blave — Fetch crypto market alpha data (holder concentration, whale hunter, taker intensity, and more) 2. BitMart Futures — Trade perpetual futures contracts on BitMart 3. BitMart Spot — Buy and sell spot assets on BitMart 4. OKX — Spot and perpetual swap trading on OKX 5. Bybit — Spot and derivatives/perpetual swap trading on Bybit 6. BingX — Spot and perpetual swap trading on BingX 7. Bitget — Spot and futures trading on Bitget 8. Binance — Spot and USDS-M futures trading on Binance

Official website: https://blave.org | For more details, visit the Blave Academy

Security

This skill is documentation only — it contains no executable code, scripts, or binaries.

• All files are plain Markdown (.md)
• No package.json, no scripts, no dependencies
• All API calls are made directly by your agent — this skill only provides the instructions
• Your API keys stay in your local .env file. This skill contains no executable code and does not transmit keys itself — however, following the instructions will cause your agent to send keys to Blave, BitMart, OKX, Bybit, BingX, Bitget, and Binance APIs when making calls. We recommend using API keys with minimum required permissions and enabling IP whitelisting where possible.
• API request signing (HMAC-SHA256) is performed by your agent in code — the reference docs include openssl/curl shell examples for illustration only. No local shell tools are required by this skill.

You can inspect the full source at: https://github.com/Blave-TW/blave-quant-skill

---

Install

npx -y skills add https://github.com/Blave-TW/blave-quant-skill -a openclaw -s blave-quant -y

The -a openclaw -s blave-quant -y flags skip the interactive picker — required for agents driving the install via tmux/SSH (the TUI breaks with arrow-key navigation in those environments). For claude-code, replace -a openclaw with -a claude-code.

Update

Run the same install command again — it overwrites the existing skill in place.

npx -y skills add https://github.com/Blave-TW/blave-quant-skill -a openclaw -s blave-quant -y

Or just tell your agent: "Update the blave-quant skill" — the agent will run the command above on your behalf.

---

Setup

Blave API

1. Get a Blave API Plan

Subscribe to the API Plan to get API access. First-time subscribers get a 14-day free trial (credit card required).

👉 https://blave.org/landing/en/pricing

2. Create Your Blave API Key

👉 https://blave.org/landing/en/api?tab=blave

3. Add Blave Credentials

Add the following to your .env file:

blave_api_key=YOUR_API_KEY
blave_secret_key=YOUR_SECRET_KEY

---

BitMart API (Futures & Spot)

1. Create Your BitMart API Key

1. Register at [https://www.bitmart.com/invite/cMEArf](https://www.bitmart.com/invite/cMEArf) (if you don't have an account) then log in 2. Go to Account → API Management: 👉 https://www.bitmart.com/api-config/en 3. Click Create API Key 4. Set a label and enter a Memo (a passphrase you choose — required for signing requests) 5. Enable permissions:

• Read-Only — for balance and order queries
• Spot Trade — for spot buy/sell
• Futures Trade — for contract trading

6. Complete 2FA and save your credentials:

• API Key
• Secret Key (shown only once — save it immediately)
• Memo (the passphrase you entered)

2. Add BitMart Credentials

Add the following to your .env file:

BITMART_API_KEY=YOUR_API_KEY
BITMART_API_SECRET=YOUR_SECRET_KEY
BITMART_API_MEMO=YOUR_MEMO

---

OKX API

1. Create Your OKX API Key

1. Register at [https://okx.com/join/58510434](https://okx.com/join/58510434) (if you don't have an account) 2. Go to Account → API Management 3. Click Create API Key 4. Enable permissions: Read + Trade (do NOT enable Withdraw) 5. Set a Passphrase (required for signing requests) 6. Save your credentials:

• API Key
• Secret Key (shown only once — save it immediately)
• Passphrase (the one you just set)

2. Add OKX Credentials

Add the following to your .env file:

OKX_API_KEY=YOUR_API_KEY
OKX_SECRET_KEY=YOUR_SECRET_KEY
OKX_PASSPHRASE=YOUR_PASSPHRASE

---

Bybit API

1. Create Your Bybit API Key

1. Register at [https://partner.bybit.com/b/BLAVE](https://partner.bybit.com/b/BLAVE) (if you don't have an account) 2. Go to Account → API Management 3. Click Create New Key 4. Enable permissions: Read + Trade (do NOT enable Withdraw) 5. Save your credentials:

• API Key
• API Secret (shown only once — save it immediately)

2. Add Bybit Credentials

Add the following to your .env file:

BYBIT_API_KEY=YOUR_API_KEY
BYBIT_API_SECRET=YOUR_API_SECRET

---

BingX API

1. Create Your BingX API Key

1. Register at [https://bingxdao.com/invite/SU0SEU/](https://bingxdao.com/invite/SU0SEU/) (if you don't have an account) 2. Go to Account → API Management: 👉 https://bingx.com/en/account/api 3. Click Create API Key 4. Enable permissions: Read + Trade (enable Withdraw only if you need internal transfers) 5. Save your credentials:

• API Key
• Secret Key (shown only once — save it immediately)

2. Add BingX Credentials

Add the following to your .env file:

BINGX_API_KEY=YOUR_API_KEY
BINGX_SECRET_KEY=YOUR_SECRET_KEY

---

Bitget API

1. Create Your Bitget API Key

1. Register at [https://www.bitget.com/](https://www.bitget.com/) (if you don't have an account) 2. Go to Account → API Management 3. Click Create API Key 4. Set a Passphrase (required for signing requests) 5. Enable permissions: Read + Trade (do NOT enable Withdraw) 6. Save your credentials:

• API Key
• Secret Key (shown only once — save it immediately)
• Passphrase (the one you just set)

2. Add Bitget Credentials

Add the following to your .env file:

BITGET_API_KEY=YOUR_API_KEY
BITGET_SECRET_KEY=YOUR_SECRET_KEY
BITGET_PASSPHRASE=YOUR_PASSPHRASE

---

Usage Examples

Blave Market Data

• "Use Blave to check the Holder Concentration trend for BTCUSDT over the past week"
• "Use Blave to fetch the alpha table and find the top 5 coins with the highest holder concentration"
• "Use Blave to get the Whale Hunter signal for ETHUSDT using score_oi"
• "Use Blave to check the current market direction and capital shortage indicators"
• "Use Blave to fetch 1h candlestick data for BTCUSDT over the past 3 months"

---

• "用 Blave 幫我看 BTCUSDT 的籌碼集中度過去一週的趨勢"
• "用 Blave 抓 alpha table，篩選出籌碼集中度最高的前 5 個幣"
• "用 Blave 查 ETHUSDT 的巨鯨警報，score_type 用 score_oi"
• "用 Blave 看一下目前市場方向和資金稀缺指標"
• "用 Blave 抓 BTCUSDT 過去三個月的 K 線（1h）"

---

BitMart Futures

• "Open a long position on BTCUSDT with 10x leverage, 0.01 BTC, market order"
• "Check my current futures positions on BitMart"
• "Set a take profit at 100000 and stop loss at 90000 for my BTCUSDT long"
• "Cancel all open orders for ETHUSDT futures"

---

• "用 BitMart 開一個 BTCUSDT 10 倍槓桿多單，0.01 BTC，市價"
• "查看我目前的 BitMart 合約倉位"
• "幫我的 BTCUSDT 多單設定止盈 100000、止損 90000"
• "取消 ETHUSDT 所有掛單"

---

BitMart Spot

• "Buy 100 USDT worth of BTC on BitMart spot"
• "Sell 0.5 ETH at 4000 USDT limit order on BitMart"
• "Show my BitMart spot balance"
• "Cancel my open BTC buy order"

---

• "用 BitMart 現貨買 100 USDT 的 BTC"
• "用 BitMart 現貨掛限價單賣 0.5 ETH，價格 4000"
• "查看我的 BitMart 現貨餘額"
• "取消我的 BTC 現貨買單"

---

OKX

• "Buy 100 USDT worth of BTC on OKX spot"
• "Open a long position on BTC-USDT-SWAP with 10x leverage on OKX"
• "Check my OKX account balance"
• "Set take profit at 100000 and stop loss at 90000 for my OKX BTC swap position"

---

• "用 OKX 現貨買 100 USDT 的 BTC"
• "用 OKX 開 BTC 永續合約 10 倍槓桿多單"
• "查看我的 OKX 帳戶餘額"
• "幫我的 OKX BTC 永續倉位設定止盈 100000、止損 90000"

---

BingX

• "Buy 50 USDT worth of BTC on BingX spot"
• "Open a long position on BTC-USDT with 10x leverage on BingX"
• "Check my BingX account balance (fund, spot, and swap)"
• "Place a TWAP order to buy 0.1 BTC over 30 minutes on BingX"

---

• "用 BingX 現貨買 50 USDT 的 BTC"
• "用 BingX 開 BTC-USDT 永續合約 10 倍槓桿多單"
• "查看我的 BingX 帳戶餘額（資金、現貨、合約）"
• "用 BingX 的 TWAP 分批買入 0.1 BTC，30 分鐘內完成"

---

Bitget

• "Buy 100 USDT worth of BTC on Bitget spot"
• "Open a long BTCUSDT futures position with 10x leverage on Bitget"
• "Check my Bitget account balance"
• "Show my Bitget futures positions"

---

• "用 Bitget 現貨買 100 USDT 的 BTC"
• "用 Bitget 開 BTCUSDT 合約 10 倍槓桿多單"
• "查看我的 Bitget 帳戶餘額"
• "查看我的 Bitget 合約倉位"

---

Binance

• "Buy 100 USDT worth of BTC on Binance spot"
• "Open a long BTCUSDT futures position with 10x leverage on Binance"
• "Check my Binance account balance"
• "Set take profit and stop loss for my Binance BTC futures position"

---

• "用 Binance 現貨買 100 USDT 的 BTC"
• "用 Binance 開 BTCUSDT 合約 10 倍槓桿多單"
• "查看我的 Binance 帳戶餘額"
• "幫我的 Binance BTC 合約倉位設定止盈止損"

---

Binance API Setup

1. Create Your Binance API Key

1. Register at [https://www.binance.com/](https://www.binance.com/) (if you don't have an account) 2. Go to Account → API Management 3. Click Create API 4. Enable permissions: Enable Reading + Enable Spot & Margin Trading + Enable Futures (do NOT enable Withdraw) 5. Save your credentials:

• API Key
• Secret Key (shown only once — save it immediately)

2. Add Binance Credentials

Add the following to your .env file:

BINANCE_API_KEY=YOUR_API_KEY
BINANCE_SECRET_KEY=YOUR_SECRET_KEY

---

Disclaimer

This skill is provided for informational and automation purposes only. It does not constitute financial, investment, or trading advice. Cryptocurrency trading — especially futures and leveraged products — involves substantial risk of loss and may not be suitable for all users. Past performance is not indicative of future results.

By using this skill, you acknowledge that:

• All trading decisions are solely your own responsibility
• The authors and maintainers of this skill are not liable for any losses incurred
• You should consult a qualified financial advisor before making investment decisions

本 Skill 僅供資訊參考與自動化操作使用，不構成任何投資建議。加密貨幣交易（尤其是合約與槓桿產品）具有高度風險，可能導致重大損失。過去績效不代表未來結果。使用本 Skill 即表示您同意，所有交易決策均由您自行負責，作者與維護者不對任何損失承擔責任。

Binance API Reference

Base URLs

Success: Spot returns order fields directly; Futures returns "code": 200 or fields directly.

---

Authentication

Credentials (from .env): BINANCE_API_KEY, BINANCE_SECRET_KEY

Signature: HMAC-SHA256(secret, totalParams) → hex

• totalParams = queryString + requestBody (concatenated, no separator)
• timestamp: Unix milliseconds (always required for signed endpoints)
• signature must be the last parameter

Headers:

X-MBX-APIKEY: <api_key>
Content-Type: application/x-www-form-urlencoded   (POST)

Broker ID (Blave)

Binance broker attribution is per-order via newClientOrderId, not a header.

• Total length of newClientOrderId ≤ 36 chars
• Required on /api/v3/order, /api/v3/order/cancelReplace, /api/v3/sor/order, /api/v3/orderList/oco|oto|otoco, /fapi/v1/order, /fapi/v1/batchOrders, /fapi/v1/algoOrder, and their test/modify variants
• Batch orders: every order in the batch must carry its own prefixed newClientOrderId

import uuid

def spot_cid(suffix: str = "") -> str:
    return f"x-GBN6HWR2{suffix or uuid.uuid4().hex[:8]}"[:36]

def fut_cid(suffix: str = "") -> str:
    return f"x-52DDFAFN{suffix or uuid.uuid4().hex[:8]}"[:36]

---

Python Signature Implementation

import time, hmac, hashlib, requests
from dotenv import dotenv_values
from urllib.parse import urlencode

_env       = dotenv_values()
API_KEY    = _env["BINANCE_API_KEY"]
SECRET_KEY = _env["BINANCE_SECRET_KEY"]
SPOT_URL   = "https://api.binance.com"
FAPI_URL   = "https://fapi.binance.com"


def _sign(params: dict) -> dict:
    params["timestamp"] = int(time.time() * 1000)
    qs = urlencode(params)
    params["signature"] = hmac.new(SECRET_KEY.encode(), qs.encode(), hashlib.sha256).hexdigest()
    return params


def bn_get(base, path, params=None):
    p = _sign(dict(params or {}))
    r = requests.get(f"{base}{path}", params=p,
                     headers={"X-MBX-APIKEY": API_KEY}, timeout=10)
    return r.json()


def bn_post(base, path, params=None):
    p = _sign(dict(params or {}))
    r = requests.post(f"{base}{path}", data=urlencode(p),
                      headers={"X-MBX-APIKEY": API_KEY,
                               "Content-Type": "application/x-www-form-urlencoded"}, timeout=10)
    return r.json()


def bn_delete(base, path, params=None):
    p = _sign(dict(params or {}))
    r = requests.delete(f"{base}{path}", params=p,
                        headers={"X-MBX-APIKEY": API_KEY}, timeout=10)
    return r.json()


def bn_put(base, path, params=None):
    p = _sign(dict(params or {}))
    r = requests.put(f"{base}{path}", data=urlencode(p),
                     headers={"X-MBX-APIKEY": API_KEY,
                              "Content-Type": "application/x-www-form-urlencoded"}, timeout=10)
    return r.json()


# Shortcuts
def spot_get(path, params=None):    return bn_get(SPOT_URL, path, params)
def spot_post(path, params=None):   return bn_post(SPOT_URL, path, params)
def spot_delete(path, params=None): return bn_delete(SPOT_URL, path, params)
def fapi_get(path, params=None):    return bn_get(FAPI_URL, path, params)
def fapi_post(path, params=None):   return bn_post(FAPI_URL, path, params)
def fapi_delete(path, params=None): return bn_delete(FAPI_URL, path, params)
def fapi_put(path, params=None):    return bn_put(FAPI_URL, path, params)

---

Spot Endpoints

Account

Order Placement

Spot order params: symbol, side (BUY/SELL), type (LIMIT/MARKET/STOP_LOSS/TAKE_PROFIT/STOP_LOSS_LIMIT/TAKE_PROFIT_LIMIT/LIMIT_MAKER), timeInForce (GTC/IOC/FOK), quantity, quoteOrderQty (market buy by quote), price, `newClientOrderId` (REQUIRED: must start with `x-GBN6HWR2`, ≤36 chars)

Order Query

Advanced Order Types

Smart Order Routing (SOR)

---

USDS-Margined Futures Endpoints

Account & Position

Order Placement

Futures order params: symbol, side (BUY/SELL), positionSide (BOTH/LONG/SHORT), type (LIMIT/MARKET/STOP/STOP_MARKET/TAKE_PROFIT/TAKE_PROFIT_MARKET/TRAILING_STOP_MARKET), quantity, price, stopPrice, timeInForce, reduceOnly, `newClientOrderId` (REQUIRED: must start with `x-52DDFAFN`, ≤36 chars)

Order Modification

Order Cancellation

Order Query

Leverage & Margin

---

Symbol Format

• Spot: BTCUSDT (no separator)
• Futures: BTCUSDT (no separator)

Rate Limits

• Orders: tracked per 10s and per 1min per UID
• Public market data: IP-based
• Repeated violations → auto IP ban (2min to 3 days)

Binance Trading

Spot Base URL: https://api.binance.com | Futures Base URL: https://fapi.binance.com

Spot: BTCUSDT | Futures: BTCUSDT | Testnet: https://testnet.binance.vision (spot) / https://demo-fapi.binance.com (futures)

Full details in references/binance-api-reference.md

Authentication

Credentials (from .env): BINANCE_API_KEY, BINANCE_SECRET_KEY

No Binance account? Register at [https://www.binance.com/](https://www.binance.com/)

Verify credentials before any private call. If missing — STOP.

Signature: HMAC-SHA256(secret, queryString + requestBody) → hex

• timestamp: Unix milliseconds (always required)
• signature must be the last parameter

Headers:

X-MBX-APIKEY: <api_key>
Content-Type: application/x-www-form-urlencoded   (POST)

Python signature implementation: references/binance-api-reference.md

Broker ID (Blave — MANDATORY on every order)

Binance brokers are attached per order via newClientOrderId, not via a header. Every place-order call MUST include newClientOrderId starting with x-<BROKER_ID>:

Rules:

• Prefix starts with literal x- (lowercase), then the broker ID
• Total length ≤ 36 chars; append a unique suffix (timestamp/uuid fragment) to keep each ID unique
• Applies to: /api/v3/order, /api/v3/order/cancelReplace, /api/v3/sor/order, /api/v3/orderList/oco|oto|otoco, /fapi/v1/order, /fapi/v1/batchOrders, /fapi/v1/algoOrder, and their test/modify variants
• Batch orders: every order in the batch needs its own qualifying newClientOrderId
• If user supplies a custom newClientOrderId, reject it or prepend the broker prefix — never strip the prefix

import time, uuid

def spot_cid(suffix: str = "") -> str:
    tag = suffix or uuid.uuid4().hex[:8]
    return f"x-GBN6HWR2{tag}"[:36]

def fut_cid(suffix: str = "") -> str:
    tag = suffix or uuid.uuid4().hex[:8]
    return f"x-52DDFAFN{tag}"[:36]

# Spot place order
spot_post("/api/v3/order", {
    "symbol": "BTCUSDT", "side": "BUY", "type": "MARKET",
    "quantity": "0.001",
    "newClientOrderId": spot_cid(),
})

# Futures place order
fapi_post("/fapi/v1/order", {
    "symbol": "BTCUSDT", "side": "BUY", "type": "MARKET",
    "quantity": "0.001",
    "newClientOrderId": fut_cid(),
})

Operation Flow

Step 0: Credential Check

Verify BINANCE_API_KEY, BINANCE_SECRET_KEY. If missing — STOP. Default to Mainnet unless user explicitly requests Testnet.

Step 1: Pre-Trade Check (Futures)

• Query positions: GET /fapi/v2/positionRisk?symbol=<SYMBOL>
• If position exists → inherit leverage and margin type, do NOT override

Step 2: Execute

• READ → call, parse, display
• WRITE → present summary → ask "CONFIRM" → execute

Step 3: Verify

After order → query order status. After close → query positions.

Quick Reference — Spot

Quick Reference — USDS-M Futures

Security

• WRITE operations require "CONFIRM"
• Always show liquidation price before opening leveraged positions
• "Not financial advice. Trading carries significant risk of loss."

References

• references/binance-api-reference.md — spot + futures endpoints, Python signature

BingX API Reference

Base URL

Prefer .com; only fall back to .pro on network-level failures. Default to live unless user explicitly requests paper trading.

---

Authentication

Credentials (from .env): BINGX_API_KEY, BINGX_SECRET_KEY

Signature: HMAC-SHA256

1. Collect all params (query + body) + timestamp (Unix ms)
2. Sort alphabetically by key (unencoded)
3. Concatenate as key=value&key=value
4. signature = HMAC-SHA256(secret, canonical_string) → hex
5. Append &signature=<hex> to query string or body

Headers (all requests):

X-BX-APIKEY: <api_key>
X-SOURCE-KEY: BX-AI-SKILL

Response format: {"code": 0, "msg": "", "data": ...} — code == 0 is success.

---

Python Signature Implementation

import time, hmac, hashlib, json, os, requests
from dotenv import dotenv_values
from urllib.parse import urlencode

_env       = dotenv_values()
API_KEY    = _env["BINGX_API_KEY"]
SECRET_KEY = _env["BINGX_SECRET_KEY"]
BASE_URL   = "https://open-api.bingx.com"
FALLBACK   = "https://open-api.bingx.pro"
HEADERS    = {"X-BX-APIKEY": API_KEY, "X-SOURCE-KEY": "BX-AI-SKILL"}


def _sign(params: dict) -> str:
    """Build canonical string from sorted params and return HMAC-SHA256 hex signature."""
    params["timestamp"] = str(int(time.time() * 1000))
    canonical = "&".join(f"{k}={v}" for k, v in sorted(params.items()))
    sig = hmac.new(SECRET_KEY.encode(), canonical.encode(), hashlib.sha256).hexdigest()
    return canonical + f"&signature={sig}"


def bingx_get(path: str, params: dict = {}):
    """Signed GET request with domain fallback."""
    qs = _sign(dict(params))
    for base in [BASE_URL, FALLBACK]:
        try:
            r = requests.get(f"{base}{path}?{qs}", headers=HEADERS, timeout=10)
            data = r.json()
            if data.get("code") != 0:
                raise Exception(f"BingX error {data.get('code')}: {data.get('msg')}")
            return data.get("data")
        except requests.exceptions.ConnectionError:
            if base == FALLBACK: raise
    return None


def bingx_post(path: str, params: dict = {}):
    """Signed POST request (form-encoded) with domain fallback."""
    body = _sign(dict(params))
    for base in [BASE_URL, FALLBACK]:
        try:
            r = requests.post(f"{base}{path}", data=body, headers={
                **HEADERS, "Content-Type": "application/x-www-form-urlencoded"
            }, timeout=10)
            data = r.json()
            if data.get("code") != 0:
                raise Exception(f"BingX error {data.get('code')}: {data.get('msg')}")
            return data.get("data")
        except requests.exceptions.ConnectionError:
            if base == FALLBACK: raise
    return None


def bingx_delete(path: str, params: dict = {}):
    """Signed DELETE request with domain fallback."""
    qs = _sign(dict(params))
    for base in [BASE_URL, FALLBACK]:
        try:
            r = requests.delete(f"{base}{path}?{qs}", headers=HEADERS, timeout=10)
            data = r.json()
            if data.get("code") != 0:
                raise Exception(f"BingX error {data.get('code')}: {data.get('msg')}")
            return data.get("data")
        except requests.exceptions.ConnectionError:
            if base == FALLBACK: raise
    return None

---

Account Balance Endpoints

BingX has three separate accounts: Fund, Spot, Swap. Assets don't auto-transfer — query all three to see full picture.

---

Perpetual Futures (Swap) Endpoints

Order Management

Place order params:

Cancel Orders

Query Orders

Position Management

Leverage & Mode Settings

Order Modification

TWAP Orders

Additional

---

Spot Endpoints

Order Management

Spot order types: MARKET, LIMIT, TAKE_STOP_LIMIT, TAKE_STOP_MARKET, TRIGGER_LIMIT, TRIGGER_MARKET

Query Orders

OCO Orders

---

Symbol Format

• Perpetual futures: BTC-USDT (with hyphen)
• Spot: BTC-USDT (with hyphen)

Notes

• orderID (string) is preferred over orderId (numeric) for large IDs to avoid precision loss
• Order history queries have a max 7-day range per request
• Position history max 3-month span
• Kill switch countdown: 10-120 seconds, must send heartbeat to reset

BingX Trading

Base URL: https://open-api.bingx.com | Fallback: https://open-api.bingx.pro | Paper (VST): https://open-api-vst.bingx.com

Spot: BTC-USDT | Perpetual: BTC-USDT | Success: "code": 0

42 swap endpoints + 17 spot endpoints — full details in references/bingx-api-reference.md

Authentication

Credentials (from .env): BINGX_API_KEY, BINGX_SECRET_KEY

No BingX account? Register at [https://bingxdao.com/invite/SU0SEU/](https://bingxdao.com/invite/SU0SEU/)

Verify credentials before any private call. If missing — STOP.

Signature: HMAC-SHA256(secret, sorted_params_canonical_string) → hex, appended as &signature=<hex>

• Collect all params + timestamp (Unix ms)
• Sort alphabetically by key, concatenate as key=value&key=value

Headers (all requests):

X-BX-APIKEY: <api_key>
X-SOURCE-KEY: BX-AI-SKILL

`X-SOURCE-KEY: BX-AI-SKILL` is MANDATORY on every request — no exceptions.

Python signature implementation and helper functions: references/bingx-api-reference.md

Operation Flow

Step 0: Credential Check

Verify BINGX_API_KEY, BINGX_SECRET_KEY. If missing — STOP. Default to Live unless user explicitly requests paper trading (VST).

Step 1: Pre-Trade Check (Swap)

• Query position mode: GET /openApi/swap/v1/positionSide/dual
• Query leverage: GET /openApi/swap/v2/trade/leverage?symbol=<SYMBOL>
• If position exists → inherit leverage and margin type, do NOT override

Step 2: Execute

• READ → call, parse, display
• WRITE → present summary → ask "CONFIRM" → execute

Step 3: Verify

After order → query order status. After close → query positions.

Quick Reference

Security

• WRITE operations require "CONFIRM"
• Always show liquidation price before opening leveraged positions
• "Not financial advice. Trading carries significant risk of loss."

References

• references/bingx-api-reference.md — 59 endpoints, Python signature, full params

---

Bitfinex Trading & Funding

Base URL: https://api.bitfinex.com (authenticated) | https://api-pub.bitfinex.com (public)

Symbol format: Trading tBTCUSD, tETHUST (UST=USDT) | Funding fUSD, fBTC, fUST

Success: response array, first element is not "error" | Error: ["error", CODE, "message"]

Authentication

Credentials (from .env): BITFINEX_API_KEY, BITFINEX_API_SECRET

No Bitfinex account? Register at [https://www.bitfinex.com/sign-up?refcode=ZZDLtrXMF](https://www.bitfinex.com/sign-up?refcode=ZZDLtrXMF)

Verify credentials before any private call. If missing — STOP.

Signature: HMAC-SHA384 (NOT SHA256)

import hmac, hashlib, json, time, requests

def bfx_request(path, body=None):
    body = body or {}
    nonce = str(int(time.time() * 1_000_000))
    body_json = json.dumps(body)
    sig_payload = f"/api/{path}{nonce}{body_json}"
    sig = hmac.new(
        BITFINEX_API_SECRET.encode(),
        sig_payload.encode(),
        hashlib.sha384
    ).hexdigest()
    headers = {
        "bfx-nonce": nonce,
        "bfx-apikey": BITFINEX_API_KEY,
        "bfx-signature": sig,
        "content-type": "application/json",
    }
    return requests.post(f"https://api.bitfinex.com/{path}",
                         headers=headers, data=body_json)

Nonce: strictly increasing per API key. Use int(time.time() * 1_000_000) (microseconds).

Affiliate Code

Always include `aff_code` in the `meta` field of every order:

{"meta": {"aff_code": "ZZDLtrXMF"}}

5% developer reward on every trade fee. Fixed, does not reduce over time.

Operation Flow

Step 0: Credential Check

Verify BITFINEX_API_KEY, BITFINEX_API_SECRET. If missing — STOP.

Step 1: Pre-Trade Check

POST /v2/auth/r/wallets → check balance in correct wallet (exchange / margin / funding).

Step 2: Execute

• READ → call, parse, display
• WRITE → present summary → ask "CONFIRM" → execute

Step 3: Verify

After order → POST /v2/auth/r/orders → confirm status. After funding → POST /v2/auth/r/funding/offers.

---

Wallet Types

Transfer between wallets: POST /v2/auth/w/transfer

---

Order Types

"EXCHANGE" prefix = spot wallet. No prefix = margin wallet.

Order Flags

Combine by summing: Hidden + Post Only = 4160

---

Key Endpoints — Trading

Place Order — Parameters

{
  "type": "EXCHANGE LIMIT",
  "symbol": "tBTCUSD",
  "amount": "0.01",
  "price": "50000",
  "flags": 0,
  "meta": {"aff_code": "ZZDLtrXMF"}
}

Cancel Order

{"id": 123456789}

Or by client ID: {"cid": 12345, "cid_date": "2026-04-17"}

Transfer Between Wallets

{
  "from": "exchange",
  "to": "funding",
  "currency": "USD",
  "amount": "1000"
}

---

Key Endpoints — Funding (Lending)

Submit Funding Offer — Parameters

{
  "type": "LIMIT",
  "symbol": "fUSD",
  "amount": "1000",
  "rate": "0.0002",
  "period": 2
}

Funding types:

• LIMIT — fixed rate
• FRRDELTAVAR — Flash Return Rate + delta (variable, rate adjusts)
• FRRDELTAFIX — Flash Return Rate + delta (fixed after match)

Cancel Funding Offer

{"id": 987654321}

Funding Loans vs Credits

• Loans (/funding/loans) — your lent funds that are NOT currently used in a position
• Credits (/funding/credits) — your lent funds that ARE currently used in a position

---

Response Arrays

Bitfinex v2 returns arrays, not objects. Key mappings:

Order Array

Wallet Array

Position Array

Funding Offer Array

---

Security

• WRITE operations require "CONFIRM"
• Always show liquidation price before opening margin positions
• "Not financial advice. Trading carries significant risk of loss."

---

Bitget API Reference

Base URL

https://api.bitget.com

Success response: "code": "00000" — all other codes are errors.

---

Authentication

Credentials (from .env): BITGET_API_KEY, BITGET_SECRET_KEY, BITGET_PASSPHRASE

Signature: Base64(HMAC-SHA256(secret, timestamp + METHOD + path + body))

• timestamp: Unix milliseconds
• GET body = ""
• POST body = compact JSON

Headers (authenticated requests):

ACCESS-KEY: <api_key>
ACCESS-SIGN: <base64 signature>
ACCESS-PASSPHRASE: <passphrase>
ACCESS-TIMESTAMP: <unix ms>
Content-Type: application/json
locale: en-US

---

Python Signature Implementation

import time, hmac, hashlib, base64, json, os, requests
from dotenv import dotenv_values

_env        = dotenv_values()
API_KEY     = _env["BITGET_API_KEY"]
SECRET_KEY  = _env["BITGET_SECRET_KEY"]
PASSPHRASE  = _env["BITGET_PASSPHRASE"]
BASE_URL    = "https://api.bitget.com"


def _sign(ts, method, path, body_str=""):
    msg = f"{ts}{method}{path}{body_str}"
    mac = hmac.new(SECRET_KEY.encode(), msg.encode(), hashlib.sha256).digest()
    return base64.b64encode(mac).decode()


def _headers(method, path, body_str=""):
    ts = str(int(time.time() * 1000))
    return {
        "ACCESS-KEY": API_KEY,
        "ACCESS-SIGN": _sign(ts, method, path, body_str),
        "ACCESS-PASSPHRASE": PASSPHRASE,
        "ACCESS-TIMESTAMP": ts,
        "Content-Type": "application/json",
        "locale": "en-US",
    }


def bitget_get(path, params=None):
    qs = ""
    if params:
        qs = "?" + "&".join(f"{k}={v}" for k, v in params.items())
    h = _headers("GET", path + qs)
    r = requests.get(f"{BASE_URL}{path}", params=params, headers=h, timeout=10)
    data = r.json()
    if data.get("code") != "00000":
        raise Exception(f"Bitget error {data.get('code')}: {data.get('msg')}")
    return data.get("data")


def bitget_post(path, body=None):
    body_str = json.dumps(body, separators=(",", ":")) if body else ""
    h = _headers("POST", path, body_str)
    r = requests.post(f"{BASE_URL}{path}", data=body_str, headers=h, timeout=10)
    data = r.json()
    if data.get("code") != "00000":
        raise Exception(f"Bitget error {data.get('code')}: {data.get('msg')}")
    return data.get("data")

---

Account Balance

---

Spot Endpoints

Market Data (Public)

Trading (Private)

Spot order params: symbol, side (buy/sell), orderType (limit/market), price, size, force (gtc/ioc/fok/post_only)

Plan Orders (Private)

---

Futures (Mix) Endpoints

Market Data (Public)

Trading (Private)

Futures order params: symbol, productType (USDT-FUTURES/USDC-FUTURES/COIN-FUTURES), side (buy/sell), tradeSide (open/close), orderType (limit/market), price, size, marginCoin, leverage

Position Management (Private)

Configuration (Private)

---

Transfers

---

Symbol Format

• Spot: BTCUSDT
• Futures: BTCUSDT with productType=USDT-FUTURES

Rate Limits

• Public: 10-20 req/s per IP
• Private: 5-10 req/s per UID
• Configuration: 5 req/s per UID

Bitget Trading

Base URL: https://api.bitget.com | Spot: BTCUSDT | Futures: BTCUSDT + productType=USDT-FUTURES | Success: "code": "00000"

Full details in references/bitget-api-reference.md

Authentication

Credentials (from .env): BITGET_API_KEY, BITGET_SECRET_KEY, BITGET_PASSPHRASE

No Bitget account? Register at [https://www.bitget.com/](https://www.bitget.com/)

Verify credentials before any private call. If missing — STOP.

Signature: Base64(HMAC-SHA256(secret, timestamp + METHOD + path + body))

• timestamp: Unix milliseconds
• GET body = ""
• POST body = compact JSON (no spaces)

Headers (authenticated requests):

ACCESS-KEY: <api_key>
ACCESS-SIGN: <base64 signature>
ACCESS-PASSPHRASE: <passphrase>
ACCESS-TIMESTAMP: <unix ms>
Content-Type: application/json
locale: en-US

Python signature implementation: references/bitget-api-reference.md

Operation Flow

Step 0: Credential Check

Verify BITGET_API_KEY, BITGET_SECRET_KEY, BITGET_PASSPHRASE. If missing — STOP.

Step 1: Pre-Trade Check (Futures)

• Query positions: GET /api/v2/mix/position/all-position?productType=USDT-FUTURES
• If position exists → inherit leverage and margin mode, do NOT override

Step 2: Execute

• READ → call, parse, display
• WRITE → present summary → ask "CONFIRM" → execute

Step 3: Verify

After order → query order status. After close → query positions.

Quick Reference

Security

• WRITE operations require "CONFIRM"
• Always show liquidation price before opening leveraged positions
• "Not financial advice. Trading carries significant risk of loss."

References

• references/bitget-api-reference.md — spot + futures endpoints, Python signature

---

Close Position Workflow

Credentials: Read from .env — BITMART_API_KEY, BITMART_API_SECRET, BITMART_API_MEMO.

Scenario: Close a Long Position

User prompt: "Close my BTC long position on BitMart"

Step 1: Get current positions

curl -s -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  'https://api-cloud-v2.bitmart.com/contract/private/position-v2?symbol=BTCUSDT'

Expected response:

{
  "code": 1000,
  "data": [
    {
      "symbol": "BTCUSDT",
      "leverage": "10",
      "current_amount": "100",
      "position_amount": "100",
      "position_side": "long",
      "entry_price": "67000.0",
      "mark_price": "67500.0",
      "liquidation_price": "60500.0",
      "unrealized_pnl": "50.00",
      "initial_margin": "670.00",
      "open_type": "cross"
    }
  ]
}

If no position is found, inform the user:

No open BTCUSDT long position found. Nothing to close.

If multiple positions exist (e.g., both long and short in hedge mode), ask the user which one to close.

Step 2: Determine close side

For a long position: side = 3

Step 3: Present close summary and ask for CONFIRM

Close Position Summary:
  Symbol: BTCUSDT
  Direction: Close Long (sell_close_long, side=3)
  Size: 100 contracts (entire position)
  Type: Market
  Entry Price: 67,000.0 USDT
  Current Mark Price: 67,500.0 USDT
  Unrealized PnL: +50.00 USDT (profit)
  Estimated Realized PnL: ~+50.00 USDT

Please type CONFIRM to proceed.

Step 4: Submit close order (after user confirms)

Note: Close orders only require symbol, side, type, and size.

Do NOT include leverage or open_type — these fields are ignored for close orders and may cause confusion.

For limit close, add price. For partial close, use a smaller size.

TIMESTAMP=$(date +%s000)
BODY='{"symbol":"BTCUSDT","side":3,"type":"market","size":100}'
SIGN=$(echo -n "${TIMESTAMP}#${BITMART_API_MEMO}#${BODY}" | openssl dgst -sha256 -hmac "$BITMART_API_SECRET" | awk '{print $NF}')
curl -s -X POST 'https://api-cloud-v2.bitmart.com/contract/private/submit-order' \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  -H "Content-Type: application/json" \
  -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "X-BM-SIGN: $SIGN" \
  -H "X-BM-TIMESTAMP: $TIMESTAMP" \
  -d "$BODY"

Expected response:

{
  "code": 1000,
  "data": {
    "order_id": 23456789012345680
  }
}

Step 5: Verify position closed

curl -s -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  'https://api-cloud-v2.bitmart.com/contract/private/position-v2?symbol=BTCUSDT'

Verify the position no longer appears or the parsed current_amount is 0.

Also check the fill details:

curl -s -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  'https://api-cloud-v2.bitmart.com/contract/private/order?symbol=BTCUSDT&order_id=23456789012345680'

Step 6: Report realized PnL

Position Closed Successfully:
  Symbol: BTCUSDT
  Direction: Closed Long
  Size: 100 contracts
  Entry Price: 67,000.0 USDT
  Exit Price: 67,498.5 USDT
  Realized PnL: +49.85 USDT
  Fees: 4.05 USDT
  Net PnL: +45.80 USDT
  Margin Released: 670.00 USDT

Not financial advice. You are solely responsible for your investment decisions.

---

Scenario: Partial Close

User prompt: "Close half of my BTC long"

The flow is the same, but with size = 50 (half of 100):

{"symbol":"BTCUSDT","side":3,"type":"market","size":50}

After partial close, report both the closed portion and the remaining position.

---

Scenario: Close a Short Position

User prompt: "Close my ETH short position"

• Query positions for ETHUSDT
• Use side = 2 (buy_close_short)
• For short positions, profit occurs when exit price < entry price

{"symbol":"ETHUSDT","side":2,"type":"market","size":50}

---

Scenario: Limit Close

User prompt: "Close my BTC long at 70000"

Use a limit order instead of market:

{"symbol":"BTCUSDT","side":3,"type":"limit","price":"70000","size":100,"mode":1}

Inform the user that the order will remain open until the price reaches 70000 or they cancel it.

---

Error Handling

BitMart Futures Trading

Base URL: https://api-cloud-v2.bitmart.com | Symbol: BTCUSDT (no underscore) | Success: code == 1000

53 endpoints — full details in references/bitmart-api-reference.md

Authentication

Credentials (from .env): BITMART_API_KEY, BITMART_API_SECRET, BITMART_API_MEMO

No BitMart account? Register at [https://www.bitmart.com/invite/cMEArf](https://www.bitmart.com/invite/cMEArf)

Verify credentials before any private call. If missing — STOP.

Signature: HMAC-SHA256(secret, "{timestamp}#{memo}#{body}") — GET body = ""

Always include `X-BM-BROKER-ID: BlaveData666666` on ALL requests.

IP Whitelist: Use public IP (curl https://checkip.amazonaws.com), not private IP (10.x, 172.x, 192.168.x).

Signature Python implementation and common mistakes: references/bitmart-signature.md

Operation Flow

Step 0: Credential Check

Verify BITMART_API_KEY, BITMART_API_SECRET, BITMART_API_MEMO. If missing — STOP.

Step 1.1: Query Positions (READ)

GET /contract/private/position-v2 (KEYED, no signature needed) Filter current_amount != "0" → display symbol, position_side, current_amount, entry_price, leverage, open_type, liquidation_price, unrealized_pnl

Step 1.5: Pre-Trade Check (MANDATORY before open/leverage)

1. Call GET /contract/private/position-v2?symbol=<SYMBOL> 2. If current_amount non-zero → inherit leverage and open_type, do NOT override 3. If user wants different values → STOP, warn to close position first

Step 1.55: Pre-Mode-Switch Check

Confirm no positions (Step 1.5) AND no open orders (GET /contract/private/get-open-orders). If either exists → STOP.

Step 1.6: TP/SL on Existing Position

POST /contract/private/submit-tp-sl-order — submit TP and SL as two separate calls

Step 2: Execute

• READ → call, parse, display
• WRITE → present summary → ask "CONFIRM" → execute

submit-order rules:

Step 3: Verify

• After open: position-v2 → report entry price, size, leverage, liquidation price
• After close: position-v2 → report realized PnL
• After order: GET /contract/private/order → confirm status

Order Reference

Side: 1 Open Long / 2 Close Short / 3 Close Long / 4 Open Short

Mode: 1 GTC / 2 FOK / 3 IOC / 4 Maker Only

Timestamps: ms — always convert to local time for display.

Error Handling

Spot ↔ Futures Transfer

Present summary → ask "CONFIRM" → execute.

Endpoint: POST https://api-cloud-v2.bitmart.com/account/v1/transfer-contract (SIGNED)

Rate limit: 1 req/2sec. ⚠️ /spot/v1/transfer-contract does NOT exist.

Security

• WRITE operations require "CONFIRM"
• Always show liquidation price before opening leveraged positions
• "Not financial advice. Futures trading carries significant risk of loss."

References

• references/bitmart-api-reference.md — 53 endpoints
• references/bitmart-signature.md — Python signature implementation
• references/bitmart-open-position.md / bitmart-close-position.md / bitmart-plan-order.md / bitmart-tp-sl.md

---

Open Position Workflow

Credentials: Read from .env — BITMART_API_KEY, BITMART_API_SECRET, BITMART_API_MEMO.

Scenario: Open a Long Position

User prompt: "Open a 10x long BTC position with 100 contracts on BitMart"

Step 1: Pre-flight — Check futures balance

curl -s -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  'https://api-cloud-v2.bitmart.com/contract/private/assets-detail'

Verify the user has sufficient available_balance in USDT. If insufficient, suggest transferring from spot:

Insufficient futures balance. Available: 50.00 USDT, Required: ~670 USDT (estimated).
Would you like to transfer USDT from your spot wallet?

Step 2: Pre-flight — Check contract details

curl -s -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  'https://api-cloud-v2.bitmart.com/contract/public/details?symbol=BTCUSDT'

Validate:

• contract_size — to calculate margin requirement
• min_volume — ensure order size meets minimum
• max_volume — ensure order size does not exceed maximum
• max_leverage — ensure requested leverage is supported
• price_precision — for limit orders

Step 3: Pre-flight — Check leverage brackets

curl -s -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  'https://api-cloud-v2.bitmart.com/contract/public/leverage-bracket?symbol=BTCUSDT'

Verify the requested leverage (10x) is available for the position size. If position size exceeds the tier limit, warn the user:

Warning: At 10x leverage, maximum position is 500,000 contracts.
Your requested 100 contracts is within limits.

Step 3.5: Check existing position (MANDATORY)

Before setting leverage or submitting an order, check for existing positions:

curl -s -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  'https://api-cloud-v2.bitmart.com/contract/private/position-v2?symbol=BTCUSDT'

position-v2 returns a data[] array. Do not assume there is only one row:

• In one_way_mode, you will typically see one row with position_side="both"
• In some account / mode combinations, you may see multiple rows for the same symbol (for example position_side="long" and position_side="short"), even when both sides are zero

Use this step to answer two questions only:

• Does a position already exist?
• If yes, which leverage and open_type must be inherited?

Do not rely on position-v2 for position_mode. Query get-position-mode later only when the workflow becomes mode-sensitive (for example, deciding whether to switch modes or explaining hedge vs one-way behavior).

Evaluate the entire data[] array:

Parse each row's current_amount as a number before comparing it. The API returns string values such as "0".

If any row's parsed `current_amount` is non-zero (existing position found):

• Treat the symbol as having an existing position
• Use the relevant non-zero position row's leverage and open_type values in the order — do NOT send different values
• If user requested different leverage or margin mode → STOP and warn:

"You have an existing position. Close it first before changing leverage or margin mode."

• Do NOT call submit-leverage with different values — API will return 40012/40040
• Do not attempt to change position_mode while an existing position is present
• Skip Step 4 and continue with the current account mode in Step 5

If every row's parsed `current_amount` is 0 (no existing position):

• Proceed with user-requested leverage and margin mode (Step 4)

Step 4: Set leverage (if needed — skip if existing position found in Step 3.5)

Only execute this step when no existing position was found in Step 3.5:

TIMESTAMP=$(date +%s000)
BODY='{"symbol":"BTCUSDT","leverage":"10","open_type":"cross"}'
SIGN=$(echo -n "${TIMESTAMP}#${BITMART_API_MEMO}#${BODY}" | openssl dgst -sha256 -hmac "$BITMART_API_SECRET" | awk '{print $NF}')
curl -s -X POST 'https://api-cloud-v2.bitmart.com/contract/private/submit-leverage' \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  -H "Content-Type: application/json" \
  -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "X-BM-SIGN: $SIGN" \
  -H "X-BM-TIMESTAMP: $TIMESTAMP" \
  -d "$BODY"

Step 5: Check current position mode and set it only if safe

Query the account-wide position_mode only when you need a mode-sensitive decision, such as deciding whether a mode switch is needed or explaining current hedge/one-way behavior:

curl -s -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  'https://api-cloud-v2.bitmart.com/contract/private/get-position-mode'

Read the current account-wide position mode first:

• If Step 3.5 found any existing position (any row's parsed current_amount is non-zero), do not call set-position-mode
• If the user requested a different position mode while an existing position is present, STOP and tell them to close the existing position first
• Before any mode switch, check that there are no open orders on the account:

curl -s -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  'https://api-cloud-v2.bitmart.com/contract/private/get-open-orders'

• If any open orders are present, STOP and tell the user to cancel them before changing position_mode
• Only consider calling set-position-mode when Step 3.5 found no existing position and get-open-orders is empty

If the user wants hedge mode (to hold long and short simultaneously), Step 3.5 found no existing position, and the current mode is not already hedge_mode, set it:

TIMESTAMP=$(date +%s000)
BODY='{"position_mode":"hedge_mode"}'
SIGN=$(echo -n "${TIMESTAMP}#${BITMART_API_MEMO}#${BODY}" | openssl dgst -sha256 -hmac "$BITMART_API_SECRET" | awk '{print $NF}')
curl -s -X POST 'https://api-cloud-v2.bitmart.com/contract/private/set-position-mode' \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  -H "Content-Type: application/json" \
  -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "X-BM-SIGN: $SIGN" \
  -H "X-BM-TIMESTAMP: $TIMESTAMP" \
  -d "$BODY"

Note: BitMart rejects set-position-mode when the account is not in a clean state for mode switching. Existing positions will fail, and open orders may also fail with 40059 ("Some positions exist and the mode switching fails."). If mode switching fails, stop and ask the user to clear existing positions / open orders before retrying.

Step 6: Present order summary and ask for CONFIRM

Display to user:

Position Summary:
  Symbol: BTCUSDT
  Direction: Long (buy_open_long, side=1)
  Type: Market
  Size: 100 contracts
  Leverage: 10x
  Margin Mode: Cross
  Estimated Entry: ~67,123 USDT
  Estimated Margin: ~671 USDT
  Estimated Liquidation: ~60,500 USDT

  WARNING: Futures trading carries significant risk. Higher leverage
  amplifies both gains and losses. You could lose your entire margin.

Please type CONFIRM to proceed.

Step 7: Submit order (after user confirms)

Parameter rules (must match SKILL.md Step 2a):

• Market order: do NOT include price field — it is ignored and causes confusion
• If existing position found in Step 3.5: use leverage and open_type from the relevant non-zero position row, not user-requested values
• `size` must be an integer (number of contracts) — check min/max via GET /contract/public/details
• Maker Only (`mode=4`): only valid with type=limit, never with type=market

TIMESTAMP=$(date +%s000)
BODY='{"symbol":"BTCUSDT","side":1,"type":"market","size":100,"leverage":"10","open_type":"cross"}'
SIGN=$(echo -n "${TIMESTAMP}#${BITMART_API_MEMO}#${BODY}" | openssl dgst -sha256 -hmac "$BITMART_API_SECRET" | awk '{print $NF}')
curl -s -X POST 'https://api-cloud-v2.bitmart.com/contract/private/submit-order' \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  -H "Content-Type: application/json" \
  -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "X-BM-SIGN: $SIGN" \
  -H "X-BM-TIMESTAMP: $TIMESTAMP" \
  -d "$BODY"

Expected response:

{
  "code": 1000,
  "data": {
    "order_id": 23456789012345678
  }
}

Step 8: Verify position

curl -s -H "X-BM-KEY: $BITMART_API_KEY" \
  -H "User-Agent: bitmart-skills/futures/v2026.3.23" \
  -H "X-BM-BROKER-ID: BlaveData666666" \
  'https://api-cloud-v2.bitmart.com/contract/private/position-v2?symbol=BTCUSDT'

Step 9: Report results

Position Opened Successfully:
  Symbol: BTCUSDT
  Direction: Long
  Size: 100 contracts
  Entry Price: 67,123.4 USDT
  Leverage: 10x
  Margin Mode: Cross
  Margin Used: 671.23 USDT
  Liquidation Price: 60,500.0 USDT
  Mark Price: 67,125.0 USDT
  Unrealized PnL: +0.16 USDT

Not financial advice. Futures trading carries significant risk of loss.

---

Scenario: Open a Short Position

User prompt: "Short ETH with 20x leverage, 50 contracts, isolated margin"

The flow is the same as above, with these differences:

• Side: 4 (sell_open_short) instead of 1
• Leverage: 20x
• Open type: isolated
• Liquidation direction: above entry price (for shorts, liquidation is at higher price)

Order body:

{"symbol":"ETHUSDT","side":4,"type":"market","size":50,"leverage":"20","open_type":"isolated"}

---

Error Handling