# Opentrade Cex

> Use for centralized exchange trading and account queries: CEX spot/futures orders, open/closed orders, balances, spot assets, futures/perpetual positions, leverage, margin mode, position mode, funding rates, order book, tickers, K-lines, open interest, gamma exposure, large liquidation aggregates, account summary, and trade/position history. Trigger on buy/sell on CEX, long/short, open or close position, set leverage, cancel order, show open orders, show holdings, query positions, CEX balance, gamma exposure, option gamma, GEX, liquidations, 查询持仓, 查询订单, 当前订单, 历史订单, 交易历史, 成交记录. For user-specific holdings, positions, orders, closed orders, or trade history, query CEX first; fall back to DEX/on-chain skills only if CEX has no relevant data or the user explicitly asks for wallet/DEX/on-chain data. Do not use for DEX swaps, token search, custodial wallet management, or transaction broadcasting.

- Skill: `6551team/opentrade-cex` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 6551team/opentrade-cex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/6551team/opentrade-cex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: 6551team (https://skillmd.com/u/6551team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/6551team/opentrade-cex

---


# OpenTrade CEX Trading

41 API endpoints for centralized exchange trading — market data, public metadata, account management, spot & futures orders, positions, and leverage.

> **IMPORTANT**: This is a **CEX (centralized exchange)** trading skill. All trades are executed server-side with built-in risk controls — no private key management or transaction signing required.
>
> **IMPORTANT**: Write operations (place order, close position, set leverage) are protected by a 4-layer risk engine: price deviation check, position limit, rate limit, and balance verification.
>
> **CRITICAL — Required Parameters for Orders**:
> - **`type`** (REQUIRED): Order type must always be specified (`market`, `limit`, `stop_market`, `take_profit_market`). Each type has different parameter requirements.
> - **`hedged`** (REQUIRED): When placing orders (`POST /orders`) or closing positions (`POST /positions/close`), the `hedged` field is required. If the `hedged` value is unknown or not provided by the user, you **MUST** first call `GET /position/mode` to obtain `data.hedged`. Once obtained, the value can be reused for subsequent requests on the same symbol and exchange without re-fetching. Using an incorrect `hedged` value may cause order rejection or affect the wrong position.
> - **`quantity` for close position** (REQUIRED): When closing a position, you must explicitly provide the quantity to close. `0` is not allowed. Use the actual position size from `GET /positions` when closing the full position.
>
> **CRITICAL — Prefer Contract (Swap) Symbol**:
> - When `/market/metadata` returns multiple markets, **default to the perpetual/swap symbol** (e.g., `BTC/USDT:USDT`) rather than the spot symbol (e.g., `BTC/USDT`).
> - Only use the spot symbol when the user explicitly requests spot trading.
> - Always use `symbol` field, NOT `displaySymbol`, when making API calls.

## Pre-flight Checks

Every time before running any CEX command, always follow these steps in order:

1. Find or create a `.env` file in the project root to load the API credentials:
  ```bash
  OPENNEWS_TOKEN=your_token_here
  ```

  Get your API token at: https://www.newsliquid.com/mcp

  **Security warning**: Never commit .env to git (add it to .gitignore) and never expose credentials in logs, screenshots, or chat messages.

2. Set the base URL and auth header:
  ```bash
  BASE_URL="https://ai.6551.io"
  AUTH_HEADER="Authorization: Bearer $OPENNEWS_TOKEN"
  ```

## Skill Routing

- For user-specific holdings/assets, positions, open orders, closed orders, or trade/trading history, **query CEX first** with this skill. If CEX returns no relevant records, then fall back to DEX/on-chain skills:
  - holdings / assets → `opentrade-portfolio`
  - on-chain public trade logs / swap activity → `opentrade-market`
  - broadcast transaction order status → `opentrade-gateway`
- For DEX swaps / on-chain token exchange → use `opentrade-dex-swap`
- For on-chain wallet balances / portfolio → use `opentrade-portfolio`
- For on-chain market data / smart money signals → use `opentrade-market`
- For token search / holders / trending → use `opentrade-token`
- For custodial wallet (BSC/Solana) → use `opentrade-wallet`
- For transaction broadcasting / gas → use `opentrade-gateway`
- For CEX trading (spot, futures, leverage, orders, positions) → use this skill (`opentrade-cex`)

## Supported Exchanges

| ExchangeID | Name |
|------------|------|
| `binance` | Binance |
| `bybit` | Bybit |
| `okx` | OKX |
| `hyperliquid` | Hyperliquid |
| `aster` | Aster |

## Quickstart

```bash
# 1. Get real-time ticker
curl -s "$BASE_URL/open/trader/newsliquid/v1/market/ticker?symbol=BTC/USDT&exchangeId=binance" \
  -H "$AUTH_HEADER"

# 2. Check account balance
curl -s "$BASE_URL/open/trader/newsliquid/v1/account/summary?exchangeId=binance&symbol=BTC/USDT:USDT" \
  -H "$AUTH_HEADER"

# 3. Get position mode (if hedged value is unknown, MUST call before placing orders or closing positions)
curl -s "$BASE_URL/open/trader/newsliquid/v1/position/mode?symbol=BTC/USDT:USDT&exchangeId=binance" \
  -H "$AUTH_HEADER"
# → Returns {"data": {"hedged": false, "info": {"dualSidePosition": false}}, "success": true}

# 4. Place a limit buy order (use hedged value from step 3)
curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/orders" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"symbol":"BTC/USDT:USDT","side":"buy","type":"limit","quantity":0.001,"price":60000,"exchangeId":"binance","hedged":false}'

# 5. Check open orders
curl -s "$BASE_URL/open/trader/newsliquid/v1/orders/open?exchangeId=binance" \
  -H "$AUTH_HEADER"

# 6. Check current positions
curl -s "$BASE_URL/open/trader/newsliquid/v1/positions?exchangeId=binance" \
  -H "$AUTH_HEADER"

# 7. Close a position (use hedged value from step 3, quantity is required)
curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/positions/close" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"symbol":"BTC/USDT:USDT","side":"long","quantity":0.001,"exchangeId":"binance","hedged":false}'
```

> **Note**: Trading pair format follows CCXT standard:
> - **Spot**: `BTC/USDT` (no colon, no leverage)
> - **Perpetual futures (swap)**: `BTC/USDT:USDT` (with `:SETTLE` suffix, supports leverage) — **default choice for most trading operations**
> 
> Always use the exact `symbol` value returned from `GET /market/metadata` to ensure correct market type. **Prefer the contract/swap symbol by default**; use spot only when user explicitly requests it.

## Command Index

### Market Data (no risk control)

| # | Endpoint | Method | Description |
|---|---|---|---|
| 1 | `/open/trader/newsliquid/v1/market/metadata` | GET | Get market metadata (trading pairs, precision, limits) |
| 2 | `/open/trader/newsliquid/v1/market/ticker` | GET | Get real-time ticker (last price, 24h change, volume) |
| 3 | `/open/trader/newsliquid/v1/market/klines` | GET | Get K-line / candlestick data |
| 4 | `/open/trader/newsliquid/v1/market/base-currencies` | GET | Get base currency list (USDT, BTC, etc.) |
| 5 | `/open/trader/newsliquid/v1/market/time` | GET | Get server time |

### Public Metadata (no risk control)

| # | Endpoint | Method | Description |
|---|---|---|---|
| 6 | `/open/trader/newsliquid/v1/public/metadata/orderbook` | GET | Get order book depth data |
| 7 | `/open/trader/newsliquid/v1/public/metadata/tickers` | GET | Get price tickers (multiple symbols) |
| 8 | `/open/trader/newsliquid/v1/public/metadata/ohlcv` | GET | Get OHLCV candlestick data |
| 9 | `/open/trader/newsliquid/v1/public/metadata/trades` | GET | Get recent public trades |
| 10 | `/open/trader/newsliquid/v1/public/metadata/time` | GET | Get exchange server time |
| 11 | `/open/trader/newsliquid/v1/public/metadata/status` | GET | Get exchange operational status |
| 12 | `/open/trader/newsliquid/v1/public/metadata/funding-rate` | GET | Get current funding rate (single symbol) |
| 13 | `/open/trader/newsliquid/v1/public/metadata/funding-rates` | GET | Get funding rates (multiple symbols) |
| 14 | `/open/trader/newsliquid/v1/public/metadata/funding-rate/history` | GET | Get historical funding rates |
| 15 | `/open/trader/newsliquid/v1/public/metadata/funding-rate/exchanges` | GET | Get funding rate across exchanges |
| 16 | `/open/trader/newsliquid/v1/public/metadata/funding-interval` | GET | Get funding interval |
| 17 | `/open/trader/newsliquid/v1/public/metadata/open-interest` | GET | Get current open interest |
| 18 | `/open/trader/newsliquid/v1/public/metadata/open-interest/history` | GET | Get historical open interest |
| 19 | `/open/trader/newsliquid/v1/public/metadata/gamma` | GET | Get equity option gamma exposure by symbol |
| 20 | `/open/trader/newsliquid/v1/public/metadata/liquidations` | GET | Get aggregated large liquidation data |
| 21 | `/open/trader/newsliquid/v1/public/market/index-constituents` | GET | Get contract index price constituents |
| 22 | `/open/trader/newsliquid/v1/public/market/smart-money` | GET | Get smart money signal overview |

### Account (no risk control)

| # | Endpoint | Method | Description |
|---|---|---|---|
| 22 | `/open/trader/newsliquid/v1/account/summary` | GET | Account summary (balance, leverage, max position) |
| 23 | `/open/trader/newsliquid/v1/account/spot` | GET | Query specific spot asset |
| 24 | `/open/trader/newsliquid/v1/account/spots` | GET | Query all spot assets |

### Config (no risk control)

| # | Endpoint | Method | Description |
|---|---|---|---|
| 25 | `/open/trader/newsliquid/v1/config` | GET | Get trading config |
| 26 | `/open/trader/newsliquid/v1/config` | PUT | Update trading config |

### Orders (risk control on create)

| # | Endpoint | Method | Risk | Description |
|---|---|---|---|---|
| 27 | `/open/trader/newsliquid/v1/orders` | POST | Yes | Place order (limit/market/stop-loss/take-profit) |
| 28 | `/open/trader/newsliquid/v1/orders/:orderId` | DELETE | No | Cancel order |
| 29 | `/open/trader/newsliquid/v1/orders/open` | GET | No | List open orders |
| 30 | `/open/trader/newsliquid/v1/orders/closed` | GET | No | List closed orders |

### Positions (risk control on close)

| # | Endpoint | Method | Risk | Description |
|---|---|---|---|---|
| 31 | `/open/trader/newsliquid/v1/positions` | GET | No | List current positions |
| 32 | `/open/trader/newsliquid/v1/positions/history` | GET | No | List historical positions |
| 33 | `/open/trader/newsliquid/v1/positions/close` | POST | Yes | Close position (market price) |

### Trades (no risk control)

| # | Endpoint | Method | Description |
|---|---|---|---|
| 34 | `/open/trader/newsliquid/v1/trades/history` | GET | Get trade execution history |

### Leverage & Margin (risk control on leverage change)

| # | Endpoint | Method | Risk | Description |
|---|---|---|---|---|
| 35 | `/open/trader/newsliquid/v1/leverage` | GET | No | Get available leverage tiers |
| 36 | `/open/trader/newsliquid/v1/leverage/current` | GET | No | Get current leverage setting |
| 37 | `/open/trader/newsliquid/v1/leverage/current` | PUT | Yes | Set leverage multiplier |
| 38 | `/open/trader/newsliquid/v1/margin/mode` | GET | No | Get margin mode |
| 39 | `/open/trader/newsliquid/v1/position/mode` | GET | No | Get position mode (one-way/hedge) |
| 40 | `/open/trader/newsliquid/v1/position/mode` | PUT | No | Set position mode |

## API Reference

### 1. Get Market Metadata

获取指定交易对在所有交易所的市场元数据信息（交易对列表、合约类型、杠杆范围、最小下单量等）。

> **CRITICAL — Symbol Format (CCXT Standard)**:
> 
> **Spot trading pairs**: `BASE/QUOTE` format
> - Example: `BTC/USDT` (spot trading, no leverage)
> - Characteristics: `spot: true`, `swap: false`, `contract: false`, `margin: false`
> 
> **Perpetual futures (swap)**: `BASE/QUOTE:SETTLE` format
> - Example: `BTC/USDT:USDT` (USDT-margined perpetual contract)
> - Characteristics: `spot: false`, `swap: true`, `contract: true`, `margin: true`
> - The `:SETTLE` suffix indicates the settlement currency (usually matches QUOTE)
> 
> **How to distinguish in `/market/metadata` response**:
> 1. Check the `symbol` field format:
>    - Contains `:` → Perpetual futures (e.g., `BTC/USDT:USDT`)
>    - No `:` → Spot (e.g., `BTC/USDT`)
> 2. Check boolean flags:
>    - `spot: true` → Spot trading pair
>    - `swap: true` → Perpetual futures
>    - `contract: true` → Any derivative (futures/swap/option)
> 3. Check `type` field: `"spot"`, `"swap"`, `"future"`, `"option"`
> 
> **IMPORTANT — Use `symbol`, NOT `displaySymbol`**:
> - **Always use the `symbol` field** when calling other endpoints (ticker, orders, positions, etc.)
> - The `displaySymbol` field is for display purposes only and may not work correctly in API calls
> - Example: Use `symbol: "BTC/USDT:USDT"` from the response, not `displaySymbol`
>
> **CRITICAL — Prefer Contract (Swap) Symbol by Default**:
> - When `/market/metadata` returns multiple markets for the same ticker (e.g., both spot `BTC/USDT` and swap `BTC/USDT:USDT`), **prioritize the contract/swap symbol** (`swap: true` or `contract: true`) unless the user explicitly requests spot trading
> - **Why**: Most CEX trading operations (leverage, open/close positions, futures trading) require the contract symbol. Using the spot symbol for these operations will fail or produce unexpected results
> - **Selection priority** (top to bottom):
>   1. **Perpetual futures** (`swap: true`, symbol has `:SETTLE` suffix) — **default choice**
>   2. **Futures** (`future: true`) — if no swap is available
>   3. **Spot** (`spot: true`) — only when user explicitly asks for spot trading (e.g., "buy BTC spot", "spot trade")
> - **User intent signals for spot**: "spot", "现货", "spot trading", "buy and hold"
> - **User intent signals for contract/swap** (default): "long", "short", "leverage", "futures", "perpetual", "做多", "做空", "杠杆", "合约", "open position", "close position"
> - When in doubt, ask the user: "Do you want to trade spot or perpetual futures?"

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/market/metadata?ticker=BTC" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `ticker` | String (query) | Yes | Base currency code (e.g., `BTC`, `ETH`, `SOL`) |

**Response:**
```json
{
  "success": true,
  "data": {
    "ticker": "BTC",
    "markets": [
      {
        "exchangeId": "binance",
        "id": "BTCUSDT",
        "symbol": "BTC/USDT",
        "displaySymbol": "BTC/USDT",
        "active": true,
        "type": "spot",
        "rawType": "spot",
        "baseId": "BTC",
        "baseCurrency": "BTC",
        "quoteId": "USDT",
        "quoteCurrency": "USDT",
        "costMin": 5,
        "amountMin": 0.00001,
        "margin": true,
        "spot": true,
        "swap": false,
        "future": false,
        "option": false,
        "contract": false
      },
      {
        "exchangeId": "binance",
        "id": "BTCUSDT",
        "symbol": "BTC/USDT:USDT",
        "displaySymbol": "BTC/USDT",
        "active": true,
        "type": "swap",
        "rawType": "swap",
        "settleCurrency": "USDT",
        "baseId": "BTC",
        "baseCurrency": "BTC",
        "quoteId": "USDT",
        "quoteCurrency": "USDT",
        "costMin": 50,
        "amountMin": 0.001,
        "margin": false,
        "spot": false,
        "swap": true,
        "future": false,
        "option": false,
        "contract": true
      },
    ]
  },
  "usage": {"cost": 1, "quota": 99}
}
```

---

### 2. Get Ticker

获取指定交易所和交易对的实时行情数据。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/market/ticker?symbol=BTC/USDT&exchangeId=binance" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `symbol` | String (query) | Yes | Trading pair in CCXT format (e.g., `BTC/USDT`) |
| `exchangeId` | String (query) | Yes | Exchange ID: `binance`, `bybit`, `okx`, `hyperliquid` |

**Response:**
```json
{
  "success": true,
  "data": {
    "symbol": "BTC/USDT",
    "last": 67890.50,
    "bid": 67889.00,
    "ask": 67891.00,
    "high": 68500.00,
    "low": 66800.00,
    "volume": 12345.678,
    "timestamp": "2026-03-21T10:30:00Z"
  },
  "usage": {"cost": 1, "quota": 99}
}
```

**Display to user:**
- "BTC/USDT: $67,890.50"
- "Bid: $67,889 | Ask: $67,891"
- "24h High: $68,500 | Low: $66,800 | Volume: 12,345.68 BTC"

---

### 3. Get K-Lines

获取 Binance K 线（蜡烛图）数据。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/market/klines?symbol=BTCUSDT&interval=1h&limit=100" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `symbol` | String (query) | No | Trading pair (default: `BTCUSDT`) |
| `interval` | String (query) | No | K-line interval (default: `1m`): `1m`, `5m`, `15m`, `1h`, `4h`, `1d`, etc. |
| `limit` | Integer (query) | No | Number of candles (default: 100) |

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "openTime": 1679400000000,
      "open": "67800.00",
      "high": "67900.00",
      "low": "67750.00",
      "close": "67850.00",
      "volume": "123.456",
      "closeTime": 1679400059999
    }
  ],
  "usage": {"cost": 1, "quota": 99}
}
```

**Display to user:**
- Summarize recent price action (e.g., "BTC rose from $67,800 to $67,850 in the last hour")
- Mention support/resistance levels if visible

---

### 4. Get Base Currencies

获取所有交易所支持的去重基础币种列表。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/market/base-currencies" \
  -H "$AUTH_HEADER"
```

