> ## 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.

SDKs wrap the same REST routes shown in Endpoint Reference. Keep route family selection explicit in code.

<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.symbol, 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>

<Tip>
  If an SDK method name differs from these examples, follow the package README and generated types. The REST reference remains the route contract.
</Tip>

## SDK Namespace Map

SDKs should keep venue families visible in the client namespace. The exact method names differ by runtime; keep the family name visible in wrappers, tests, and review notes.

| Family           | Common package shape                                                          | Example symbol                  | Fallback when helper is absent                      |
| ---------------- | ----------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------- |
| Hyperliquid core | `client.hyperliquid.*`                                                        | `BTC`                           | Generated REST route under `/v1/hyperliquid/*`      |
| HIP-3            | `client.hyperliquid.hip3.*`                                                   | `km:US500`                      | Generated REST route under `/v1/hyperliquid/hip3/*` |
| Lighter.xyz      | `client.lighter.*`                                                            | `BTC`                           | Generated REST route under `/v1/lighter/*`          |
| Hyperliquid Spot | TypeScript/Python: `client.spot.*`; Rust: `client.hyperliquid.spot.*`         | `HYPE-USDC`                     | Generated REST route under `/v1/hyperliquid/spot/*` |
| HIP-4            | `client.hyperliquid.hip4.*` where the installed package exposes HIP-4 helpers | `#0` or outcome-side identifier | Generated REST route under `/v1/hyperliquid/hip4/*` |

Keep this map visible in wrappers and tests. A generic `getOrderbook(symbol)` helper should still name the venue family in its config or function signature.

Check the package README and installed version before copying helper names into shared code. Helper names can differ by runtime, but the route-family boundary should stay visible.

## REST Fallback

Use direct REST as a first-class path when you need the exact generated route shape or when the runtime does not use one of the listed packages.

```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"])
```

The fallback path should use the same API key, response-envelope rules, request-ID logging, and data-quality gates as SDK code.

## Response Handling

SDK callers should still understand the REST envelope. Preserve `success`, `data`, `meta.count`, `meta.next_cursor`, and `meta.request_id` where the route returns them. When the SDK unwraps `data`, expose metadata separately so retries, support workflows, and audit logs do not lose the request ID.

## Error And Metadata Handling

SDK errors should preserve enough context for support and retries.

```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.symbol, orderbook.midPrice);
} catch (error) {
  if (error instanceof OxArchiveError) {
    console.error(error.code, error.message, error.requestId);
  }
  throw error;
}
```

If the route returns metadata separately from the SDK data object, log it beside the data result. If the SDK throws a structured error, keep the status or code and request ID with the failed job.

## Pagination And History

For historical routes, design SDK loops around bounded windows and cursors. Store each request path, query parameters, cursor, and request ID with the output. Do not widen a job across many symbols until one window confirms schema, data-quality state, and rate behavior.

```typescript theme={"theme":"github-dark"}
let page = await client.hyperliquid.trades.list("BTC", {
  start: Date.now() - 86_400_000,
  end: Date.now(),
  limit: 1000
});

while (page.nextCursor) {
  page = await client.hyperliquid.trades.list("BTC", {
    start: Date.now() - 86_400_000,
    end: Date.now(),
    cursor: page.nextCursor,
    limit: 1000
  });
}
```

Pair large SDK pulls with [Data quality](/data-quality) and [Rate limits](/rate-limits). Use [Data catalog](/data-catalog) instead when the job is a large file export or warehouse load.

## Review Rule

Generated SDK examples should show where auth comes from, how errors are surfaced, and where metadata lives. If the SDK hides metadata by default, add a wrapper or logging hook so production callers can still recover request IDs.
Include one route fixture per venue family and test metadata propagation before widening a shared wrapper.