Venues & Symbols

The API abstracts 13 live venues (plus virtual consolidators) into a single wire protocol. The same subscribe/unsubscribe actions work for all of them; only the set of message types they emit differs.

When in doubt about which symbols exist, query GET /v1/symbols/{exchange} — it returns the authoritative live list at any moment.

Venue matrix

Venue id	Class	Chain	Symbol format	Message types
`hl`	CLOB perp	HyperEVM	`ETH`, `kPEPE`, `PURR/USDC`	`quote`, `print` (+ `d_*`), `funding`
`dydx`	CLOB perp	dYdX V4 (Cosmos)	`ETH-USD`, `BTC-USD`, `SOL-USD`	`quote`, `print` (+ `d_*`), `funding`
`gmx`	Oracle perp	Arbitrum	`ETH`, `BTC`	`quote`, `funding`
`vertex`	Oracle perp	Arbitrum	`BTC`, `ETH`	`quote`, `funding`
`ostium`	Oracle perp (RWA)	Arbitrum	`XAU/USD`, `SPX/USD`, `EUR/USD`	`quote`, `print`, `funding`
`uni`	AMM V3	Arbitrum	`WETH/USDC`	`quote`, `print`, `depth`, `liquidity`
`univ4`	AMM V4	Arbitrum	`WETH/USDC`	`quote`, `print`, `depth`, `liquidity`
`univ4chain`	AMM V4	Unichain (130)	`ETH/USDC`	`quote`, `print`, `depth`, `liquidity`
`sushi`	AMM V3-fork	Arbitrum	`WETH/USDC`	`quote`, `print`, `depth`, `liquidity`
`pancake`	AMM V3-fork	Arbitrum	`WETH/USDC`	`quote`, `print`, `depth`, `liquidity`
`balancer`	Weighted AMM	Arbitrum	`WETH/USDC`	`quote`
`pendle`	Yield rate	Arb / Base / Eth	`PT-weETH-25JUN2026` or address	`rate_market`, `rate_depth`, `print`
`spectra`	Yield rate	Arb / Base / Eth	`PT-sw-USPC-...` or address	`rate_market`, `print`

Virtual venues (cross-venue consolidators):

Venue id	What it delivers
`ammbook`	Consolidated NBBO across all four Arbitrum AMMs (`uni`, `univ4`, `sushi`, `pancake`)
`ammliquidity`	Consolidated Mint/Burn stream from all four AMMs + snapshot of up to 1000 recent events
`rates`	Consolidated yield feed — subscribe as `rates:all`, `rates:swaps`, or `rates:<PT-symbol>`

Venue class notes

CLOB perps — `hl`, `dydx`

Native order books. quote arrives on every L2 update (sub-second). Both venues’ print messages carry server-computed microstructure fields (d_hawkes, d_lobimb, etc.) — see Message Types. dYdX V4 prints carry the same d_* field set as HL.

funding.intervalHrs is 8 for both. ratePct is always annualized regardless of native cadence.

dYdX V4 lives on a sovereign Cosmos SDK chain (CometBFT). Symbol format is canonical BASE-USD (ETH-USD, BTC-USD, SOL-USD); bare-ticker inputs auto-normalize server-side. ~121 active perp markets. No spot markets on dYdX — V3 and V4 are perp-only.

Oracle perps — `gmx`, `vertex`, `ostium`

Price is oracle-driven. quote is a synthetic mid + venue spread model, polled at 2–5s cadence. GMX and Vertex do not emit print messages. Ostium does — it fires on OpenTrade/CloseTrade on-chain events.

Ostium covers RWA assets: gold (XAU/USD), oil (WTI/USD), FX pairs (EUR/USD), indices (SPX/USD), single-name equities.

AMM spot — `uni`, `univ4`, `univ4chain`, `sushi`, `pancake`

quote is derived from current tick + active liquidity. One level per pool fee tier; OrderLevel.fee reports the fee in ppm (500 = 0.05%).

