Symbols

Unified symbol format for cross-exchange consistency and how to use the /markets endpoint.

The MMT API uses unified symbols for cross-exchange consistency. You must fetch the symbol list from /markets and use our unified symbol format in all API requests.

Important: Always fetch /markets first and use the symbol field exactly as provided. Do not construct symbols yourself or use exchange-native tickers.

How It Works

Fetch /markets to get available symbols per exchange
Use the symbol field in all API requests and WebSocket subscriptions
Use other fields for display - exchange_ticker, base, quote are for your UI

{
  "symbol": "btc/usd",           // Use this for API calls
  "exchange_ticker": "BTCUSDT",  // For display (exchange's native format)
  "base": "BTC",                 // For display
  "quote": "USDT",               // For display
  "normalised_base": "btc",
  "normalised_quote": "usd"
}

API requests: Use symbol field (btc/usd)

Display to users: Use exchange_ticker, base, or quote as you prefer

Unified Symbol Format

Symbols use the pattern base/quote (lowercase, slash-separated):

Example	Description
`btc/usd`	Bitcoin vs USD
`eth/usd`	Ethereum vs USD
`sol/usd`	Solana vs USD

The unified symbol normalizes across exchanges - what Binance calls BTCUSDT and Coinbase calls BTC-USD both map to our unified btc/usd.

Finding Available Symbols

curl -H "X-API-Key: YOUR_KEY" "https://eu-central-1.mmt.gg/api/v1/markets"

Response:

{
  "exchanges": [
    {
      "id": "binancef",
      "symbols": [
        {
          "symbol": "btc/usd",
          "exchange_ticker": "BTCUSDT",
          "base": "BTC",
          "quote": "USDT",
          "normalised_base": "btc",
          "normalised_quote": "usd",
          "tick_size": 0.1,
          "step_size": 0.001
        }
      ]
    }
  ]
}

Using Symbols

REST API

# Use the symbol from /markets response
curl -H "X-API-Key: YOUR_KEY" \
  "https://eu-central-1.mmt.gg/api/v1/candles?exchange=binancef&symbol=btc/usd&tf=1m&from=1704067200&to=1704153600"

WebSocket

{
  "type": "subscribe",
  "channel": "candles",
  "exchange": "binancef",
  "symbol": "btc/usd",
  "tf": "1m"
}

Response Data

Responses return the same unified symbol:

{
  "exchange": "binancef",
  "symbol": "btc/usd",
  "data": [...]
}

Common Mistakes

Wrong: Constructing symbols yourself

# Don't guess or construct symbols
?symbol=BTCUSDT      # Wrong - exchange ticker
?symbol=BTC-USD      # Wrong - exchange format
?symbol=btc-usdt     # Wrong - dash separator
?symbol=btc/usdt     # Wrong if /markets returns btc/usd

Correct: Using symbols from /markets

# Always use exactly what /markets returns
?symbol=btc/usd      # Correct - matches /markets response

Case Sensitivity

Symbols are case-insensitive. These are equivalent:

btc/usd
BTC/USD
Btc/Usd

The API normalizes to lowercase internally.

Some endpoints support aggregating data across multiple exchanges (e.g., /stats, /volumes, /oi, /vd, /heatmap_sd, /heatmap_hd, /flat_heatmap_sd, /flat_heatmap_hd). When using these endpoints, the unified symbol must exist on all specified exchanges:

# Check /markets to verify btc/usd exists on both exchanges
/api/v1/heatmap_sd?exchange=binancef:bybitf&symbol=btc/usd&tf=1m&from=...&to=...

For aggregated requests, exchange IDs must be colon-separated, unique, and alphabetically ordered. Invalid aggregate exchange strings return INVALID_EXCHANGE.

Note: Not all endpoints support aggregation. See individual endpoint documentation for details. The /candles and /orderbook endpoints only support a single exchange.

/stop_heatmap, /tp_heatmap, and /liquidation_heatmap are also single-exchange only.

For LLMs and Automation

When building integrations:

Fetch /markets on startup - cache the symbol list
Match by unified symbol - use the symbol field for all API calls
Display using exchange fields - show exchange_ticker or base/quote in your UI

# Fetch markets and build a lookup
markets = fetch_markets()
symbols = {s["symbol"]: s for ex in markets["exchanges"] for s in ex["symbols"]}

# Use unified symbol for API calls
candles = fetch_candles(exchange="binancef", symbol="btc/usd", tf="1m", ...)

# Display using exchange ticker
display_name = symbols["btc/usd"]["exchange_ticker"]  # "BTCUSDT"