API Documentation

Build trading bots, integrate market data, and manage your account programmatically. TradeGrail provides a REST API and WebSocket feeds for real-time data.

Base URL: https://api.tradegrail.com
WebSocket: wss://api.tradegrail.com/ws/
All requests use HTTPS. HTTP requests are rejected.

Quick Start

Step 1
Create Account
Register at tradegrail.com and verify your email address.
Step 2
Generate API Keys
Go to Dashboard → API Keys and create a new key pair.
Step 3
Make Your First Call
Use the API key and secret in request headers to authenticate.
Example: Fetch market ticker
# Public endpoint - no authentication required
curl https://api.tradegrail.com/api/markets/tickers
Example: Get your balances (authenticated)
curl https://api.tradegrail.com/api/wallets/balances \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_secret_key"
Example: Place a limit order
curl -X POST https://api.tradegrail.com/api/order \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pair": "BTC-USDT",
    "side": "buy",
    "order_type": "limit",
    "amount": 0.001,
    "price": 45000.0
  }'

Authentication

TradeGrail supports two authentication methods. API keys are recommended for programmatic access. Public endpoints (market data) do not require authentication.

API Keys (Recommended)

Include your API key and secret in the request headers: 

X-API-Key: your_api_key
X-API-Secret: your_api_secret
Security: Never share your API secret. It is shown only once during creation. If compromised, revoke the key immediately in your Dashboard.

API Key Permissions

PermissionDescription
read:allRead balances, orders, trades, history
write:ordersPlace and cancel orders
write:withdrawalsCreate withdrawal requests

Rate Limits

Rate limits protect the platform and ensure fair usage. Limits vary by endpoint category. When a limit is exceeded, the API returns HTTP 429.

CategoryLimitPerEndpoints
Market Data 500 req/s IP Tickers, orderbook, public trades, candles
Read-Only 600 req/min User Balances, user orders, user trades, history
Trading 300 req/min User Place order, cancel order, API key management
Withdrawals 5 req/min User Withdraw, change password
Login 5 req/min IP Login, register, password reset
Rate limit response headers
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 60
Retry-After: 45
Tip: When you receive a 429 response, check the Retry-After header for the number of seconds to wait before retrying.

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with details.

StatusMeaning
200Success
201Created (new resource)
400Bad Request - invalid parameters
401Unauthorized - missing or invalid authentication
403Forbidden - insufficient permissions
429Too Many Requests - rate limit exceeded
500Internal Server Error
Error response format
{
  "error": "Insufficient balance",
  "details": "The requested amount exceeds your available balance."
}

Market Data

Public endpoints for market data. No authentication required.

GET /api/markets/tickers 24h ticker stats for all pairs PUBLIC ▼

Returns 24-hour rolling window statistics for all trading pairs.

Response
[
  {
    "symbol": "BTC-USDT",
    "last_price": 45000.0,
    "open_price": 44000.0,
    "high_24h": 46000.0,
    "low_24h": 43000.0,
    "volume_24h": 100.5,
    "quote_volume_24h": 4500000.0,
    "price_change_percent": 2.27,
    "best_bid": 44999.0,
    "best_ask": 45001.0,
    "num_trades_24h": 250
  }
]
GET /api/markets/ticker/{symbol} Ticker for specific pair PUBLIC ▼

Returns 24h ticker data for a specific trading pair.

Path Parameters
NameTypeRequiredDescription
symbolstringYesTrading pair, e.g. BTC-USDT
GET /api/book/{pair} Order book PUBLIC ▼

Returns current order book with bids and asks, sorted by best price.

Path Parameters
NameTypeRequiredDescription
pairstringYesTrading pair, e.g. BTC-USDT
Response
{
  "bids": [
    { "price": 44999.0, "amount": 1.5 }
  ],
  "asks": [
    { "price": 45001.0, "amount": 2.0 }
  ]
}
GET /api/trades Recent trades PUBLIC ▼

Returns recent trades for a given pair.

Query Parameters
NameTypeRequiredDescription
pairstringOptionalFilter by pair, e.g. BTC-USDT
limitintegerOptionalNumber of trades (default: 100, max: 1000)
Response
[
  {
    "id": "uuid",
    "pair": "BTC-USDT",
    "price": 45000.0,
    "amount": 0.5,
    "side": "buy",
    "timestamp": 1707000000000
  }
]
GET /api/candles/{pair} OHLCV candle data PUBLIC ▼

Returns OHLCV (Open-High-Low-Close-Volume) candle data for charts.

