AArtery
WelcomeGet StartedConceptsProvidersRecipesReferenceAPI ReferencePlayground
On this page

Hyperliquid Spot Markets

The /v1/markets/hyperliquid/spot/* namespace covers spot pair market data on Hyperliquid — PURR/USDC, HYPE/USDC, and the rest of the canonical HL spot universe. Each endpoint maps onto an HL Info call but reshapes the response into the Artery wire format — typed columns, consistent error envelope, server-side caching.

The shape of every endpoint mirrors the perp namespace; the only differences are the path (/spot/pairs/{pair}/…) and the fields specific to spot (prevDayPrice, dayChangePct, no funding/OI).

Note

Why pair, not coin? HL spot is pair-quoted (PURR/USDC) while HL perp is single-asset (BTC). Same provider, different domain — see ADR-0004 for the design rationale. Use /v1/markets/hyperliquid/coins/* for perps and /v1/markets/hyperliquid/spot/pairs/* for spot.

Note

URL form: Slash is reserved in URL paths, so the customer-facing identifier is dash-separated (HYPE-USDC). The human-readable slash form (HYPE/USDC) is returned in the response body as name.

HL itself uses @<universe-index> (@107, @1, …) as the upstream id for most spot pairs — only PURR/USDC is given a slash-form name. Artery hides this by deriving names from the spot token table, so you never need to know which pair is @107. The original index is still returned in the pair list for power users who want to round-trip into the raw HL Info API.

Endpoint summary

MethodPathCachePurpose
GET/v1/markets/hyperliquid/spot/pairs60sList every canonical spot pair.
GET/v1/markets/hyperliquid/spot/pairs/{pair}5sMark / mid / 24h-change snapshot.
GET/v1/markets/hyperliquid/spot/pairs/{pair}/orderbook2sL2 depth (top-N bids/asks).
GET/v1/markets/hyperliquid/spot/pairs/{pair}/trades5sMost recent taker fills.
GET/v1/markets/hyperliquid/spot/pairs/{pair}/candles30sOHLC candles, flexible windowing.

All five require the read scope and meter under the markets.read SKU (shared with HL perp + future providers — no double-billing for crossing the perp/spot line).

List pairs

bashcurl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/markets/hyperliquid/spot/pairs"
jsonc{
  "pairs": [
    {
      "name": "PURR/USDC",
      "pair": "PURR-USDC",
      "baseToken": "PURR",
      "quoteToken": "USDC",
      "baseDecimals": 5,
      "quoteDecimals": 8,
      "index": 0
    },
    {
      "name": "HYPE/USDC",
      "pair": "HYPE-USDC",
      "baseToken": "HYPE",
      "quoteToken": "USDC",
      "baseDecimals": 4,
      "quoteDecimals": 8,
      "index": 1
    }
  ]
}
  • pair is what you pass in the URL path. name is the HL-canonical identifier (slash form).
  • Non-canonical / testnet pairs are filtered out. For the raw HL universe use GET /v1/hyperliquid/info/spotMeta from the passthrough family.

Pair snapshot

bashcurl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/markets/hyperliquid/spot/pairs/PURR-USDC"
jsonc{
  "pair": "PURR-USDC",
  "markPrice": 0.2143,
  "midPrice": 0.2142,
  "prevDayPrice": 0.2087,
  "dayChangePct": 2.68,
  "dayNotionalVolume": 1234567.89,
  "dayBaseVolume": 5760000.0
}
  • dayChangePct = (markPrice - prevDayPrice) / prevDayPrice * 100. Null when either input is missing or prevDayPrice is 0.
  • Unknown pair → 404 unknown_pair.

Orderbook

bashcurl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/markets/hyperliquid/spot/pairs/PURR-USDC/orderbook?depth=20"
jsonc{
  "pair": "PURR-USDC",
  "bids": [
    { "price": 0.2140, "size": 500 },
    { "price": 0.2139, "size": 1000 }
  ],
  "asks": [
    { "price": 0.2146, "size": 400 },
    { "price": 0.2147, "size": 800 }
  ],
  "ts": 1779163200000
}
ParameterTypeDefaultNotes
depthint20Clamped to [1, 100].

Recent trades

bashcurl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/markets/hyperliquid/spot/pairs/PURR-USDC/trades?limit=50"
jsonc{
  "trades": [
    {
      "pair": "PURR-USDC",
      "price": 0.2143,
      "size": 100.0,
      "side": "buy",
      "ts": 1779163198120,
      "txHash": "0x..."
    }
  ]
}
  • side: "buy" = aggressor lifted the ask; "sell" = aggressor hit the bid.
  • limit clamped to [1, 200]; default 50.

OHLC candles

bash# Last 100 1h candles
curl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/markets/hyperliquid/spot/pairs/PURR-USDC/candles?interval=1h&limit=100"
 
# Explicit time range
curl -H "Authorization: Bearer art_live_<your-key>" \
  "https://api.artery.questflow.ai/v1/markets/hyperliquid/spot/pairs/PURR-USDC/candles?interval=1h&start_time=2026-05-18T00:00:00Z&end_time=2026-05-19T00:00:00Z&limit=30"
jsonc{
  "candles": [
    {
      "ts": 1779163200000,
      "open": 0.2110,
      "high": 0.2155,
      "low":  0.2095,
      "close": 0.2143,
      "volume": 487500
    }
  ]
}

Query parameters

ParameterTypeDefaultNotes
intervalenum1hOne of 1m, 5m, 15m, 1h, 4h, 1d.
limitint100Clamped to [1, 500]. Always caps the response.
start_timestring | msderivedUnix-ms or ISO-8601. Inclusive lower bound.
end_timestring | msderivedUnix-ms or ISO-8601. Exclusive upper bound.

Windowing strategies

Caller sendsServer behavior
neither boundMost recent limit candles.
both boundsEvery bucket in [start_time, end_time), capped at limit newest.
start_time onlyFrom that timestamp forward, capped at limit.
end_time onlyEnding at that timestamp, the most recent limit candles.
  • start_time >= end_time → 400 validation_failed.
  • Candles are returned oldest-first within the response.

Error responses

HTTPerror.codeWhen
400validation_failedBad interval, malformed start_time/end_time, start >= end, malformed pair.
404unknown_pairpair not present in HL canonical spot universe.
401unauthenticatedMissing / invalid Authorization.
403insufficient_scopeKey lacks read.
429rate_limitedOver the markets.read SKU quota.
502upstream_unavailableHL Info endpoint 5xx'd or timed out.

Caching

Same tiers as the perp namespace — see the perp markets reference for the why behind each TTL.

Edit this page on GitHubLast updated
PreviousHyperliquid MarketsNextPortfolio
Hyperliquid Spot Markets · Artery API Docs