depth is a snapshot of tick boundaries near the current price with pre-computed market-impact estimates ($1k / $10k / $100k / $1M). Emitted on every Mint/Burn, throttled to 200ms per symbol.

liquidity is the raw Mint or Burn event.

AMM venues are extensible — any token pair resolvable via the on-chain pool registry is subscribable. Subscribe to a pair not in the published list and the backend will auto-discover the pool.

univ4chain (Unichain) uses native ETH (address(0)): subscribe as ETH/USDC, not WETH/USDC.

Yield rate — `pendle`, `spectra`

rate_market is a per-market snapshot: implied APY, PT price, TVL, expiry. Emitted ~5s (Pendle) / ~30s (Spectra). rate_depth (Pendle only) is a depth-at-size APY quote replacing the traditional price-level DOM.

Virtual venues

Subscribing to any individual AMM venue (uni, univ4, sushi, pancake) causes the backend to also subscribe all four Arbitrum AMMs to that symbol internally. You receive messages only from the venues you explicitly subscribed to — unless you also subscribed to ammbook.

For the rates virtual venue:

rates:all — rate_market for every Pendle + Spectra market
rates:swaps — print from every Pendle + Spectra pool
rates:<PT-symbol> — per-market rate_market + rate_depth (Pendle only)

Chain reference

Chain	Chain ID	Venues
Arbitrum One	42161	`gmx`, `vertex`, `ostium`, `uni`, `univ4`, `sushi`, `pancake`, `balancer`, `pendle`, `spectra`
Unichain	130	`univ4chain`
Base	8453	`pendle`, `spectra`
Ethereum	1	`pendle`, `spectra`
HyperEVM	(HL L1)	`hl`
dYdX Chain	`dydx-mainnet-1`	`dydx`

Symbol naming

General rules

Case-sensitive. HL canonical symbols are uppercase (ETH, BTC); the k prefix for micro contracts is lowercase (kPEPE, kSHIB).
No leading/trailing whitespace. The backend does not trim.
AMM pairs use a forward slash. WETH/USDC, not WETH-USDC.
Address symbols are lowercase. Pendle/Spectra accept the PT contract address; always pass it lowercase.

Per-venue formats

Venue	Symbol form	Example
`hl`	Standard perp	`ETH`, `BTC`, `SOL`
`hl`	Micro contract	`kPEPE`, `kSHIB`, `kBONK`
`hl`	Builder DEX perp	`xyz:CL`, `xyz:NG`
`hl`	Spot pair	`PURR/USDC`
`dydx`	`BASE-USD` (hyphenated)	`ETH-USD`, `BTC-USD`, `SOL-USD`
`gmx`, `vertex`	Bare uppercase	`ETH`, `BTC`, `LINK`
`ostium`	With `/USD` quote	`XAU/USD`, `EUR/USD`, `SPX/USD`
AMM venues	`BASE/QUOTE` tickers	`WETH/USDC`, `WBTC/WETH`
`univ4chain`	Native ETH	`ETH/USDC`
`pendle`, `spectra`	PT symbol	`PT-weETH-25JUN2026`
`pendle`, `spectra`	Contract address	`0xc62d...fe6` (lowercase)

For Ostium, bare crypto symbols are normalized to /USD automatically (ETH → ETH/USD). Subscribe using the canonical form.

For Pendle/Spectra, the address is the unique key — PT symbol strings are human-friendly aliases. Historical queries (/v1/history/rates/:address) require the address.

Discovery in code

import httpx

base = "https://api.mackinac.io"

# Live HL symbols
hl_live = httpx.get(f"{base}/v1/symbols/hl/live").json()

# Which venues quote ETH?
eth = httpx.get(f"{base}/v1/instruments/ETH").json()
# → {"symbol":"ETH","venues":[{"exchange":"hl","symbol":"ETH"},{"exchange":"dydx","symbol":"ETH-USD"},{"exchange":"gmx","symbol":"ETH"},…]}

See Discovery REST for the full endpoint reference.