> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK REST usage

> Use 0xArchive SDK clients for REST market-data routes, request options, pagination, response envelopes, and typed examples.

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

<CodeGroup>
  ```python Python theme={"theme":"github-dark"}
  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)
  ```

  ```typescript TypeScript theme={"theme":"github-dark"}
  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);
  ```

  ```rust Rust theme={"theme":"github-dark"}
  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(())
  }
  ```
</CodeGroup>

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.*`<br />Symbols such as `BTC`<br />REST: `/v1/hyperliquid/*` |
| HIP-3 | `client.hyperliquid.hip3.*`<br />Symbols such as `km:US500`<br />REST: `/v1/hyperliquid/hip3/*` |
| Hyperliquid Spot | TypeScript/Python: `client.spot.*`; Rust: `client.hyperliquid.spot.*`<br />Pairs such as `HYPE-USDC`<br />REST: [Hyperliquid Spot routes](/rest-api/spot) under `/v1/hyperliquid/spot/*` |
| HIP-4 | `client.hyperliquid.hip4.*` where the installed package has HIP-4 helpers<br />Outcome sides such as `#0`<br />REST: `/v1/hyperliquid/hip4/*` |
| Lighter | `client.lighter.*`<br />Symbols such as `BTC`<br />REST: `/v1/lighter/*` |
| Lighter on Robinhood Chain | Python and Rust: `client.rh_lighter.*`; TypeScript: `client.rhLighter.*` (SDK `1.12.0` and later)<br />Symbols such as `BTC` and `AAPL-USDG`<br />REST: [Lighter on Robinhood Chain routes](/rest-api/rh-lighter) 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](/rest-api/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](/webhooks).
* **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.

```python Direct REST theme={"theme":"github-dark"}
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.

```typescript theme={"theme":"github-dark"}
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](/rest-api/pagination). This window, the hour that ended one hour ago, is inside every plan's history, including Free's most recent 30 days.

```typescript theme={"theme":"github-dark"}
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](/data-quality) and [Rate limits](/rate-limits). For a large file export or warehouse load, use the [Data Catalog](/data-catalog) instead.

## Next step

Stream and replay from the same SDKs with [SDK WebSocket usage](/sdks/websocket-usage).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.