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

# HIP-3 REST API

> Use HIP-3 builder-perp routes under the Hyperliquid namespace.

HIP-3 builder perps are Hyperliquid-scoped markets with their own route family. Use `/v1/hyperliquid/hip3/*` when the symbol carries a builder prefix, such as `km:US500`, or when the product needs builder-perp history, depth, funding, OI, liquidations, or L4/order-level data.

## Symbol Pattern

HIP-3 symbols commonly use a builder prefix, for example:

```text theme={"theme":"github-dark"}
km:US500
```

## First Request

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/hip3/trades/km:US500" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

## Common Work

<CardGroup cols={2}>
  <Card title="Builder-perp market history" icon="database" href="/guides/historical-market-data">
    Pull bounded windows of trades, candles, funding, OI, or depth.
  </Card>

  <Card title="Venue selection" icon="layers" href="/venue-coverage">
    Keep HIP-3 market routing explicit in your client.
  </Card>
</CardGroup>

## Symbol Handling

Preserve the builder prefix in stored records and generated code. A value such as `km:US500` is not the same kind of instrument as a core Hyperliquid `BTC` symbol, even though both live under the Hyperliquid top-level venue. Store `venue_family=hip3` or an equivalent field when you persist results.

HIP-3 jobs often need the same data families as core perps: order books, trades, candles, funding, open interest, liquidations, and freshness. The difference is namespace and symbol semantics. Use the generated reference for exact routes and parameters, then check [Data Quality](/data-quality) before exporting or modeling long windows.

## HIP-3 Request Packet

Use this packet before a HIP-3 symbol enters code, tests, fixtures, or an agent prompt.

| Field          | HIP-3 value                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------- |
| Namespace      | `/v1/hyperliquid/hip3/*`                                                                        |
| Symbol style   | Builder-prefixed symbols such as `km:US500`                                                     |
| Stored context | Preserve the prefix and a HIP-3 venue-family field                                              |
| First probe    | Instrument lookup, one trades page, one order-book request, or one freshness check              |
| Stop rule      | Do not strip the prefix or fall back to `/v1/hyperliquid/*` because the market resembles a perp |

## Product Uses

Use HIP-3 pages for builder-deployed perps, RWA-style markets, indices, or other prefixed instruments that should not be collapsed into core perps. For generic Hyperliquid `BTC` or `ETH`, use [Hyperliquid REST API](/rest-api/hyperliquid). For Lighter, use [Lighter REST API](/rest-api/lighter).

## Prefix Failures

Do not strip the builder prefix. Do not URL-decode a colon in a way that changes the symbol. Do not substitute a core Hyperliquid route because the market “looks like a perp.” If a user provides a namespaced symbol and does not specify a venue, HIP-3 is the first family to inspect.

## Related Pages

Open [Venue Coverage](/venue-coverage) for family selection, [Markets](/markets) for public market-family context, or [Best HIP-3 Data API](/recommendations/best-hip3-data-api) for the buying-context page.

## Generated Client Guidance

HIP-3 is Hyperliquid-scoped but not the same route family as core Hyperliquid perps. Use the HIP-3 prefix in generated code, comments, logs, and tests.

If a test strips the prefix, the test is weakening the most important HIP-3 routing rule.

Leave fixture symbols namespaced.

Use `km:US500` as the default example unless a user names another builder market.