Path Parameters
NameTypeRequiredDescription
pairstringYesTrading pair, e.g. BTC-USDT
Query Parameters
NameTypeRequiredDescription
intervalstringOptional1m, 5m, 15m, 30m, 1h, 4h, 1d (default: 15m)
limitintegerOptionalNumber of candles (default: 100, max: 1500)
Response
[
  {
    "pair": "BTC-USDT",
    "interval": "15m",
    "timestamp": 1707000000000,
    "open": 45000.0,
    "high": 45500.0,
    "low": 44500.0,
    "close": 45200.0,
    "volume": 50.5,
    "trades": 125
  }
]
GET /api/fees/stats Exchange fee statistics PUBLIC ▼

Returns aggregated fee statistics for the exchange.

Response
[
  {
    "currency": "USDT",
    "total_fees_collected": 1500.50,
    "maker_fees": 500.25,
    "taker_fees": 1000.25
  }
]

Trading

Endpoints for placing, cancelling, and querying orders. All trading endpoints require authentication.

POST /api/order Place new order AUTH ▼

Place a new limit or market order. Balance is locked immediately upon placement.

Request Body
FieldTypeRequiredDescription
pairstringYesBTC-USDT or WART-USDT
sidestringYesbuy or sell
order_typestringYeslimit or market
amountdecimalYesOrder quantity in base currency
pricedecimalLimit onlyPrice per unit (required for limit orders)
Response
{
  "success": true,
  "message": "Order placed and matched successfully",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "pair": "BTC-USDT",
  "side": "buy",
  "price": 45000.0,
  "amount": 0.5
}
Minimum order values: BTC-USDT: 5 USDT | WART-USDT: 1 USDT
DELETE /api/order/{pair}/{order_id} Cancel order AUTH ▼

Cancel an active or partially filled order. Remaining locked balance is returned.

Path Parameters
NameTypeRequiredDescription
pairstringYesTrading pair, e.g. BTC-USDT
order_iduuidYesOrder UUID
Response
{
  "success": true,
  "message": "Order cancelled and funds unlocked"
}
GET /api/user-orders Active orders AUTH ▼

Returns all active and partially filled orders for the authenticated user.

Response
[
  {
    "id": "uuid",
    "pair": "BTC-USDT",
    "order_type": "limit",
    "side": "buy",
    "price": 45000.0,
    "amount": 0.5,
    "remaining": 0.2,
    "status": "partial",
    "created_at": 1707000000000
  }
]
GET /api/order-history Order history AUTH ▼

Returns filled and cancelled orders. Last 100 orders.

Response
[
  {
    "id": "uuid",
    "pair": "BTC-USDT",
    "side": "buy",
    "price": 45000.0,
    "amount": 0.5,
    "remaining": 0.0,
    "status": "filled",
    "created_at": 1707000000000
  }
]
GET /api/user-trades User trade history AUTH ▼

Returns executed trades with fee details for the authenticated user.

Response
[
  {
    "id": "uuid",
    "pair": "BTC-USDT",
    "side": "buy",
    "price": 45000.0,
    "amount": 0.5,
    "fee_amount": 22.50,
    "fee_currency": "USDT",
    "fee_type": "taker",
    "timestamp": 1707000000000
  }
]

Wallet

Endpoints for managing balances, deposit addresses, and withdrawals.

GET /api/wallets/balances All balances AUTH ▼

Returns balances for all currencies including available, locked, and network details.

Response
[
  {
    "currency": "USDT",
    "available": 1000.50,
    "locked": 50.00,
    "total": 1050.50,
    "withdrawal_fee": 7.0,
    "min_withdrawal": 10.0
  }
]
GET /api/wallets/deposit-address/{currency} Get deposit address AUTH ▼

Get or generate a deposit address for the specified currency.

Path Parameters
NameTypeRequiredDescription
currencystringYesUSDT, BTC, or WART
Response
{
  "currency": "USDT",
  "address": "TAddr123...",
  "network": "TRC20"
}
POST /api/wallets/withdraw Create withdrawal AUTH ▼

Submit a withdrawal request. Requires 2FA verification if enabled on your account.

Request Body
FieldTypeRequiredDescription
currencystringYesUSDT, BTC, or WART
amountdecimalYesWithdrawal amount
addressstringYesDestination address
networkstringYesTRC20, BEP20, BTC, or WART
totp_codestringIf 2FA6-digit TOTP code (required if 2FA enabled)
Response
{
  "id": "uuid",
  "status": "pending_validation",
  "message": "Withdrawal created"
}
Note: Withdrawal requests are processed and subject to security review.

