API Reference
Single endpoint, 20 operations, 5 DEXes. Every request is normalized — same params, same response shape, regardless of exchange.
Quick start
mt_live_ (mainnet) or mt_test_ (testnet). Copy the full key — it's only shown once.Authentication
Pass your API key via the X-API-Key header (preferred), or as a Bearer token:
A testnet key cannot access mainnet credentials and vice versa. Scopes are enforced per-key and cannot be widened after creation.
Request format
Every request body must include operation. Most operations also require credentialId — your exchange credential UUID from the Mithril platform.
BTC-USD-PERP, BTC/USDT-P, and BTC all resolve correctly per exchange.Operations
Operations are split by tier: Free for read-only market + account data, Builder+ for order placement and management.
Market data
FreegetOrderbookCurrent orderbook for a market.
{
"success": true,
"bids": [["94200.00", "1.5"], ["94190.00", "3.2"], ...],
"asks": [["94210.00", "0.8"], ["94220.00", "2.1"], ...]
}getMarkPriceCurrent mark price for a perpetual market.
{
"success": true,
"markPrice": "94205.50",
"indexPrice": "94198.20"
}getCandlesOHLCV candlestick data. Interval is normalized per exchange.
{
"success": true,
"candles": [
{ "time": 1710000000, "open": "93800", "high": "94500", "low": "93600", "close": "94200", "volume": "1204.5" },
...
]
}getFundingRateCurrent perpetual funding rate.
{
"success": true,
"fundingRate": "0.0001",
"nextFundingTime": 1710014400
}getMarketsWithFundingAll available markets with current funding rates.
{
"success": true,
"markets": [
{ "symbol": "BTC-USD-PERP", "markPrice": "94205", "fundingRate": "0.0001", "openInterest": "12400000" },
...
]
}getFeeInfoMaker/taker fees for a market in basis points (1 bps = 0.01%).
{
"success": true,
"makerFee": "2",
"takerFee": "5"
}Account
FreegetBalanceAccount equity, free collateral, and total account value.
{
"success": true,
"exchange_type": "paradex",
"equity": "10452.38",
"freeCollateral": "8200.00",
"accountValue": "10452.38"
}getPositionsAll open positions with entry price, size, and unrealized PnL.
{
"success": true,
"positions": [
{
"market": "BTC-USD-PERP",
"side": "LONG",
"size": "0.1",
"entryPrice": "92000.00",
"markPrice": "94200.00",
"unrealizedPnl": "220.00",
"leverage": "10"
}
]
}getOrdersAll open/pending orders.
{
"success": true,
"orders": [
{
"id": "ord_abc123",
"market": "ETH-USD-PERP",
"side": "BUY",
"type": "LIMIT",
"size": "1.0",
"price": "3200.00",
"filledSize": "0",
"status": "OPEN",
"createdAt": 1710000000
}
]
}getFillsTrade fill history.
{
"success": true,
"fills": [
{
"id": "fill_xyz",
"market": "BTC-USD-PERP",
"side": "BUY",
"size": "0.05",
"price": "93800.00",
"fee": "0.235",
"timestamp": 1710001000
}
]
}testCredentialsVerify that exchange credentials are valid and active.
{
"success": true,
"valid": true,
"exchange": "paradex"
}Order placement
Builder+placeLimitOrderPlace a limit order at a specific price.
{
"operation": "placeLimitOrder",
"credentialId": "9f2a...d841",
"market": "BTC-USD-PERP",
"side": "BUY",
"size": "0.01",
"price": "94000"
}{
"success": true,
"orderId": "ord_abc123",
"market": "BTC-USD-PERP",
"side": "BUY",
"size": "0.01",
"price": "94000.00",
"status": "OPEN"
}placeMarketOrderExecute immediately at the best available price.
{
"success": true,
"orderId": "ord_xyz789",
"filledPrice": "94212.50",
"filledSize": "0.01",
"fee": "0.047"
}placeStopOrderPlace a stop/trigger order. Activates when mark price hits trigger_price.
{
"success": true,
"orderId": "ord_stop1",
"status": "PENDING",
"triggerPrice": "92000.00"
}placeBatchOrderSubmit up to 10 orders in a single request (atomic per exchange).
{
"operation": "placeBatchOrder",
"credentialId": "9f2a...d841",
"orders": [
{ "market": "BTC-USD-PERP", "side": "BUY", "size": "0.01", "price": "93000", "orderType": "LIMIT" },
{ "market": "BTC-USD-PERP", "side": "SELL", "size": "0.01", "price": "95000", "orderType": "LIMIT" }
]
}{
"success": true,
"results": [
{ "orderId": "ord_a1", "status": "OPEN" },
{ "orderId": "ord_a2", "status": "OPEN" }
]
}placeProtectionOrdersPlace TP/SL orders on an existing position in one call.
{
"success": true,
"tpOrderId": "ord_tp1",
"slOrderId": "ord_sl1"
}Order management
Builder+cancelOrderCancel a specific order by its exchange order ID.
{ "success": true }cancelAllOrdersCancel all open orders on a market.
{ "success": true, "cancelledCount": 3 }closeAllPositionsClose all open positions on a market with market orders.
{ "success": true, "closedSize": "0.1", "avgClosePrice": "94180.00" }setLeverageSet cross-margin leverage for a market.
{ "success": true, "leverage": 10 }Rate limits
When a limit is exceeded, the gateway returns 429 with a Retry-After header (seconds to wait) and rate limit headers on every response:
Error codes
All errors follow the same envelope:
Response headers
MCP setup
Mithril exposes all 20 operations as MCP tools via Streamable HTTP transport, letting Claude and other LLM agents trade directly. Available on Builder+.
Claude Desktop config
Add to ~/.claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Claude Code config
How it works
The MCP server uses Streamable HTTP — stateless JSON-RPC over POST. Your API key is passed via the Authorization header. Tool names use snake_case (e.g. get_balance, place_limit_order) and are automatically converted to the gateway's camelCase operations.
Once connected, Claude can call tools like get_balance, place_limit_order, cancel_all_orders directly — 20 tools total covering all market data, account, order, and management operations.