**Parameters:** None

**Response:**
```json
{
  "success": true,
  "data": ["BTC", "ETH", "SOL", "DOGE", "XRP"],
  "usage": {"cost": 1, "quota": 99}
}
```

---

### 5. Get Server Time

获取 ai-bots-trading 服务器的当前时间。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/market/time" \
  -H "$AUTH_HEADER"
```

**Parameters:** None

**Response:**
```json
{
  "timestamp": 1679400000000,
  "time": "2026-03-21T10:30:00Z",
  "usage": {"cost": 1, "quota": 99}
}
```

---

### 6. Get Order Book

获取指定交易对的订单簿深度数据。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/orderbook?exchangeId=binance&symbol=BTC/USDT&limit=20" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | Yes | Trading pair (e.g., `BTC/USDT`) |
| `limit` | Integer (query) | No | Order book depth limit (default: 20, e.g., 20, 50, 100) |

**Response:**
```json
{
  "success": true,
  "data": {
    "symbol": "BTC/USDT",
    "bids": [[67889.00, 0.5], [67888.00, 1.2]],
    "asks": [[67891.00, 0.3], [67892.00, 0.8]],
    "timestamp": 1679400000000,
    "datetime": "2026-03-21T10:30:00Z"
  }
}
```

---

### 7. Get Price Tickers

获取指定交易所的多个交易对行情数据。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/tickers?exchangeId=binance&symbols=BTC/USDT,ETH/USDT" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbols` | String (query) | No | Comma-separated symbols (e.g., `BTC/USDT,ETH/USDT`). Omit for all symbols. |

