Repository navigation
API contract 2026-10-01: version header, error codes, hasMore, capabilities - #23
Merged
Merged
Conversation
…lities Every REST request sends 0xArchive-Version: 2026-10-01 and the WebSocket client connects with version=2026-10-01. The SDK parses that version's shapes: the standard envelope on data quality and /v1/symbols, RFC 3339 record times with integer *Ms fields, and the live payload shapes on Lighter and Robinhood Chain replay. - OxArchiveError exposes errorCode, status, requestId, param, validValues and the error body; ERROR_CODES and the ErrorCode union list the codes. WebSocket error messages carry errorCode, with ws.onServerError(). - Paged methods return hasMore and meta (including meta.symbol and meta.venue); the positions iterators stop when hasMore is false. - client.capabilities() returns typed /v1/capabilities rows. - trades side (buy or sell) on history and recent, on every venue; triggered on order history; depth on full-depth L2 history. - WebSocket replay of HIP-3, HIP-4 and Spot L4 and of the full-depth channels, checked against WS_CHANNEL_CAPABILITIES, one table that mirrors /v1/capabilities. - trades.history() and spot.twap.history() beside the existing names. - The venue is named Lighter in the README and doc comments.
Contributor
|
Target date: no date → 2026-10-08 Date status: Proposed. This is a proposed delivery target; owner confirmation is still required. Why: K requested a Target date on every active tracked item. This copies the already recorded planning/review date; it does not create owner agreement or change scope, status, priority, ownership, implementation/deployment/sending permission, or any release hold. |
The client used the global WebSocket, which Node.js 18 and 20 do not have, so connect() failed there with "WebSocket is not defined". In Node.js 24.15 the built-in WebSocket closes the connection (1006) when a compressed message decompresses to more than about 4 MB, which a BTC L4 snapshot does. In Node.js the client now connects with the ws package, already a dependency of the SDK, on every version; the built-in WebSocket is the fallback when ws cannot be loaded. Browsers keep the built-in WebSocket, and a WebSocket the caller assigns to globalThis is used as is. A replay sent before connect() resolved was dropped without an error. Requests made while the client is connecting or reconnecting are now queued and sent once the socket opens, and discarded if the first connect fails. While the client is disconnected they throw an error that says to call and await connect(); replayStop() and streamStop() do nothing then, since nothing is running. Subscriptions behave as before: they are kept and sent on every connect. - Tests cover the queue, the refusal, a reconnect, a real ws server with no global WebSocket, and a 9 MB compressed message.
WS_CHANNEL_CAPABILITIES marked hip4_orderbook, hip4_open_interest and spot_twap as live. /v1/capabilities says the two HIP-4 channels replay only and spot_twap neither streams nor replays: the API accepts a subscription to each but sends nothing on it. - hip4_orderbook and hip4_open_interest are replay only. A live subscription, including through subscribeHip4(), throws before sending; read the current book and open interest over REST. - spot_twap is REST only (client.spot.twap). Live and replay requests throw restOnlyError(); the channel name stays so existing code compiles. WsLiveOnlyChannel no longer lists it, and the new WsRestOnlyChannel does. - The unit table matches the capabilities rows of 2026-10-04, and the live check compares every channel's venue, datatype and modes with the endpoint, including channels that no row lists.
- package.json exports give each condition its own declarations: import resolves index.d.mts and index.mjs, require index.d.ts and index.js. ES module projects using node16 or nodenext resolution failed to type-check `import OxArchive from '@0xarchive/sdk'`, because the declarations were read as CommonJS. The JavaScript entry points are unchanged. repository.url uses the git+https form. - The README coverage table gives each dataset's first served instant from /v1/capabilities instead of month-level dates; Robinhood Chain candles are served from 2026-06-26 20:10 UTC; HIP-3 L4 and order history from 2026-03-11 01:03 UTC; Spot TWAP is REST only. - Market counts for Spot and Robinhood Chain are no longer pinned; the listing calls return the current set. - Examples use windows relative to now, so they run on a Free key's 30-day window. HIP-4 examples look up an open outcome first, HIP-3 examples use markets that are trading, and every replay example awaits connect(). - The Hyperliquid core trades note no longer describes how trades are collected; doc comments drop pipeline wording and em dashes. - README and CHANGELOG 1.12.0 record these changes, the ws package in Node.js, the request queue, the channel table and the trade side values the API accepts; the CHANGELOG states plain semantic versioning.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adopts the 0xArchive API contract
2026-10-01. Folded into the unreleased 1.12.0; the version is unchanged.Version selector
0xArchive-Version: 2026-10-01(including the raw web3 subscribe requests);OxArchiveWsconnects withversion=2026-10-01. Exported asAPI_VERSIONandAPI_VERSION_HEADER.client.symbols.list()read the standard{ success, data, meta }envelope.*Msfield: CVD buckets, HIP-3 oracle reads, Lighter and Robinhood Chain liquidations and liquidation volume, L4 snapshot resting orders (timestamp/timestampMs), andsnapshotTs/snapshotTsMson liquidation levels and trigger-levels history.OrderBookforonHistoricalTickData().Errors
OxArchiveErrorexposeserrorCode,status,requestId,param,validValuesand the errorbody.ERROR_CODES, theErrorCodeunion,WEBSOCKET_ONLY_ERROR_CODESandisErrorCode()are exported. A non-JSON error body keeps its HTTP status.errorCode(for exampleslow_consumer,endpoint_unsupported);ws.onServerError()receives them.Pagination and meta
hasMore(frommeta.hasMore) withnextCursor, andmetaincludingmeta.symbolandmeta.venue. The positions iterators stop whenhasMoreis false.Capabilities
client.capabilities()returns typedGET /v1/capabilitiesrows.WS_CHANNEL_CAPABILITIESis one table of every WebSocket channel (venue, datatype, live, replay, bulk replay) mirroring the endpoint; the live and replay checks read it.Parameters
side: 'buy' | 'sell'on trade history andtrades.recent()on every venue.triggeredon order history (Hyperliquid core, HIP-3, HIP-4).depthon full-depth L2 history; order book historydepthdocumented for every venue.WebSocket replay
orderbook_full,hip3_orderbook_full) are no longer refused: bulk, single-channel, explicitend,speedignored. Replay is still refused forticker,all_tickers,spot_orderbook,spot_tradesandspot_twap, and live subscription for the replay-only candle and L3 channels.Verbs
trades.history()besidetrades.list(), andspot.twap.history()besidespot.twap.bySymbol(). No names were removed.Docs
/v1/capabilities; the venue is named Lighter. CHANGELOG 1.12.0 updated.Testing
npm run build,npx tsc --noEmit -p .,npx eslint src/(0 errors), the package-contents check, andnpx vitest run: 364 passed, 9 skipped.tests/api-contract.test.tscovers each item with mocked fetch and a fake socket.tests/live-contract.test.tsruns read-only checks against the live API whenOXA_API_KEYis set (skipped otherwise): 9 passed.