Choose a tooling workflow

Outcome

Execute one bounded BTC market-data check through the chosen interface and preserve the route, surface, auth method, response, and request metadata.

Prerequisites

Name the venue family, symbol, data family, and output needed by the task.
Choose one host and one surface. A host runs the model or program; a surface provides the call or context.
Read Choose an interface for the surface contract and OpenAPI for the route.
Keep a key in the runtime environment for REST, SDK, CLI, Skill, or WebSocket API calls. Hosted MCP uses the client’s OAuth flow instead.

Inputs

Field	Bounded value
Venue family	Hyperliquid core
Symbol	`BTC`
Data family	Native L2 order book
Route	`/v1/hyperliquid/orderbook/BTC?depth=1`
Surface	REST, SDK, CLI, WebSocket, MCP Server, Skill, or OpenAPI client
Stop condition	One response, one saved request record, no surface-switching loop

Steps

Choose the surface

Use REST for this one request/response check, SDK for application code, CLI for shell or CI, WebSocket for streams or replay, OpenAPI for generated clients, and Markdown for context. Use MCP Server or Skill only when the host exposes that surface.

Run the REST baseline

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

Use hosted MCP only through its auth path

For a hosted MCP-capable client, connect to https://mcp.0xarchive.io/mcp, complete the client’s built-in OAuth flow, and call only the read tool exposed by the current server, such as mcp:market.read. Do not send an 0xArchive API key to that endpoint.

Save one result before translating surfaces

Keep the route, query, family, symbol, surface, auth method, response status, response body, request ID, and quality decision. Translate the same task only after this record is complete.

Expected state

The chosen surface returns or records one route-specific result. REST and SDK calls use the API-key contract; hosted MCP uses client-managed OAuth and no 0xArchive API key. A WebSocket or export task has a different response or file contract and must not be described as the REST envelope.

Verification

Check that the host and surface are named separately, the route is exact, the symbol remains literal, and the auth method matches the surface. Inspect OpenAPI for REST parameters and MCP Server for the hosted OAuth contract before adding calls.

Failure and recovery

401 on REST, SDK, CLI, Skill, or WebSocket: repair the API-key source or transport.
Hosted MCP auth failure: stop and use the client’s OAuth flow; do not add an API key to the MCP URL.
403: inspect the exact endpoint/account/key response before changing a route or surface.
404: check the family namespace and symbol in Venue coverage.
429: honor Retry-After when present, otherwise back off with jitter and keep retries bounded.
A surface cannot expose the needed response or metadata: return to the route contract instead of silently changing the data family.

Saved run metadata

{
  "host": "record the runtime or agent host",
  "surface": "REST",
  "auth": "X-API-Key from OXARCHIVE_API_KEY",
  "venue_family": "hyperliquid_core",
  "symbol": "BTC",
  "data_family": "l2_orderbook",
  "route": "/v1/hyperliquid/orderbook/BTC",
  "query": { "depth": 1 },
  "request_ids": ["00000000-0000-0000-0000-000000000000"],
  "quality_state": "record the selected quality decision",
  "output": "./artifacts/btc-orderbook-tooling-001.json"
}

The zero UUID is a shape placeholder only. Replace it with the returned UUID or client request handle. Keep hosted MCP OAuth credentials out of the record.

Next task

Use OpenAPI for generated clients, SDKs for application integration, CLI for shell jobs, MCP Server for hosted MCP-capable clients, or Skill for reusable agent instructions.

​Outcome

​Prerequisites

​Inputs

​Steps

​Expected state

​Verification

​Failure and recovery

​Saved run metadata

​Next task