**Response:**
```json
{
  "success": true,
  "data": {
    "BTC/USDT": {
      "symbol": "BTC/USDT",
      "last": 67890.50,
      "bid": 67889.00,
      "ask": 67891.00,
      "high": 68500.00,
      "low": 66800.00,
      "volume": 12345.678,
      "timestamp": 1679400000000
    },
    "ETH/USDT": {
      "symbol": "ETH/USDT",
      "last": 3450.20,
      "bid": 3449.50,
      "ask": 3450.80,
      "high": 3500.00,
      "low": 3400.00,
      "volume": 98765.432,
      "timestamp": 1679400000000
    }
  }
}
```

---

### 8. Get OHLCV Data

获取指定交易对的 OHLCV（开盘价、最高价、最低价、收盘价、成交量）K线数据。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/ohlcv?exchangeId=binance&symbol=BTC/USDT&timeframe=1h&limit=50" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | Yes | Trading pair (e.g., `BTC/USDT`) |
| `timeframe` | String (query) | No | Timeframe (default: `1h`): `1m`, `5m`, `15m`, `1h`, `4h`, `1d` |
| `since` | Integer (query) | No | Timestamp in milliseconds to fetch data from |
| `limit` | Integer (query) | No | Number of candles (default: 50) |

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "timestamp": 1679400000000,
      "open": 67800.00,
      "high": 67900.00,
      "low": 67750.00,
      "close": 67850.00,
      "volume": 123.456
    }
  ]
}
```

---

### 9. Get Public Trades

获取指定交易对的最近公开成交记录。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/trades?exchangeId=binance&symbol=BTC/USDT&limit=20" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | Yes | Trading pair (e.g., `BTC/USDT`) |
| `since` | Integer (query) | No | Timestamp in milliseconds to fetch trades from |
| `limit` | Integer (query) | No | Number of trades (default: 20) |

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": "123456",
      "symbol": "BTC/USDT",
      "price": 67890.50,
      "amount": 0.01,
      "cost": 678.905,
      "side": "buy",
      "timestamp": 1679400000000,
      "datetime": "2026-03-21T10:30:00Z",
      "takerOrMaker": "taker"
    }
  ]
}
```

