Skip to content

Add OiFundingInterval::OneMinute, and a cursor for order flow - #13

Merged
0xFantomMenace merged 3 commits into
mainfrom
docs/cvd-cursor-1m
Sep 27, 2026
Merged

0xFantomMenace merged 3 commits into
mainfrom
docs/cvd-cursor-1m

Conversation

@0xFantomMenace

@0xFantomMenace 0xFantomMenace commented Sep 27, 2026 •

Copy link
Copy Markdown
Member

The 0xArchive API now serves 1-minute buckets (interval=1m) on funding, open interest, price, liquidation-volume and breadth history, on every venue. Order flow now honors its bucket parameter, with 1m (default), 5m, 15m and 1h, and reads a sent cursor.

In this crate, funding, open interest and HIP-3 breadth history type interval as OiFundingInterval, which had no 1-minute variant. Liquidation volume, prices and order flow take a String and already pass "1m" through. OrderFlowParams and Hip4OrderFlowParams had no cursor.

The API does not return next_cursor on order flow yet. That arrives with an API switch, after SDK releases that forward the cursor are published. So this PR adds cursor but does not document paging by next_cursor; the paging docs are in draft #14, held until the switch is on.

Changes

  • OiFundingInterval::OneMinute ("1m").
  • Breadth history rustdoc lists 1m.
  • OrderFlowParams::interval and Hip4OrderFlowParams::interval document the buckets the API serves.
  • cursor: Option<String> on OrderFlowParams and Hip4OrderFlowParams, sent by orders.flow() (core and HIP-3) and hip4.get_order_flow(): a resume point in Unix milliseconds, and the response starts at the first bucket that opens after it. The field and method docs say start is inclusive, end exclusive, limit is the maximum number of buckets (default 1000, max 10000), a response holds the oldest limit buckets, and buckets are labelled by open time in UTC. The README order-flow example is a single request.
  • Tests: every OiFundingInterval variant maps to its wire value; OneMinute is sent as interval=1m by funding, open interest and HIP-3 breadth history (wiremock, one expected hit per route).
  • Test (wiremock): the order-flow cursor is sent on core, HIP-3 and HIP-4, the first request carries none, and a next_cursor in the response is surfaced. It fails when the cursor is not sent.
  • CHANGELOG: an Unreleased entry, including that order-flow next_cursor arrives with an API switch.

Semver note

OiFundingInterval is not #[non_exhaustive], so downstream code that matches it without a wildcard arm will need a OneMinute arm. The order-flow param structs gain a public field, so a struct literal that lists every field needs cursor: None (or ..Default::default()). The changelog says both; pick the version bump accordingly at release.

Test plan

  • cargo test --all-targets: pass (coverage_contract 16 of 16, including the 3 new tests). cargo test --doc: 8 passed.
  • cargo fmt --check reports no diffs in the lines this PR changes. The crate has existing rustfmt drift elsewhere, left alone here.
  • Checked against the live API: interval=1m and 15m on order flow return 1-minute and 15-minute buckets, a sent cursor starts the response after it, and the response carries no next_cursor.

The API now serves 1-minute buckets on funding, open interest and HIP-3
breadth history, the three params typed with OiFundingInterval, but the
enum had no variant for them.

- OiFundingInterval::OneMinute maps to "1m". The enum is not
  non_exhaustive, so a match without a wildcard arm needs the new arm;
  the changelog says so.
- The breadth history doc lists 1m.
- OrderFlowParams::interval and Hip4OrderFlowParams::interval document
  the buckets the API serves: "1m" (the default), "5m", "15m" and "1h".
- Tests: every variant maps to its wire value, and OneMinute is sent as
  interval=1m by funding, open interest and HIP-3 breadth history.
The API now pages order flow on Hyperliquid, HIP-3 and HIP-4: a page
holds the oldest `limit` buckets of the window, and `next_cursor` is set
while more may follow. `OrderFlowParams` and `Hip4OrderFlowParams` had no
`cursor`, so a caller could never get past the first page.

- `cursor: Option<String>` on both structs, sent by `orders.flow()` and
  `hip4.get_order_flow()`. Requests without it are unchanged.
- Field and method docs: start inclusive, end exclusive, limit counts
  buckets (default 1000, max 10000), buckets are labelled by open time in
  UTC, and how to follow `next_cursor`.
- The README order-flow example pages a day at 1m.
- New test (wiremock): the cursor is sent on core, HIP-3 and HIP-4, the
  first page carries none, and `next_cursor` comes back. It fails when
  the cursor is not sent.
- CHANGELOG: both structs are built with struct literals, so a literal
  that lists every field needs `cursor: None` (or
  `..Default::default()`).
@0xFantomMenace 0xFantomMenace changed the title Add OiFundingInterval::OneMinute for 1-minute aggregation Add OiFundingInterval::OneMinute, and a cursor for order flow Sep 27, 2026
The API reads a sent order-flow cursor, but it does not return
next_cursor on order flow yet. That arrives with an API switch. Until
then the docs must not tell callers to page by it.

- `cursor` stays on `OrderFlowParams` and `Hip4OrderFlowParams`. Its
  doc describes a resume point (a Unix millisecond timestamp); `limit`
  is the maximum number of buckets. The struct and method docs no
  longer say how to follow next_cursor.
- The README order-flow example is a single request again.
- CHANGELOG: order-flow next_cursor arrives with an API switch.
@0xFantomMenace
0xFantomMenace merged commit a9955db into main Sep 27, 2026
1 check passed
@0xFantomMenace
0xFantomMenace deleted the docs/cvd-cursor-1m branch September 29, 2026 00:06
0xFantomMenace added a commit that referenced this pull request Sep 29, 2026
Add OiFundingInterval::OneMinute, and a cursor for order flow
0xFantomMenace added a commit that referenced this pull request Sep 29, 2026
Add OiFundingInterval::OneMinute, and a cursor for order flow
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant