SDK REST usage

Call 0xArchive REST routes from TypeScript, Python, or Rust through the SDK clients. Each client wraps the routes in the Endpoint reference and keeps the venue family in the method path, so a Hyperliquid call never turns into a Lighter call by accident.

from os import environ
from oxarchive import Client

client = Client(api_key=environ["OXARCHIVE_API_KEY"])
book = client.hyperliquid.orderbook.get("BTC")
print(book.coin, book.mid_price)

import { OxArchive } from "@0xarchive/sdk";

const client = new OxArchive({
  apiKey: process.env.OXARCHIVE_API_KEY!
});

const book = await client.hyperliquid.orderbook.get("BTC");
console.log(book);

use oxarchive::OxArchive;

#[tokio::main]
async fn main() -> oxarchive::Result<()> {
    let api_key = std::env::var("OXARCHIVE_API_KEY").expect("Set OXARCHIVE_API_KEY");
    let client = OxArchive::new(api_key)?;
    let book = client.hyperliquid.orderbook.get("BTC", None).await?;
    println!("{:?}", book.mid_price);
    Ok(())
}

If a method name differs in your installed version, follow that package’s README and types; the REST reference stays the route contract.

Client namespaces

Family	Namespace, symbols, and REST routes
Hyperliquid core	`client.hyperliquid.` Symbols such as `BTC` REST: `/v1/hyperliquid/`
HIP-3	`client.hyperliquid.hip3.` Symbols such as `km:US500` REST: `/v1/hyperliquid/hip3/`
Hyperliquid Spot	TypeScript/Python: `client.spot.`; Rust: `client.hyperliquid.spot.` Pairs such as `HYPE-USDC` REST: Hyperliquid Spot routes under `/v1/hyperliquid/spot/*`
HIP-4	`client.hyperliquid.hip4.` where the installed package has HIP-4 helpers Outcome sides such as `#0` REST: `/v1/hyperliquid/hip4/`
Lighter	`client.lighter.` Symbols such as `BTC` REST: `/v1/lighter/`
Lighter on Robinhood Chain	Python and Rust: `client.rh_lighter.`; TypeScript: `client.rhLighter.` (SDK `1.12.0` and later) Symbols such as `BTC` and `AAPL-USDG` REST: Lighter on Robinhood Chain routes under `/v1/rh-lighter/*`

Across families, SDK 1.12.0 and later also include:

Account positions: positions on the Hyperliquid, HIP-3, Lighter, and Robinhood Chain clients, plus accounts.by_l1 (TypeScript accounts.byL1) on Lighter mainnet. See Account positions.
Webhooks: client.webhooks for endpoints, subscriptions, estimate and dry-run previews, watched addresses, and the delivery log, plus a signature verifier. See Webhook routes.
Market analytics: cvd and breadth on the Hyperliquid and HIP-3 clients, oracle on HIP-3, wallets.classify on Hyperliquid and HIP-3, questions on HIP-4, and a top-level symbols.

Keep the family visible in your own wrappers too: a generic getOrderbook(symbol) helper should still name the venue family in its configuration or signature.

REST fallback

Call a route directly when you need its exact shape or your runtime has no SDK. Use the same key, response handling, request-ID logging, and data-quality checks as SDK code.

Direct REST

from os import environ
import requests

res = requests.get(
    "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC",
    headers={"X-API-Key": environ["OXARCHIVE_API_KEY"]},
    timeout=20,
)
res.raise_for_status()
payload = res.json()
print(payload["data"]["symbol"], payload["meta"]["request_id"])

Keep request IDs and errors

Market-data responses carry success, data, and meta: lists add meta.count, paged routes add meta.has_more and meta.next_cursor, and each response has a meta.request_id. When an SDK unwraps data, keep the metadata alongside the result so retries, logs, and support requests still have the request ID.

import { OxArchive, OxArchiveError } from "@0xarchive/sdk";

const client = new OxArchive({
  apiKey: process.env.OXARCHIVE_API_KEY!,
  timeout: 30_000
});

try {
  const orderbook = await client.hyperliquid.orderbook.get("BTC", { depth: 20 });
  console.log(orderbook.coin, orderbook.midPrice);
} catch (error) {
  if (error instanceof OxArchiveError) {
    console.error(error.code, error.errorCode, error.message, error.requestId);
  }
  throw error;
}

On a failure, keep the HTTP status, the API’s error_code (errorCode in TypeScript), and the request ID with the failed job. If your wrapper hides metadata, add a logging hook so production callers can still recover the request ID.

Page through history

Fix the window once, then follow the returned cursor with the same bounds and a page budget. See REST pagination. This window, the hour that ended one hour ago, is inside every plan’s history, including Free’s most recent 30 days.

const end = Date.now() - 60 * 60_000;          // one hour ago
const window = { start: end - 60 * 60_000, end, limit: 1000 };

let page = await client.hyperliquid.trades.list("BTC", window);
const pages = [page];

while (page.hasMore && pages.length < 10) {    // page budget
  page = await client.hyperliquid.trades.list("BTC", { ...window, cursor: page.nextCursor });
  pages.push(page);
}

Store the request path, parameters, each cursor, and each request ID with the output. Confirm one window’s schema, data quality, and rate behavior before widening across symbols, and pair large pulls with Data quality and Rate limits. For a large file export or warehouse load, use the Data Catalog instead.

Next step

Stream and replay from the same SDKs with SDK WebSocket usage.

SDKs

CLI

MCP

Agent skill

AI agents

Client namespaces

REST fallback

Keep request IDs and errors

Page through history

Next step

​Client namespaces

​REST fallback

​Keep request IDs and errors

​Page through history

​Next step

Client namespaces

REST fallback

Keep request IDs and errors

Page through history

Next step