---

### 10. Get Exchange Time

获取指定交易所的服务器时间。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/time?exchangeId=binance" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |

**Response:**
```json
{
  "success": true,
  "data": {
    "timestamp": 1679400000000
  }
}
```

---

### 11. Get Exchange Status

获取指定交易所的运行状态。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/status?exchangeId=binance" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |

**Response:**
```json
{
  "success": true,
  "data": {
    "status": "ok",
    "updated": 1679400000000
  }
}
```

---

### 12. Get Funding Rate

获取指定永续合约交易对的当前资金费率。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/funding-rate?exchangeId=binance&symbol=BTC/USDT" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | Yes | Trading pair (e.g., `BTC/USDT`) |

**Response:**
```json
{
  "success": true,
  "data": {
    "symbol": "BTC/USDT",
    "fundingRate": 0.0001,
    "timestamp": 1679400000000,
    "datetime": "2026-03-21T10:30:00Z",
    "markPrice": 67890.50,
    "indexPrice": 67885.00,
    "nextFundingTimestamp": 1679428800000
  }
}
```

---

### 13. Get Funding Rates

获取指定交易所多个永续合约交易对的资金费率。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/funding-rates?exchangeId=binance&symbols=BTC/USDT,ETH/USDT" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbols` | String (query) | No | Comma-separated symbols. Omit for all symbols. |

