# Mithril API — LLM Reference

Base URL: https://api.mithril.money/v1
Method: POST
Auth: X-API-Key: mt_live_YOUR_KEY (header) or Authorization: Bearer mt_live_YOUR_KEY

All requests: { "operation": "<name>", "credentialId": "<uuid>", ...params }
All responses: { "success": true|false, ...data } or { "success": false, "code": "...", "error": "..." }

---

## TIERS

| Tier    | Keys | RPM | RPD     | Operations       | Price  |
|---------|------|-----|---------|------------------|--------|
| free    | 3    | 30  | 5,000   | read-only        | $0     |
| builder | 10   | 120 | 50,000  | all              | $29/mo |
| pro     | 25   | 600 | 500,000 | all              | $79/mo |

---

## READ OPERATIONS (free tier)

### getBalance
Get account equity, free collateral, account value.
Params: credentialId (required)
Response: { success, exchange_type, equity, freeCollateral, accountValue }

### getPositions
Get open positions.
Params: credentialId (required), market (optional)
Response: { success, positions: [{ market, side, size, entryPrice, markPrice, unrealizedPnl, leverage }] }

### getOrders
Get open/pending orders.
Params: credentialId (required), market (optional)
Response: { success, orders: [{ id, market, side, type, size, price, filledSize, status, createdAt }] }

### getFills
Get trade fill history.
Params: credentialId (required), market (required), limit (optional, default 100)
Response: { success, fills: [{ id, market, side, size, price, fee, timestamp }] }

### getOrderbook
Get current orderbook bids/asks.
Params: credentialId (required), market (required), depth (optional, default 20)
Response: { success, bids: [[price, size], ...], asks: [[price, size], ...] }

### getMarkPrice
Get current mark price and index price.
Params: credentialId (required), market (required)
Response: { success, markPrice, indexPrice }

### getCandles
Get OHLCV candlestick data.
Params: credentialId (required), market (required), interval (optional: 1/5/15/60/240/1440 minutes, default 60), limit (optional, default 100)
Response: { success, candles: [{ time, open, high, low, close, volume }] }

### getFundingRate
Get current perpetual funding rate.
Params: credentialId (required), market (required)
Response: { success, fundingRate, nextFundingTime }

### getMarketsWithFunding
Get all available markets with funding rates.
Params: credentialId (required)
Response: { success, markets: [{ symbol, markPrice, fundingRate, openInterest }] }

### getFeeInfo
Get maker/taker fees in basis points (1 bps = 0.01%).
Params: credentialId (required), market (required)
Response: { success, makerFee, takerFee }

### testCredentials
Verify exchange credentials are valid.
Params: credentialId (required)
Response: { success, valid, exchange }

---

## WRITE OPERATIONS (builder+ tier)

### placeLimitOrder
Place a limit order.
Params: credentialId (required), market (required), side ("BUY"|"SELL", required), size (required), price (required), postOnly (optional), reduceOnly (optional), clientOrderId (optional)
Response: { success, orderId, market, side, size, price, status }

### placeMarketOrder
Execute at best available price immediately.
Params: credentialId (required), market (required), side ("BUY"|"SELL", required), size (required), reduceOnly (optional)
Response: { success, orderId, filledPrice, filledSize, fee }

### placeStopOrder
Place a stop/trigger order.
Params: credentialId (required), market (required), side ("BUY"|"SELL", required), size (required), triggerPrice (required), reduceOnly (optional, default true)
Response: { success, orderId, status, triggerPrice }

### placeBatchOrder
Place up to 10 orders at once.
Params: credentialId (required), orders (array, required): [{ market, side, size, price, orderType, postOnly, clientId }]
Response: { success, results: [{ orderId, status }] }

### placeProtectionOrders
Place TP/SL on an existing position.
Params: credentialId (required), market (required), side ("LONG"|"SHORT", required), size (required), entryPrice (required), tpPercent (optional, %), slPercent (optional, %)
Response: { success, tpOrderId, slOrderId }

### cancelOrder
Cancel a specific order.
Params: credentialId (required), orderId (required), market (required)
Response: { success }

### cancelAllOrders
Cancel all open orders on a market.
Params: credentialId (required), market (required)
Response: { success, cancelledCount }

### closeAllPositions
Close all positions on a market with market orders.
Params: credentialId (required), market (required)
Response: { success, closedSize, avgClosePrice }

### setLeverage
Set cross-margin leverage.
Params: credentialId (required), market (required), leverage (number, required)
Response: { success, leverage }

---

## ERROR CODES

MISSING_API_KEY       401  No API key provided
INVALID_KEY_FORMAT    401  Key doesn't start with mt_live_ or mt_test_
INVALID_API_KEY       401  Key not found
KEY_REVOKED           401  Key manually revoked
KEY_EXPIRED           401  Key past expiry date
TIER_INSUFFICIENT     403  Operation requires Builder or Pro tier
OPERATION_NOT_ALLOWED 403  Operation not in key's scope
CREDENTIAL_NOT_ALLOWED 403 Credential not in key's scope
EXCHANGE_NOT_ALLOWED  403  Exchange not in key's scope
MISSING_OPERATION     400  operation field missing
INVALID_JSON          400  Request body is not valid JSON
RATE_LIMITED          429  Per-minute or per-day limit exceeded
EXCHANGE_ERROR        502  Upstream exchange returned an error
INTERNAL_ERROR        500  Gateway error

---

## RESPONSE HEADERS

X-Request-Id                  UUID for this request
X-Request-Duration-Ms         Total gateway latency
X-RateLimit-Limit-Minute      Per-minute limit
X-RateLimit-Remaining-Minute  Requests left this minute
X-RateLimit-Limit-Day         Per-day limit
X-RateLimit-Remaining-Day     Requests left today

---

## MCP SETUP

Transport: Streamable HTTP (stateless JSON-RPC over POST)
URL: https://pqnoeidcslevoexrduio.supabase.co/functions/v1/mithril-mcp-server
Auth: Authorization: Bearer mt_live_YOUR_KEY

Add to Claude Desktop config (claude_desktop_config.json):
{
  "mcpServers": {
    "mithril": {
      "url": "https://pqnoeidcslevoexrduio.supabase.co/functions/v1/mithril-mcp-server",
      "headers": {
        "Authorization": "Bearer mt_live_YOUR_KEY"
      }
    }
  }
}

MCP tool names (snake_case) map to API operations (camelCase):
get_balance -> getBalance
get_positions -> getPositions
get_orders -> getOrders
get_fills -> getFills
get_orderbook -> getOrderbook
get_mark_price -> getMarkPrice
get_candles -> getCandles
get_funding_rate -> getFundingRate
get_all_markets -> getMarketsWithFunding
get_fee_info -> getFeeInfo
test_credentials -> testCredentials
place_limit_order -> placeLimitOrder
place_market_order -> placeMarketOrder
place_stop_order -> placeStopOrder
place_batch_orders -> placeBatchOrder
place_protection_orders -> placeProtectionOrders
cancel_order -> cancelOrder
cancel_all_orders -> cancelAllOrders
close_all_positions -> closeAllPositions
set_leverage -> setLeverage

---

Docs: https://api.mithril.money/docs
Dashboard: https://api.mithril.money/dashboard
Pricing: https://api.mithril.money/pricing