History

GET /api/history/deposits Deposit history AUTH ▼

Returns last 100 deposits for the authenticated user.

Response
[
  {
    "id": 1,
    "currency": "USDT",
    "amount": 500.0,
    "txid": "0x...",
    "confirmations": 12,
    "created_at": 1707000000000
  }
]
GET /api/history/withdrawals Withdrawal history AUTH ▼

Returns last 100 withdrawals for the authenticated user.

Response
[
  {
    "id": "uuid",
    "currency": "USDT",
    "network": "TRC20",
    "amount": 100.0,
    "fee": 7.0,
    "to_address": "TAddr...",
    "state": "confirmed",
    "txid": "0x...",
    "created_at": 1707000000000
  }
]
GET /api/fees/my-history Fee payment history AUTH ▼

Returns last 100 trading fee records for the authenticated user.

Response
{
  "user_id": 84291,
  "fees": [
    {
      "trade_id": "uuid",
      "currency": "USDT",
      "amount": 22.50,
      "fee_type": "taker",
      "created_at": 1707000000000
    }
  ],
  "total_paid": 450.75
}

API Key Management

POST /api/user/api-keys/create Create API key AUTH ▼

Create a new API key pair. The secret is only shown once.

Request Body
FieldTypeRequiredDescription
key_namestringYesLabel for this key (e.g. "MyBot")
permissionsarrayOptionalArray of permissions
Response
{
  "id": "uuid",
  "api_key": "your_api_key",
  "secret_key": "your_api_secret",
  "key_name": "MyBot",
  "permissions": ["read:all", "write:orders"]
}
Important: Save the secret_key immediately. It cannot be retrieved later.
GET /api/user/api-keys List API keys AUTH ▼

List all API keys for the authenticated user. Secret keys are not returned.

Response
[
  {
    "id": "uuid",
    "key_name": "MyBot",
    "api_key_prefix": "xxxxx...",
    "permissions": ["read:all"],
    "created_at": 1707000000000
  }
]
DELETE /api/user/api-keys/{api_key_id} Revoke API key AUTH ▼

Permanently revoke an API key. This action cannot be undone.

Path Parameters
NameTypeRequiredDescription
api_key_iduuidYesAPI key UUID

WebSocket API

Real-time data streams via WebSocket. Connect to receive live order book updates, trades, candle data, and user-specific order updates.

Endpoint: wss://api.tradegrail.com/ws/
Candles: wss://api.tradegrail.com/ws/candles
Authentication is optional. Authenticated connections receive user-specific order updates.
Connect & Subscribe
// JavaScript example
const ws = new WebSocket("wss://api.tradegrail.com/ws/");

ws.onopen = () => {
  ws.send(JSON.stringify({
    "type": "subscribe",
    "pair": "BTC-USDT"
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.type, data.payload);
};

Order Book Stream

Receive real-time order book snapshots when orders are placed, filled, or cancelled.

Message format
{
  "type": "BookUpdate",
  "payload": {
    "pair": "BTC-USDT",
    "bids": [
      { "price": 44999.0, "amount": 1.5 }
    ],
    "asks": [
      { "price": 45001.0, "amount": 2.0 }
    ],
    "sequence": 12345
  }
}

Trades Stream

Receive real-time trade executions as they happen.

Message format
{
  "type": "TradesUpdate",
  "payload": {
    "pair": "BTC-USDT",
    "trades": [
      {
        "id": "uuid",
        "price": 45000.0,
        "amount": 0.5,
        "side": "buy",
        "timestamp": 1707000000000
      }
    ]
  }
}

Candle Stream

Real-time OHLCV candle updates. Connect to wss://api.tradegrail.com/ws/candles.

Message format
{
  "type": "candle_update",
  "pair": "BTC-USDT",
  "candle": {
    "interval": "15m",
    "timestamp": 1707000000000,
    "open": 45000.0,
    "high": 45500.0,
    "low": 44500.0,
    "close": 45200.0,
    "volume": 50.5,
    "trades": 125
  }
}

User Data Stream

Authenticated connections receive real-time updates about their own orders. Requires authenticated session (browser).

Message format
{
  "type": "OrderUpdate",
  "payload": {
    "pair": "BTC-USDT",
    "order_id": "uuid",
    "status": "filled",
    "remaining": 0.0,
    "timestamp": 1707000000000
  }
}