Futures Trading API

Programmatic access to futures market data and trading. Use API Keys for server-to-server trading and JWT for user-facing apps.

Base URL

https://api.levret.io/api/v1

Swagger UI: https://api.levret.io/api/docs

Rate Limits

• 1200 requests per minute per API key
• Order placement bursts should be backoff-aware

Authentication

For trading and private endpoints use API Keys. Some account/position routes currently require JWT.

API Key Headers

X-API-KEY-ID: YOUR_KEY_ID
X-API-KEY-SECRET: YOUR_KEY_SECRET
X-API-KEY-TS: 1736700000000
X-API-KEY-EXP: 60000
X-API-KEY-SIGN: <HMAC_SHA256(secret, method + pathWithQuery + ts + bodyJson)>
Content-Type: application/json

Signature payload: METHOD + PATH_WITH_QUERY + TS + BODY_JSON

Scopes

• read - Read-only
• trade - Place/cancel orders
• withdraw - Withdraw funds

Market Data (Public)

GET/market/supported-symbols

List supported futures symbols

GET/market/market-stats?symbol=BTC_USDT

Last price, 24h stats, funding

GET/market/orderbook?symbol=BTC_USDT&depth=50

Aggregated order book snapshot

GET/market/candles?symbol=BTC_USDT&interval=1m&limit=500

Historical candles

Rate Limits & Errors

Endpoints enforce per-key limits. Order routes include standard headers:

X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Error schema

{
  "success": false,
  "error": { "code": "RATE_LIMITED", "message": "Too many requests" },
  "path": "/order",
  "timestamp": "2025-01-01T00:00:00.000Z"
}

Orders (Private, API Key)

POST/order

Create market/limit order. Returns rate-limit headers.

{
  "userId": "USER_ID",
  "symbol": "BTC_USDT",
  "side": "buy",
  "orderType": "limit",
  "size": 0.01,
  "price": 45000,
  "leverage": 10,
  "reduce_only": false,
  "takeProfit": 47000,
  "stopLoss": 44000
}

GET/order/open?userId=USER_ID&symbol=BTC_USDT&page=1&pageSize=50&startTime=1736700000000&endTime=1736790000000

List open orders with pagination/time filters

GET/order/:id

Get order by id

POST/order/cancel

Cancel order. Rate-limited.

{ "orderId": "123456" }

POST/order/cancelAll

Cancel all pending orders. Rate-limited.

{ "userId": "USER_ID", "symbol": "BTC_USDT" }

Positions (Private)

API Key is now accepted in addition to JWT (headers: X-API-KEY-ID, X-API-KEY-SECRET).

GET/positions

List user positions

POST/positions/:id/leverage

Update position leverage (1-125)

{ "leverage": 20 }

POST/positions/:id/margin

Add or reduce isolated margin

{ "mode": "add", "amount": 50 }

POST/positions/:id/tpsl

Set/Update TP and SL prices

{ "takeProfitPrice": 47000, "stopLossPrice": 44000 }

POST/positions/:id/close

Close position

Account & Wallet (Private)

API Key is now accepted in addition to JWT (headers: X-API-KEY-ID, X-API-KEY-SECRET).

GET/wallet/account-overview

Account balances and summary

GET/wallet/balance-history?days=7

Balance history

Fills/Trades (Private)

GET/trade/user/:userId?symbol=BTC_USDT&page=1&pageSize=50&startTime=...&endTime=...

Get user trade history (fills) with pagination and time filters

GET/trade/order/:orderId

Get trades for a specific order

WebSocket API

Real-time data streaming for account updates, order status, and market data.

Connection

import { io } from 'socket.io-client'
const socket = io('https://api.levret.io/api/v1/trading', {
  auth: { apiKeyId: 'YOUR_KEY_ID', apiKeySecret: 'YOUR_KEY_SECRET' }
})
socket.on('orderUpdate', console.log)
socket.on('positionUpdate', console.log)

Events

• accountData - Account balance updates
• orderUpdate - Order status changes
• positionUpdate - Position changes
• marketData - Real-time price updates

Examples

curl

curl -X POST "https://api.levret.io/api/v1/order" -H "Content-Type: application/json" -H "X-API-KEY-ID: YOUR_KEY_ID" -H "X-API-KEY-SECRET: YOUR_KEY_SECRET" -d '{
  "userId": "USER_ID",
  "symbol": "BTC_USDT",
  "side": "buy",
  "orderType": "limit",
  "size": 0.01,
  "price": 45000
}'

Include signing headers: X-API-KEY-TS, X-API-KEY-EXP, X-API-KEY-SIGN as described above.

curl (Positions)

# Update leverage
curl -X POST "https://api.levret.io/api/v1/positions/123/leverage" -H "Content-Type: application/json" -H "X-API-KEY-ID: YOUR_KEY_ID" -H "X-API-KEY-SECRET: YOUR_KEY_SECRET" -d '{ "leverage": 20 }'

# Adjust margin
curl -X POST "https://api.levret.io/api/v1/positions/123/margin" -H "Content-Type: application/json" -H "X-API-KEY-ID: YOUR_KEY_ID" -H "X-API-KEY-SECRET: YOUR_KEY_SECRET" -d '{ "mode": "add", "amount": 50 }'

# Set TP/SL
curl -X POST "https://api.levret.io/api/v1/positions/123/tpsl" -H "Content-Type: application/json" -H "X-API-KEY-ID: YOUR_KEY_ID" -H "X-API-KEY-SECRET: YOUR_KEY_SECRET" -d '{ "takeProfitPrice": 47000, "stopLossPrice": 44000 }'

Node.js (axios)

import axios from 'axios'
const api = axios.create({ baseURL: 'https://api.levret.io/api/v1' })
const res = await api.post('/order', {
  userId: 'USER_ID', symbol: 'BTC_USDT', side: 'buy', orderType: 'market', size: 0.01
}, { headers: { 'X-API-KEY-ID': 'YOUR_KEY_ID', 'X-API-KEY-SECRET': 'YOUR_KEY_SECRET' } })
console.log(res.data)

SDKs

// Node (REST)
import { TradingRESTClient } from '@/sdks/node'
const client = new TradingRESTClient('https://api.levret.io/api/v1', 'KEY', 'SECRET')
const order = await client.createOrder({ userId: 'USER', symbol: 'BTC_USDT', side: 'buy', orderType: 'limit', size: 0.01, price: 45000 })

// Positions
await client.updateLeverage('123', 20)
await client.adjustMargin('123', 'add', 50)
await client.updateTpSl('123', 47000, 44000)

// Python (REST)
from sdks.python.levret_rest import TradingRESTClient
cli = TradingRESTClient('https://api.levret.io/api/v1', 'KEY', 'SECRET')
orders = cli.get_open_orders('USER')
cli.update_leverage('123', 20)
cli.adjust_margin('123', 'add', 50)
cli.update_tpsl('123', 47000, 44000)

Python (requests)

import requests
headers={'X-API-KEY-ID':'YOUR_KEY_ID','X-API-KEY-SECRET':'YOUR_KEY_SECRET'}
r=requests.post('https://api.levret.io/api/v1/order', json={'userId':'USER_ID','symbol':'BTC_USDT','side':'buy','orderType':'limit','size':0.01,'price':45000}, headers=headers)
print(r.json())