**Response:**
```json
{
  "success": true,
  "data": {
    "BTC/USDT": {
      "symbol": "BTC/USDT",
      "fundingRate": 0.0001,
      "timestamp": 1679400000000,
      "datetime": "2026-03-21T10:30:00Z",
      "markPrice": 67890.50,
      "indexPrice": 67885.00,
      "nextFundingTimestamp": 1679428800000
    }
  }
}
```

---

### 14. Get Funding Rate History

获取指定永续合约交易对的历史资金费率。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/funding-rate/history?exchangeId=binance&symbol=BTC/USDT&limit=20" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | No | Trading pair (e.g., `BTC/USDT`) |
| `since` | Integer (query) | No | Timestamp in milliseconds to fetch data from |
| `limit` | Integer (query) | No | Number of records (default: 20) |

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "symbol": "BTC/USDT",
      "fundingRate": 0.0001,
      "timestamp": 1679400000000,
      "datetime": "2026-03-21T10:30:00Z"
    }
  ]
}
```

---

### 15. Get Funding Rate Across Exchanges

获取指定交易对在多个交易所的资金费率对比。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/funding-rate/exchanges?exchangeIds=binance,bybit,okx&symbol=BTC/USDT" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeIds` | String (query) | Yes | Comma-separated exchange IDs (e.g., `binance,bybit,okx`) |
| `symbol` | String (query) | Yes | Trading pair (e.g., `BTC/USDT`) |

**Response:**
```json
{
  "success": true,
  "data": {
    "binance": {
      "symbol": "BTC/USDT",
      "fundingRate": 0.0001,
      "timestamp": 1679400000000,
      "datetime": "2026-03-21T10:30:00Z",
      "markPrice": 67890.50,
      "indexPrice": 67885.00,
      "nextFundingTimestamp": 1679428800000
    },
    "bybit": {
      "symbol": "BTC/USDT",
      "fundingRate": 0.00012,
      "timestamp": 1679400000000,
      "datetime": "2026-03-21T10:30:00Z",
      "markPrice": 67891.00,
      "indexPrice": 67886.00,
      "nextFundingTimestamp": 1679428800000
    }
  }
}
```

---

