opentrade-cex

What this skill does

# OpenTrade CEX Trading

39 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
  OPEN_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 $OPEN_TOKEN"
  ```

## Skill Routing

- 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/market/index-constituents` | GET | Get contract index price constituents |
| 20 | `/open/trader/newsliquid/v1/public/market/smart-money` | GET | Get smart money signal overview |

### Account (no risk control)

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

### Config (no risk control)

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