Migrate from a native venue API

Outcome

Move one historical Hyperliquid L4 snapshot workflow to 0xArchive and leave execution, account, and official venue control calls outside the migration.

Prerequisites

Identify one native workflow that reads historical market data.
Separate market-data reads from execution, account, wallet, and venue-control operations.
Choose one Hyperliquid family, symbol, timestamp, and output consumer.
Load an API key from the runtime environment and check the selected symbol’s quality state.

Inputs

Field	Bounded value
Venue family	Hyperliquid core
Symbol	`BTC`
Data family	Hyperliquid L4 order-book snapshot
Route	`/v1/hyperliquid/orderbook/BTC/l4`
Request	`timestamp=1773273600000&depth=20`
Completion condition	Snapshot is saved with checkpoint, applied-diff, route, quality, and request metadata

Steps

Mark the migration boundary

Move only the historical market-data read. Keep native execution, account state, wallet mutation, and official venue control operations in their existing authority.

Check the selected window

Check the exact family, symbol, data family, and timestamp with Data quality before replacing the old read.

Call the 0xArchive snapshot route

curl -sS "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC/l4?timestamp=1773273600000&depth=20" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Adapt only the market-data consumer

Preserve the returned checkpoint and reconstruction metadata. A continuously updated local book still applies ordered diffs after a checkpoint; a snapshot-only consumer can use the returned state directly.

Expected state

The route returns an L4 snapshot object in data with checkpoint_timestamp, diffs_applied, last_block_number, bids, and asks. Individual resting-order rows use the documented L4 fields such as oid, user_address, side, price, size, and timestamp. 0xArchive performs collection, backfill, and reconstruction server-side for the returned snapshot. That removes collection work from this migration, but it does not remove the local checkpoint, ordered-diff, gap, or reconstruction obligation for a consumer that maintains continuously updated state.

Verification

Compare one old output and one 0xArchive output for the same family, symbol, timestamp, and depth. Record the route, query, snapshot timestamp, checkpoint timestamp, number of applied diffs, and request ID. Confirm that the consumer does not treat a snapshot as a continuous stream.

Failure and recovery

No usable coverage for the timestamp: stop the migration and choose a window shown by the selected route and quality response.
401: repair the key source or header.
404: check the Hyperliquid namespace and symbol format.
A reconstruction or gap signal: discard unsafe local state, restart from the returned checkpoint, and apply ordered diffs only after the checkpoint.
A mismatch with the old consumer: keep the old market-data path for comparison, inspect the exact route schema, and do not move execution or account calls into this workflow.

Saved run metadata

{
  "migration": "hyperliquid-core-l4-snapshot-001",
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "data_family": "l4_orderbook",
  "route": "/v1/hyperliquid/orderbook/BTC/l4",
  "query": {
    "timestamp": 1773273600000,
    "depth": 20
  },
  "quality_source": "record the selected data-quality response",
  "request_ids": ["00000000-0000-0000-0000-000000000000"],
  "checkpoint_timestamp": "record the response value",
  "diffs_applied": "record the response value",
  "native_scope_boundary": ["execution", "account", "wallet", "official venue control"],
  "output": "./artifacts/btc-l4-snapshot-001.json"
}

The zero UUID is a shape placeholder only. Replace it with the UUID returned by the route or client wrapper. Keep the native scope boundary as a boundary, not as a second market-data implementation path.

Next task

Use Historical market data for bounded rows, WebSocket replay for ordered events, or SDK reconstruction when the consumer must maintain local state after a checkpoint.

​Outcome

​Prerequisites

​Inputs

​Steps

​Expected state

​Verification

​Failure and recovery

​Saved run metadata

​Next task