### 16. Get Funding Interval

获取指定永续合约交易对的资金费率结算间隔。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/funding-interval?exchangeId=binance&symbol=BTC/USDT" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | Yes | Trading pair (e.g., `BTC/USDT`) |

**Response:**
```json
{
  "success": true,
  "data": {
    "symbol": "BTC/USDT",
    "interval": "8h"
  }
}
```

---

### 17. Get Current Open Interest

获取指定永续合约交易对的当前持仓量。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/open-interest?exchangeId=binance&symbol=BTC/USDT" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | Yes | Trading pair (e.g., `BTC/USDT`) |

**Response:**
```json
{
  "success": true,
  "data": {
    "symbol": "BTC/USDT",
    "openInterestAmount": 12345.67,
    "openInterestValue": 838500000.00,
    "timestamp": 1679400000000,
    "datetime": "2026-03-21T10:30:00Z"
  }
}
```

---

### 18. Get Open Interest History

获取指定永续合约交易对的历史持仓量数据。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/open-interest/history?exchangeId=binance&symbol=BTC/USDT&timeframe=1h&limit=50" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | Yes | Trading pair (e.g., `BTC/USDT`) |
| `timeframe` | String (query) | No | Timeframe (default: `1h`): `5m`, `15m`, `1h`, `4h` |
| `since` | Integer (query) | No | Timestamp in milliseconds to fetch data from |
| `limit` | Integer (query) | No | Number of records |

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "symbol": "BTC/USDT",
      "openInterestAmount": 12345.67,
      "openInterestValue": 838500000.00,
      "timestamp": 1679400000000,
      "datetime": "2026-03-21T10:30:00Z"
    }
  ]
}
```

---

### 19. Get Gamma Exposure

获取美股标的的期权 Gamma Exposure（GEX）数据。该接口使用股票 ticker，例如 `SNDK`、`AAPL`、`TSLA`，不需要 `exchangeId`。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/metadata/gamma?symbol=SNDK&cache_ttl_seconds=300" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `symbol` | String (query) | Yes | US equity ticker, e.g. `SNDK`, `AAPL`, `TSLA` |
| `date` | String (query) | No | Market date in `YYYY-MM-DD`; when omitted, provider returns the latest available market date |
| `expiry` | String (query) | No | Option expiry date in `YYYY-MM-DD`; when provided, returns strike exposure for that expiry |
| `cache_ttl_seconds` | Integer (query) | No | Override backend cache TTL; `0` forces refresh, max `86400` |
| `include_expiry_breakdown` | Boolean (query) | No | When `true`, include exposure grouped by expiry |

**Response:**
```json
{
  "success": true,
  "data": {
    "symbol": "SNDK",
    "provider_date": "2026-08-14",
    "requested_date": null,
    "requested_expiry": null,
    "row_count": 558,
    "total_call_gex": 24677.8465,
    "total_put_gex": -13936.3542,
    "total_net_gex": 10741.4923,
    "max_abs_net_gex": 1683.3503,
    "rows": [
      {
        "strike": 3000,
        "date": "2026-08-14",
        "call_gex": 77.886,
        "put_gex": -11.8434,
        "net_gex": 66.0426,
        "normalized_gex": 0.0392328323,
        "normalized_gex_percent": 3.9232832287
      }
    ]
  },
  "usage": {"cost": "1"}
}
```

**Display to user:**
- Summarize `total_net_gex`, `total_call_gex`, `total_put_gex`, and `provider_date`
- Highlight strikes with the largest absolute `net_gex`
- If `include_expiry_breakdown=true`, summarize the largest expiries by net gamma exposure

---

### 20. Get Index Constituents

获取永续合约指数价格的成分币种及其权重。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/market/index-constituents?symbol=BTCUSDT" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `symbol` | String (query) | Yes | Perpetual symbol in raw format (e.g., `BTCUSDT`, `ETHUSDT`). Case-insensitive, will be uppercased. |

**Response:**
```json
{
  "success": true,
  "data": {
    "symbol": "BTCUSDT",
    "time": 1697007049254,
    "constituents": [
      {"exchange": "binance", "symbol": "BTCUSDT", "weight": "0.3333"},
      {"exchange": "okx",     "symbol": "BTC-USDT", "weight": "0.3333"},
      {"exchange": "coinbase","symbol": "BTC-USD",  "weight": "0.3334"}
    ]
  },
  "usage": {"cost": 1, "quota": 99}
}
```

**Display to user:**
- List the exchanges contributing to the index and their relative weights
- Useful for understanding where the mark/index price is derived from

---

### 21. Get Smart Money Signal

获取永续合约的"聪明钱"信号概览。聪明钱信号反映大资金账户在该合约上的多空倾向与持仓变化。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/public/market/smart-money?symbol=BTCUSDT" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `symbol` | String (query) | Yes | Perpetual symbol in raw format (e.g., `BTCUSDT`). Case-insensitive, will be uppercased. |

**Response:** Upstream JSON structure is returned as-is. Typical fields include the symbol, long/short ratios of top traders, position deltas, and signal timestamp. Structure may evolve with upstream changes — read the raw response before building downstream logic.

```json
{
  "success": true,
  "data": {
    "code": "000000",
    "message": null,
    "data": { "symbol": "BTCUSDT", "...": "upstream fields" },
    "success": true
  },
  "usage": {"cost": 1, "quota": 99}
}
```

**Display to user:**
- Summarize the directional bias (long-heavy vs short-heavy) and any notable shifts
- Pair with `GET /public/metadata/funding-rate` and `GET /public/metadata/open-interest` for a fuller picture

---

### 22. Get Account Summary

获取指定交易所的账户余额摘要信息，包括总余额、可用余额、杠杆分析等。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/account/summary?exchangeId=binance&symbol=BTC/USDT:USDT&accountType=swap" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | No | Trading pair, for determining quote currency |
| `accountType` | String (query) | No | Account type (default: `spot`): `spot`, `swap`, `future`, `margin` |

**Response:**
```json
{
  "success": true,
  "data": {
    "exchangeId": "binance",
    "accountType": "swap",
    "balance": 10000.00,
    "available": 8500.00,
    "currency": "USDT",
    "leverage": 10,
    "maxPosition": 85000.00,
    "totals": {
      "USDT": 10000.00,
      "BTC": 0.05
    },
    "frees": {
      "USDT": 8500.00,
      "BTC": 0.05
    },
    "leverageAnalysis": {
      "symbol": "BTC/USDT:USDT",
      "exchangeId": "binance",
      "availableBalance": 8500.00,
      "balanceCurrency": "USDT",
      "leverageInfo": {
        "exchangeId": "binance",
        "symbol": "BTC/USDT:USDT",
        "tiers": [],
        "supportsDynamicLeverage": true,
        "baseCurrency": "BTC",
        "quoteCurrency": "USDT",
        "settleCurrency": "USDT",
        "generatedAt": 1679400000000
      },
      "marketPrice": 67890.50
    }
  },
  "usage": {"cost": 1, "quota": 99}
}
```

**Display to user:**
- "Total Balance: $10,000.00 USDT"
- "Available: $8,500.00 | Leverage: 10x"
- "Max Position: $85,000.00"

---

### 23. Get Spot Asset

查询指定交易所和交易对的现货资产持有信息。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/account/spot?exchangeId=binance&symbol=BTC/USDT" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | Yes | Trading pair (e.g., `BTC/USDT`) |

**Response:**
```json
{
  "success": true,
  "data": {
    "exchangeId": "binance",
    "symbol": "BTC/USDT",
    "baseAsset": "BTC",
    "quantity": 0.5,
    "free": 0.45,
    "locked": 0.05,
    "costPrice": 65000.00,
    "totalCost": 32500.00
  },
  "usage": {"cost": 1, "quota": 99}
}
```

**Display to user:**
- "BTC: 0.5 (Free: 0.45, Locked: 0.05)"
- "Avg Cost: $65,000 | Total Cost: $32,500"

---

### 24. Get All Spot Assets

获取指定交易所的所有现货资产列表。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/account/spots?exchangeId=binance" \
  -H "$AUTH_HEADER"
```

