Trading API Documentation

The REST API enables programmatic trading: placing orders (limit / market, open / close), cancelling orders, and querying positions / orders / wallet / symbols / tickers. All endpoints return JSON; timestamps are Unix seconds or milliseconds (noted per field). API orders share the same matching and risk engine as web orders.

Authentication

Generate an API key under User Menu > API Management (one key per account; the key is shown only once, store it securely). Every request must include the header:

X-API-KEY: tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Failed authentication returns 401 API_KEY_MISSING / API_KEY_INVALID; a disabled account returns 403 ACCOUNT_DISABLED. Never hardcode your key in browser-side code.

Rate Limits & Security

• More than 20 authentication failures (missing / invalid key) per minute from one IP returns 429 RATE_LIMITED and temporarily blocks the IP.
• Order rate limits are shared with the web client; exceeding them returns 422 ORDER_RATE_LIMIT.
• All calls are written to the API log; view your call history under User Menu > API Management.
• For high-frequency market data polling, use the Market Data Cluster endpoints below (no key, no rate limit); use /api/v1 for trading operations.

After entering your API key, use the Try this endpoint panel under each endpoint to fire real requests (real orders will really execute — use with care). The key is stored in page memory only, cleared on refresh, and never written to browser storage.

Open (buy) or close (sell) a position with limit / market orders. API orders share all risk controls with web orders (order rate limits, price deviation, margin checks, etc.) and are flagged with an API source in the order history.

{ "ok": true }
// Business validation failure (HTTP 422):
{ "ok": false, "error": "MARGIN_INSUFFICIENT" }

Cancel a pending order in your own account. Calling this on filled / cancelled orders has no effect.

{ "ok": true }

Returns all current positions with the latest price, average cost, unrealized PnL, leveraged borrowing and estimated liquidation price.

{
  "ok": true,
  "positions": [
    {
      "symbolId": "btc",
      "position": 100,        // total position
      "available": 80,        // closable quantity (not locked by open orders)
      "avgCost": 64500.5,
      "lastPrice": 65100.2,
      "marketValue": 6510020,
      "unrealizedPnl": 59970,
      "leverage": 10,
      "borrowed": 580504.5,
      "margin": 64500.5,
      "liqPrice": 61234.5
    }
  ],
  "serverTime": 1751600000
}

Query open and historical orders. The source field identifies the origin (web / api).

{
  "ok": true,
  "open": [
    {
      "id": "o_xxxxxxxx",
      "symbolId": "btc",
      "side": "buy",
      "type": "limit",
      "price": 65000,
      "qty": 100,
      "filled": 0,
      "avgFillPrice": null,
      "status": "pending",
      "leverage": 10,
      "fee": 0,
      "source": "api",
      "ts": 1751600000000
    }
  ],
  "history": [],
  "serverTime": 1751600000
}

Returns available cash, cumulative traded volume and account level.

{
  "ok": true,
  "cash": 100000.0,
  "tradedVolume": 2500000.0,
  "level": 3,
  "serverTime": 1751600000
}

Returns all currently tradable pairs with precision and fee rules. Call this first to obtain valid symbolId values before placing orders.

{
  "ok": true,
  "symbols": [
    {
      "symbolId": "btc",
      "symbol": "BTC/USD",
      "base": "BTC",
      "quote": "USD",
      "name": "Bitcoin",
      "pricePrecision": 2,
      "qtyPrecision": 3,
      "openFeePct": 0.1,
      "closeFeePct": 0.1,
      "custom": false
    }
  ],
  "serverTime": 1751600000
}

Returns the latest price, 24h high/low and volume for all tradable symbols, plus order precision / quantity limits. For high-frequency polling, prefer the market data cluster endpoints below.

{
  "ok": true,
  "tickers": [
    {
      "symbolId": "btc",
      "base": "BTC",
      "quote": "USD",
      "lastPrice": 65100.2,
      "high": 65900,
      "low": 64100,
      "volume": 1234567,
      "pricePrecision": 2,
      "qtyPrecision": 3,
      "minQty": 10,
      "maxQty": 10000
    }
  ],
  "serverTime": 1751600000
}

Market Data Cluster Public API (recommended for high frequency)

No API key required, no rate limit, and both primary and backup nodes are available. The symbol parameter accepts formats such as TEST, TEST/USD, TESTUSD and test/usd.

GET  {md-server}/api/md/symbols                      Listed symbols
GET  {md-server}/api/md/ticker?symbol=TEST           24h summary (last price / change / volume)
GET  {md-server}/api/md/depth?symbol=TEST&limit=20   Full order book depth (bids/asks)
GET  {md-server}/api/md/trades?symbol=TEST&limit=50  Latest trades
GET  {md-server}/api/md/kline?symbol=TEST&step=60&limit=500
     Candlesticks (Binance-style arrays, step in seconds: 60/300/900/3600/14400/86400)

# Example response /api/md/ticker
{ "ok": true, "symbol": "TEST", "last": 50.92, "open24h": 49.4,
  "high24h": 50.92, "low24h": 49.44, "volume24h": 4000,
  "changePct": 3.08, "time": 1751600000000 }

Contact the administrator for the market data server address. All cluster nodes serve consistent data; if one node fails, switch to another. Data refreshes every second.

Error Codes

Code Examples

curl

# Market buy
curl -X POST https://api.alveroxa.com/api/v1/order \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: tk_live_your_key" \
  -d '{"symbolId":"btc","side":"buy","type":"market","qty":100}'

# Get positions
curl https://api.alveroxa.com/api/v1/positions -H "X-API-KEY: tk_live_your_key"

Python (requests)

import requests

BASE = "https://api.alveroxa.com"
HEADERS = {"X-API-KEY": "tk_live_your_key"}

# Limit buy
r = requests.post(f"{BASE}/api/v1/order", headers=HEADERS, json={
    "symbolId": "btc", "side": "buy", "type": "limit",
    "price": 65000, "qty": 100, "leverage": 1,
})
print(r.status_code, r.json())

# Get open orders
print(requests.get(f"{BASE}/api/v1/orders?status=open", headers=HEADERS).json())

Node.js (fetch)

const BASE = "https://api.alveroxa.com";
const HEADERS = { "X-API-KEY": "tk_live_your_key", "Content-Type": "application/json" };

// Cancel order
const res = await fetch(BASE + "/api/v1/order/cancel", {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ orderId: "o_xxxxxxxx" }),
});
console.log(await res.json());