**Parameters:**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String (query) | Yes | Exchange ID |
| `symbol` | String (query) | No | Filter by trading pair |

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "exchangeId": "binance",
      "symbol": null,
      "baseAsset": "BTC",
      "quantity": 0.5,
      "free": 0.45,
      "locked": 0.05,
      "costPrice": 65000.00,
      "totalCost": 32500.00
    },
    {
      "exchangeId": "binance",
      "symbol": null,
      "baseAsset": "USDT",
      "quantity": 10000.00,
      "free": 8500.00,
      "locked": 1500.00,
      "costPrice": 1.00,
      "totalCost": 10000.00
    }
  ],
  "usage": {"cost": 1, "quota": 99}
}
```

**Display to user:**
- List all assets with non-zero balances, showing free/locked split and cost basis

---

### 25. Get Trading Config

获取用户的交易配置摘要（不包含密钥敏感信息）。

```bash
curl -s "$BASE_URL/open/trader/newsliquid/v1/config" \
  -H "$AUTH_HEADER"
```

**Parameters:** None

**Response:**
```json
{
  "success": true,
  "data": {
    "defaultExchange": "binance",
    "defaultLeverage": 10,
    "defaultPosition": 100.0,
    "general": {},
    "binanceConfigured": true,
    "bybitConfigured": false,
    "okxConfigured": true,
    "hyperliquidConfigured": false,
    "asterConfigured": false
  },
  "usage": {"cost": 1, "quota": 99}
}
```

**Display to user:**
- "Default Exchange: binance | Leverage: 10x | Position: $100"
- List which exchanges are configured

---

### 26. Update Trading Config

更新用户的交易配置，包括默认交易所、杠杆和交易所凭证。

> **IMPORTANT**: Exchange API credentials (`apiKey`, `secret`, `password`) are sensitive. Never log or display them.

```bash
curl -s -X PUT "$BASE_URL/open/trader/newsliquid/v1/config" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "defaultExchange": "binance",
    "defaultLeverage": 10,
    "defaultPosition": 100.0,
    "binance": {
      "apiKey": "your-api-key",
      "secret": "your-api-secret",
      "password": ""
    }
  }'
```

**Parameters (body):**

| Field | Type | Required | Description |
|---|---|---|---|
| `defaultExchange` | String | No | Default exchange: `binance`, `bybit`, `okx`, `hyperliquid` |
| `defaultLeverage` | Integer | No | Default leverage (1-125) |
| `defaultPosition` | Float | No | Default position size |
| `general` | Object | No | General config |
| `binance` / `bybit` / `okx` / `hyperliquid` / `aster` | Object | No | Exchange credentials: `apiKey` (required), `secret` (required), `password` (optional, OKX requires) |

**Response:**
```json
{
  "success": true,
  "data": {
    "updated": true
  },
  "usage": {"cost": 1, "quota": 99}
}
```

---

### 27. Place Order (Risk Controlled)

在指定交易所下单。支持多种订单类型。

**This endpoint is protected by the risk engine** — orders that deviate too far from market price, exceed position limits, hit rate limits, or lack sufficient balance will be rejected.

> **CRITICAL — Required Parameters**:
> - **`type`** (REQUIRED): Order type must be explicitly specified. Choose from: `market`, `limit`, `stop_market`, `take_profit_market`. Each type has different parameter requirements (see Order Types section below).
> - **`hedged`** (REQUIRED): Hedge mode flag. If the value is unknown, call `GET /position/mode` first to obtain `data.hedged`. Once obtained, it can be reused for subsequent orders on the same symbol/exchange.

```bash
# Step 1: Get position mode to obtain the hedged parameter (if unknown)
curl -s "$BASE_URL/open/trader/newsliquid/v1/position/mode?symbol=BTC/USDT:USDT&exchangeId=binance" \
  -H "$AUTH_HEADER"
# → Returns {"data": {"hedged": false, "info": {"dualSidePosition": false}}, "success": true}
# Extract data.hedged value to use in the order request

# Step 2: Limit order - buy 0.01 BTC at $65,000 with TP/SL (use hedged from step 1)
curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/orders" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "exchangeId": "binance",
    "symbol": "BTC/USDT:USDT",
    "side": "buy",
    "type": "limit",
    "quantity": 0.01,
    "price": 65000.00,
    "hedged": false,
    "stopLossPrice": 64000.00,
    "takeProfitPrice": 70000.00
  }'

# Market order: sell 0.5 ETH (get hedged first)
curl -s "$BASE_URL/open/trader/newsliquid/v1/position/mode?symbol=ETH/USDT:USDT&exchangeId=binance" -H "$AUTH_HEADER"
curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/orders" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "exchangeId": "binance",
    "symbol": "ETH/USDT:USDT",
    "side": "sell",
    "type": "market",
    "quantity": 0.5,
    "hedged": false
  }'

# Stop-loss market order (get hedged first)
curl -s "$BASE_URL/open/trader/newsliquid/v1/position/mode?symbol=BTC/USDT:USDT&exchangeId=binance" -H "$AUTH_HEADER"
curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/orders" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "exchangeId": "binance",
    "symbol": "BTC/USDT:USDT",
    "side": "sell",
    "type": "stop_market",
    "quantity": 0.01,
    "triggerPrice": 58000.00,
    "hedged": false
  }'
```

**Parameters (body):**

| Field | Type | Required | Description |
|---|---|---|---|
| `exchangeId` | String | No | Exchange ID (default: `binance`) |
| `symbol` | String | Yes | Trading pair in CCXT format (e.g., `BTC/USDT:USDT`) |
| `side` | String | Yes | `buy` or `sell` |
| `type` | String | **Yes** | **Order type (REQUIRED) - determines execution behavior and which other parameters are needed. See Order Types below.** |
| `quantity` | Float | Conditional | Base currency quantity |
| `quoteAmount` | Float | Conditional | Quote currency amount (e.g., USDT) |
| `price` | Float | Conditional | Limit price, required for `limit`, `stop_limit`, `take_profit_limit` |
| `triggerPrice` | Float | Conditional | Trigger price, required for `stop_market`, `stop_limit`, `take_profit_market`, `take_profit_limit` |
| `hedged` | Boolean | **Yes** | **Hedge mode (REQUIRED) - MUST be obtained from `GET /position/mode` if unknown. Using incorrect value may cause order rejection.** |
| `stopLossPrice` | Float | No | Attached stop-loss trigger price |
| `takeProfitPrice` | Float | No | Attached take-profit trigger price |

**Order types:**
- `market` — Market order (executes immediately at current market price, no `price` needed)
- `limit` — Limit order (executes at specified `price` or better, `price` required)
- `stop_market` — Stop-loss market order (triggers at `triggerPrice`, executes at market, `triggerPrice` required)
- `take_profit_market` — Take-profit market order (triggers at `triggerPrice`, executes at market, `triggerPrice` required)

**Important**: Always specify `type` explicitly. Different order types require different parameters:
- `market`: requires `quantity` or `quoteAmount`
- `limit`: requires `quantity` or `quoteAmount` + `price`
- `stop_market` / `take_profit_market`: requires `quantity` + `triggerPrice`

**Response:**
```json
{
  "success": true,
  "data": {
    "exchange": 

…(truncated)