From 726fc056a52041e59bbe3b46c9bc8ec9433a413d Mon Sep 17 00:00:00 2001 From: Abdul Manan Date: Fri, 21 Aug 2026 17:18:01 -0400 Subject: [PATCH 1/2] docs: expand HyperCore private-preview REST reference and add peering and market deployment pages --- .../timestamps-cursors-and-replay.mdx | 2 +- .../data/hypercore/getting-started.mdx | 3 +- .../guides/rebuild-a-book-from-diffs.mdx | 15 +- .../hypercore/guides/stream-l2-order-book.mdx | 15 +- .../data/hypercore/networks-and-endpoints.mdx | 2 +- .../spot-clearinghouse-state.mdx | 53 +++ .../rest/account-state/sub-accounts.mdx | 64 +++ .../account-state/user-dex-abstraction.mdx | 51 +++ .../rest/asset-context/active-asset-data.mdx | 75 ++++ .../asset-context/meta-and-asset-ctxs.mdx | 114 +++++ .../rest/asset-context/predicted-fundings.mdx | 53 +++ .../spot-meta-and-asset-ctxs.mdx | 64 +++ .../rest/ledger-and-funding/user-funding.mdx | 90 ++++ .../user-non-funding-ledger-updates.mdx | 52 +++ .../market-data-and-snapshots/all-mids.mdx | 39 ++ .../candle-snapshot.mdx | 70 +++ .../l4-snapshots.mdx | 75 ++++ .../trigger-order-snapshot.mdx | 35 ++ .../data/hypercore/rest/metadata/meta.mdx | 62 +++ .../hypercore/rest/metadata/spot-meta.mdx | 65 +++ .../orders-and-fills/frontend-open-orders.mdx | 69 +++ .../rest/orders-and-fills/open-orders.mdx | 55 +++ .../rest/outcome-markets/outcome-meta.mdx | 56 +++ .../outcome-markets/outcome-templates.mdx | 51 +++ .../rest/outcome-markets/settled-outcome.mdx | 56 +++ .../data/hypercore/rest/overview.mdx | 51 ++- .../max-builder-fee.mdx | 40 ++ .../roles-agents-and-limits/user-fees.mdx | 94 +++++ .../user-rate-limit.mdx | 46 ++ .../roles-agents-and-limits/user-role.mdx | 81 ++++ .../delegations.mdx | 47 +++ .../delegator-history.mdx | 57 +++ .../delegator-rewards.mdx | 52 +++ .../delegator-summary.mdx | 46 ++ .../validator-l1-votes.mdx | 39 ++ .../perp-deploy-auction-status.mdx | 46 ++ .../token-deployment/spot-deploy-state.mdx | 73 ++++ .../spot-pair-deploy-auction-status.mdx | 46 ++ .../hypercore/rest/vaults/leading-vaults.mdx | 41 ++ .../rest/vaults/user-vault-equities.mdx | 45 ++ .../hypercore/rest/vaults/vault-details.mdx | 92 ++++ .../hypercore/rest/vaults/vault-summaries.mdx | 39 ++ .../deploying-markets/overview.mdx | 59 +++ .../hypercore-grpc/stream-bbo-book.mdx | 2 - .../hypercore-grpc/stream-blocks.mdx | 2 - .../hypercore-grpc/stream-l2-book-diff.mdx | 8 +- .../hypercore-grpc/stream-l2-book.mdx | 2 - .../hypercore-grpc/stream-l4-book-updates.mdx | 8 +- .../hypercore-grpc/stream-l4-book.mdx | 4 +- .../hypercore-grpc/stream-tpsl-updates.mdx | 8 +- .../hypercore-peering/overview.mdx | 192 +++++++++ .../hypercore/active-asset-context.mdx | 12 +- .../websockets/hypercore/all-candles.mdx | 33 +- .../websockets/hypercore/all-fills.mdx | 75 +++- .../hypercore/all-isolated-margin-updates.mdx | 52 ++- .../hypercore/all-leverage-updates.mdx | 54 ++- .../hypercore/all-twap-status-updates.mdx | 61 ++- .../websockets/hypercore/builder-fills.mdx | 77 +++- .../hypercore/builder-liquidation.mdx | 101 ++++- .../hypercore/builder-order-updates.mdx | 84 ++-- .../websockets/hypercore/candles.mdx | 18 +- .../websockets/hypercore/funding-rates.mdx | 27 +- .../websockets/hypercore/l2-book-diff.mdx | 112 +++-- .../websockets/hypercore/l4-book-updates.mdx | 103 +++-- .../hypercore/liquidation-fills.mdx | 81 +++- .../hypercore/set-oracle-updates.mdx | 41 +- .../websockets/hypercore/tpsl-updates.mdx | 115 +++-- .../websockets/hypercore/trades.mdx | 72 ++++ .../websockets/hypercore/user-fills.mdx | 75 +++- .../user-isolated-margin-updates.mdx | 58 ++- .../hypercore/user-leverage-updates.mdx | 60 ++- .../hypercore/user-order-updates.mdx | 86 ++-- content/docs.yml | 108 +++++ src/openapi/hypercore/hypercore.yaml | 399 ++++++++++++++++-- 74 files changed, 3952 insertions(+), 458 deletions(-) create mode 100644 content/api-reference/data/hypercore/rest/account-state/spot-clearinghouse-state.mdx create mode 100644 content/api-reference/data/hypercore/rest/account-state/sub-accounts.mdx create mode 100644 content/api-reference/data/hypercore/rest/account-state/user-dex-abstraction.mdx create mode 100644 content/api-reference/data/hypercore/rest/asset-context/active-asset-data.mdx create mode 100644 content/api-reference/data/hypercore/rest/asset-context/meta-and-asset-ctxs.mdx create mode 100644 content/api-reference/data/hypercore/rest/asset-context/predicted-fundings.mdx create mode 100644 content/api-reference/data/hypercore/rest/asset-context/spot-meta-and-asset-ctxs.mdx create mode 100644 content/api-reference/data/hypercore/rest/ledger-and-funding/user-funding.mdx create mode 100644 content/api-reference/data/hypercore/rest/ledger-and-funding/user-non-funding-ledger-updates.mdx create mode 100644 content/api-reference/data/hypercore/rest/market-data-and-snapshots/all-mids.mdx create mode 100644 content/api-reference/data/hypercore/rest/market-data-and-snapshots/candle-snapshot.mdx create mode 100644 content/api-reference/data/hypercore/rest/market-data-and-snapshots/l4-snapshots.mdx create mode 100644 content/api-reference/data/hypercore/rest/market-data-and-snapshots/trigger-order-snapshot.mdx create mode 100644 content/api-reference/data/hypercore/rest/metadata/meta.mdx create mode 100644 content/api-reference/data/hypercore/rest/metadata/spot-meta.mdx create mode 100644 content/api-reference/data/hypercore/rest/orders-and-fills/frontend-open-orders.mdx create mode 100644 content/api-reference/data/hypercore/rest/orders-and-fills/open-orders.mdx create mode 100644 content/api-reference/data/hypercore/rest/outcome-markets/outcome-meta.mdx create mode 100644 content/api-reference/data/hypercore/rest/outcome-markets/outcome-templates.mdx create mode 100644 content/api-reference/data/hypercore/rest/outcome-markets/settled-outcome.mdx create mode 100644 content/api-reference/data/hypercore/rest/roles-agents-and-limits/max-builder-fee.mdx create mode 100644 content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-fees.mdx create mode 100644 content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-rate-limit.mdx create mode 100644 content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-role.mdx create mode 100644 content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegations.mdx create mode 100644 content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-history.mdx create mode 100644 content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-rewards.mdx create mode 100644 content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-summary.mdx create mode 100644 content/api-reference/data/hypercore/rest/staking-delegation-and-validators/validator-l1-votes.mdx create mode 100644 content/api-reference/data/hypercore/rest/token-deployment/perp-deploy-auction-status.mdx create mode 100644 content/api-reference/data/hypercore/rest/token-deployment/spot-deploy-state.mdx create mode 100644 content/api-reference/data/hypercore/rest/token-deployment/spot-pair-deploy-auction-status.mdx create mode 100644 content/api-reference/data/hypercore/rest/vaults/leading-vaults.mdx create mode 100644 content/api-reference/data/hypercore/rest/vaults/user-vault-equities.mdx create mode 100644 content/api-reference/data/hypercore/rest/vaults/vault-details.mdx create mode 100644 content/api-reference/data/hypercore/rest/vaults/vault-summaries.mdx create mode 100644 content/api-reference/deploying-markets/overview.mdx create mode 100644 content/api-reference/hypercore-peering/overview.mdx create mode 100644 content/api-reference/websockets/hypercore/trades.mdx diff --git a/content/api-reference/data/hypercore/concepts/timestamps-cursors-and-replay.mdx b/content/api-reference/data/hypercore/concepts/timestamps-cursors-and-replay.mdx index 87b1438de..fa9278873 100644 --- a/content/api-reference/data/hypercore/concepts/timestamps-cursors-and-replay.mdx +++ b/content/api-reference/data/hypercore/concepts/timestamps-cursors-and-replay.mdx @@ -29,7 +29,7 @@ The stateful market-data streams use two recovery models. This taxonomy does not **Incremental streams** — `l2BookDiff`, `l4BookUpdates`, and `tpslUpdates`. Messages carry changes that chain onto previous state. These carry a cursor and support replay. -> A message with `isSnapshot: true` replaces your local state. Any message without it is a diff that must chain onto your previous state. If continuity is broken, a fresh message with `isSnapshot: true` is pushed to you — there is no separate resynchronization message and no epoch to track. +> A message with `isSnapshot: true` replaces your local state. Any message without it is a diff that must chain onto your previous state. If continuity is broken, a fresh message with `isSnapshot: true` is pushed to you. `isSnapshot` is the only continuity signal you need to handle — receiving it means discard local state and adopt the supplied snapshot. ## Detecting gaps diff --git a/content/api-reference/data/hypercore/getting-started.mdx b/content/api-reference/data/hypercore/getting-started.mdx index c596d413e..42cd55f3c 100644 --- a/content/api-reference/data/hypercore/getting-started.mdx +++ b/content/api-reference/data/hypercore/getting-started.mdx @@ -11,7 +11,8 @@ description: "HyperCore private-preview documentation." Review the [WebSocket streaming documentation](/docs/chains/websockets/hypercore) for the intended subscription envelope. -For REST reads, use the provisional base URL `https://api.g.alchemy.com/hypercore/v1`. Each REST operation includes its API key in the `{apiKey}` path segment. The base URL will be confirmed before general availability. +For REST reads, see the [REST API overview](/docs/data/hypercore/rest-api). Each REST +operation includes its API key in the `{apiKey}` path segment. ## Next steps Review the WebSocket lifecycle, replay, and wallet-fill guide before integrating. diff --git a/content/api-reference/data/hypercore/guides/rebuild-a-book-from-diffs.mdx b/content/api-reference/data/hypercore/guides/rebuild-a-book-from-diffs.mdx index 49847d820..5589422af 100644 --- a/content/api-reference/data/hypercore/guides/rebuild-a-book-from-diffs.mdx +++ b/content/api-reference/data/hypercore/guides/rebuild-a-book-from-diffs.mdx @@ -7,7 +7,20 @@ description: "HyperCore private-preview documentation." # Rebuild a book from diffs -Start from a durable L2 snapshot. Apply ordered diffs one cursor at a time. On a cursor discontinuity, discard local state, fetch a new snapshot or historical cursor, then resume. +Subscribe to `l2BookDiff`. The first message for each market is the current book +snapshot with `isSnapshot: true`; install it as local state. Apply later diffs in +height order. The first diff for each market must carry `prev_seq` equal to that +market's snapshot `seq`; continue checking `prev_seq` against your local position on +every diff. + +On a continuity break, discard local state for the affected markets and adopt the +pushed message with `isSnapshot: true`; bootstrap and recovery use the same +replacement mechanism. + +For a snapshot shared by many consumers, or to let a slow client digest a large book +while buffering live updates, use [the REST snapshot read](/docs/data/hypercore/rest-api) +instead. ## Cursor rule + Advance a durable cursor only after downstream storage succeeds. Treat a gap, correction, or finality change as a reason to backfill and reconcile. diff --git a/content/api-reference/data/hypercore/guides/stream-l2-order-book.mdx b/content/api-reference/data/hypercore/guides/stream-l2-order-book.mdx index 16d42d67a..8c7f2b1d0 100644 --- a/content/api-reference/data/hypercore/guides/stream-l2-order-book.mdx +++ b/content/api-reference/data/hypercore/guides/stream-l2-order-book.mdx @@ -7,7 +7,20 @@ description: "HyperCore private-preview documentation." # Stream an L2 order book -Subscribe to `l2Book` for the market, wait for the initial snapshot, store its cursor, and render price levels. Use `l2BookDiff` only after the snapshot is installed. +To maintain an L2 book from `l2BookDiff`, install the first message for each market +as local state. It carries the current levels with `isSnapshot: true`. Apply later +diffs in height order, checking each market's `prev_seq` against the snapshot `seq` +and then against your local position. + +`l2Book` is a standalone display snapshot, not a bootstrap source for a +diff-maintained book. If continuity breaks, discard affected local state and adopt +the pushed `isSnapshot: true` message; bootstrap and recovery use the same +replacement mechanism. + +For a snapshot shared by many consumers, or to let a slow client digest a large book +while buffering live updates, use [the REST snapshot read](/docs/data/hypercore/rest-api) +instead. ## Cursor rule + Advance a durable cursor only after downstream storage succeeds. Treat a gap, correction, or finality change as a reason to backfill and reconcile. diff --git a/content/api-reference/data/hypercore/networks-and-endpoints.mdx b/content/api-reference/data/hypercore/networks-and-endpoints.mdx index 2a2cff432..50dc2d493 100644 --- a/content/api-reference/data/hypercore/networks-and-endpoints.mdx +++ b/content/api-reference/data/hypercore/networks-and-endpoints.mdx @@ -7,6 +7,6 @@ description: "HyperCore private-preview documentation." # HyperCore Data API networks and endpoints -HyperCore will support Hyperliquid mainnet and testnet. The REST base URL is provisionally `https://api.g.alchemy.com/hypercore/v1`; it will be confirmed before general availability. +HyperCore supports Hyperliquid mainnet and testnet. See the [REST API overview](/docs/data/hypercore/rest-api) for the current `/info` host handling. For chain-level documentation, see [Chain API networks and endpoints](/docs/chains/hyperliquid/hypercore/networks-and-endpoints). diff --git a/content/api-reference/data/hypercore/rest/account-state/spot-clearinghouse-state.mdx b/content/api-reference/data/hypercore/rest/account-state/spot-clearinghouse-state.mdx new file mode 100644 index 000000000..a07c94821 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/account-state/spot-clearinghouse-state.mdx @@ -0,0 +1,53 @@ +--- +title: "Spot clearinghouse state" +description: "HyperCore private-preview documentation." +--- + + + +# Spot clearinghouse state + +Returns a user's spot balances for account-state and balance checks. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | --------------------------------- | +| `type` | string | Yes | Selects `spotClearinghouseState`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "spotClearinghouseState", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| --------------------- | ------- | ----------------------------------------------------------- | +| `balances[]` | array | Balance entries. | +| `balances[].coin` | string | Spot-token symbol, for example `USDC`. | +| `balances[].token` | integer | Numeric token index from the spot metadata response. | +| `balances[].hold` | string | Amount reserved by orders. | +| `balances[].total` | string | Combined balance held by the account, as a decimal string. | +| `balances[].entryNtl` | string | Entry notional for this token balance, as a decimal string. | + +## Response example + +```json +{ + "balances": [ + { + "coin": "USDC", + "token": 0, + "hold": "0.0", + "total": "14.625485", + "entryNtl": "0.0" + } + ] +} +``` diff --git a/content/api-reference/data/hypercore/rest/account-state/sub-accounts.mdx b/content/api-reference/data/hypercore/rest/account-state/sub-accounts.mdx new file mode 100644 index 000000000..ecce3225f --- /dev/null +++ b/content/api-reference/data/hypercore/rest/account-state/sub-accounts.mdx @@ -0,0 +1,64 @@ +--- +title: "Subaccounts" +description: "HyperCore private-preview documentation." +--- + + + +# Subaccounts + +Returns a master's named sub-accounts with their perpetual and spot account state. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `subAccounts`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "subAccounts", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| -------------------------------------- | ------------- | --------------------------------------------------------------------------------- | +| `[]` | array \| null | Sub-account entries; the native API can return `null` when no state is available. | +| `[].name` | string | Display name assigned to the sub-account. | +| `[].subAccountUser` | string | Address of the sub-account. | +| `[].master` | string | Address that controls this sub-account. | +| `[].clearinghouseState` | object | Perpetual account state for the sub-account. | +| `[].clearinghouseState.marginSummary` | object | Cross-margin collateral, notional, and margin metrics. | +| `[].clearinghouseState.withdrawable` | string | USDC withdrawable while retaining the current perpetual positions. | +| `[].clearinghouseState.assetPositions` | array | Open perpetual positions with their position state. | +| `[].clearinghouseState.time` | integer | Millisecond timestamp of the included perpetual-account state. | +| `[].spotState.balances[]` | array | Spot balances held by the sub-account. | +| `[].spotState.balances[].coin` | string | Spot-token symbol, for example `USDC`. | +| `[].spotState.balances[].total` | string | Combined balance for that spot token, as a decimal string. | +| `[].spotState.balances[].hold` | string | Amount reserved by orders. | + +## Response example + +```json +[ + { + "name": "Test", + "subAccountUser": "0x035605fc2f24d65300227189025e90a0d947f16c", + "master": "0x8c967e73e6b15087c42a10d344cff4c96d877f1d", + "clearinghouseState": { + "withdrawable": "29.78001", + "assetPositions": [], + "time": 1733968369395 + }, + "spotState": { + "balances": [{ "coin": "USDC", "total": "0.22", "hold": "0.0" }] + } + } +] +``` diff --git a/content/api-reference/data/hypercore/rest/account-state/user-dex-abstraction.mdx b/content/api-reference/data/hypercore/rest/account-state/user-dex-abstraction.mdx new file mode 100644 index 000000000..3d65b3f68 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/account-state/user-dex-abstraction.mdx @@ -0,0 +1,51 @@ +--- +title: "DEX abstraction state" +description: "HyperCore private-preview documentation." +--- + + + +# DEX abstraction state + +Returns whether a user has enabled HIP-3 DEX abstraction. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `userDexAbstraction`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "userDexAbstraction", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ---------- | --------------- | ---------------------------------------------------------------------------------------------------- | +| `Response` | boolean \| null | `true` when DEX abstraction is enabled; the native API can return `null` when no state is available. | + +## Response example + + + + +```json +true +``` + + + + +```json +null +``` + + + diff --git a/content/api-reference/data/hypercore/rest/asset-context/active-asset-data.mdx b/content/api-reference/data/hypercore/rest/asset-context/active-asset-data.mdx new file mode 100644 index 000000000..4e4f50092 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/asset-context/active-asset-data.mdx @@ -0,0 +1,75 @@ +--- +title: "Active asset data" +description: "HyperCore private-preview documentation." +--- + + + +# Active asset data + +Returns a user's active perpetual-market trading capacity and leverage for one coin. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `activeAssetData`. | +| `user` | string | Yes | Master or sub-account address. | +| `coin` | string | Yes | Perpetual market identifier. | + +```json +{ + "type": "activeAssetData", + "user": "0x0000000000000000000000000000000000000000", + "coin": "BTC" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------------ | ----------------- | --------------------------------------------------------- | +| `user` | string | Account address. | +| `coin` | string | Perpetual market symbol requested by the caller. | +| `leverage` | object | Selected leverage configuration for this user and market. | +| `leverage.type` | cross \| isolated | Selected margin mode: `cross` or `isolated`. | +| `leverage.value` | integer | Configured leverage multiplier. | +| `leverage.rawUsd` | string | HIP-3 isolated-margin amount in USD, when supplied. | +| `maxTradeSzs` | array | Maximum buy and sell sizes permitted at current margin. | +| `availableToTrade` | array | Available buy and sell notional at current margin. | +| `markPx` | string | Current mark price used for margin and unrealized PnL. | + +## Response example + + + + +```json +{ + "user": "0xb65822a30bbaaa68942d6f4c43d78704faeabbbb", + "coin": "APT", + "leverage": { "type": "cross", "value": 3 }, + "maxTradeSzs": ["24836370.4400000013", "24836370.4400000013"], + "availableToTrade": ["37019438.0284740031", "37019438.0284740031"], + "markPx": "4.4716" +} +``` + + + + +```json +{ + "user": "0xa15099a30bbf2e68942d6f4c43d70d04faeab0a0", + "coin": "xyz:XYZ100", + "leverage": { "type": "isolated", "value": 20, "rawUsd": "0.0" }, + "maxTradeSzs": ["0.0", "0.0"], + "availableToTrade": ["0.0", "0.0"], + "markPx": "25451.0" +} +``` + + + diff --git a/content/api-reference/data/hypercore/rest/asset-context/meta-and-asset-ctxs.mdx b/content/api-reference/data/hypercore/rest/asset-context/meta-and-asset-ctxs.mdx new file mode 100644 index 000000000..7e68a3e87 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/asset-context/meta-and-asset-ctxs.mdx @@ -0,0 +1,114 @@ +--- +title: "Perpetual metadata and asset contexts" +description: "HyperCore private-preview documentation." +--- + + + +# Perpetual metadata and asset contexts + +Returns perpetual metadata and aligned live market contexts; use it to read the current oracle price alongside mark and mid prices. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ----------------------------------------------------- | +| `type` | string | Yes | Selects `metaAndAssetCtxs`. | +| `dex` | string | No | Perpetual DEX name; omit for the first perpetual DEX. | + +```json +{ + "type": "metaAndAssetCtxs", + "dex": "" +} +``` + +## Response fields + +| Field | Type | Description | +| ---------------------------- | -------------- | ----------------------------------------------------------------------------------------- | +| `[0]` | object | Metadata object at tuple index 0. | +| `[0].universe[]` | array | Ordered perpetual market definitions aligned to context entries. | +| `[0].universe[].name` | string | Perpetual market symbol, for example `BTC`. | +| `[0].universe[].szDecimals` | integer | Number of decimal places accepted for order sizes. | +| `[0].universe[].maxLeverage` | integer | Maximum leverage permitted for the market. | +| `[0].marginTables` | array | Leverage-tier definitions referenced by `marginTableId`. | +| `[0].collateralToken` | integer | Spot-token index used as collateral. | +| `[1]` | array | Aligned asset-context array at tuple index 1. | +| `[1][].dayNtlVlm` | string | Rolling 24-hour notional trading volume. | +| `[1][].funding` | string | Current funding rate for the market. | +| `[1][].impactPxs` | array \| null | Estimated prices for market-impact calculations on each side, or `null` when unavailable. | +| `[1][].markPx` | string | Current mark price used for margin and unrealized PnL. | +| `[1][].midPx` | string \| null | Current midpoint between the best bid and ask, or `null` without both sides. | +| `[1][].openInterest` | string | Total open position size, as a decimal string. | +| `[1][].oraclePx` | string | Current external oracle price used by the market. | +| `[1][].premium` | string \| null | Mark-price premium relative to the oracle price, or `null` when unavailable. | +| `[1][].prevDayPx` | string | Market price approximately 24 hours earlier. | + +## Response example + + + + +```json +[ + { + "universe": [{ "name": "BTC", "szDecimals": 5, "maxLeverage": 50 }], + "marginTables": [], + "collateralToken": 0 + }, + [ + { + "dayNtlVlm": "1169046.29406", + "funding": "0.0000125", + "impactPxs": ["14.3047", "14.3444"], + "markPx": "14.3161", + "midPx": "14.314", + "openInterest": "688.11", + "oraclePx": "14.32", + "premium": "0.00031774", + "prevDayPx": "15.322" + } + ] +] +``` + + + + +```json +[ + { + "universe": [ + { + "name": "xyz:XYZ100", + "szDecimals": 4, + "maxLeverage": 20, + "marginTableId": 20, + "onlyIsolated": true + } + ], + "marginTables": [], + "collateralToken": 0 + }, + [ + { + "funding": "0.0002110251", + "openInterest": "0.0854", + "prevDayPx": "25956.0", + "dayNtlVlm": "462.9758", + "premium": "0.0031136686", + "oraclePx": "25372.0", + "markPx": "25451.0", + "midPx": "25451.0", + "impactPxs": ["24946.0", "25956.0"], + "dayBaseVlm": "0.0183" + } + ] +] +``` + + + diff --git a/content/api-reference/data/hypercore/rest/asset-context/predicted-fundings.mdx b/content/api-reference/data/hypercore/rest/asset-context/predicted-fundings.mdx new file mode 100644 index 000000000..452c43fbb --- /dev/null +++ b/content/api-reference/data/hypercore/rest/asset-context/predicted-fundings.mdx @@ -0,0 +1,53 @@ +--- +title: "Predicted fundings" +description: "HyperCore private-preview documentation." +--- + + + +# Predicted fundings + +Returns predicted funding rates and scheduled funding times for the first perpetual DEX. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ---------------------------- | +| `type` | string | Yes | Selects `predictedFundings`. | + +```json +{ + "type": "predictedFundings" +} +``` + +## Response fields + +| Field | Type | Description | +| --------------------------------- | -------------- | --------------------------------------------------------- | +| `[]` | array | One tuple per market containing its funding predictions. | +| `[][0]` | string | Market symbol for this prediction tuple. | +| `[][1]` | array | Predictions grouped by the venues contributing rates. | +| `[][1][][0]` | string \| null | Venue identifier, or `null` when that venue has no entry. | +| `[][1][][1]` | object | Funding-rate schedule reported by the associated venue. | +| `[][1][][1].fundingRate` | string | Predicted funding rate for the next interval. | +| `[][1][][1].nextFundingTime` | integer | Next scheduled funding time in milliseconds. | +| `[][1][][1].fundingIntervalHours` | integer | Hours between funding events for this venue. | + +## Response example + +```json +[ + [ + "AVAX", + [ + [ + "HlPerp", + { "fundingRate": "0.0000125", "nextFundingTime": 1733958000000 } + ] + ] + ] +] +``` diff --git a/content/api-reference/data/hypercore/rest/asset-context/spot-meta-and-asset-ctxs.mdx b/content/api-reference/data/hypercore/rest/asset-context/spot-meta-and-asset-ctxs.mdx new file mode 100644 index 000000000..b618f148c --- /dev/null +++ b/content/api-reference/data/hypercore/rest/asset-context/spot-meta-and-asset-ctxs.mdx @@ -0,0 +1,64 @@ +--- +title: "Spot metadata and asset contexts" +description: "HyperCore private-preview documentation." +--- + + + +# Spot metadata and asset contexts + +Returns spot metadata with the aligned current context for each spot pair. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------- | +| `type` | string | Yes | Selects `spotMetaAndAssetCtxs`. | + +```json +{ + "type": "spotMetaAndAssetCtxs" +} +``` + +## Response fields + +| Field | Type | Description | +| -------------------------- | ------- | --------------------------------------------------------- | +| `[0]` | object | Metadata object at tuple index 0. | +| `[0].tokens[]` | array | Spot-token definitions used by the pair universe. | +| `[0].tokens[].name` | string | Spot-token symbol, for example `USDC`. | +| `[0].tokens[].szDecimals` | integer | Number of decimal places accepted for order sizes. | +| `[0].tokens[].weiDecimals` | integer | Decimal places in the token’s smallest unit. | +| `[0].tokens[].index` | integer | Zero-based index used to reference this token or pair. | +| `[0].universe[]` | array | Ordered spot-pair definitions aligned to context entries. | +| `[0].universe[].name` | string | Spot-pair symbol, for example `PURR/USDC`. | +| `[0].universe[].tokens` | array | Indices of the base and quote tokens in the token list. | +| `[1]` | array | Aligned asset-context array at tuple index 1. | +| `[1][].dayNtlVlm` | string | Rolling 24-hour notional trading volume. | +| `[1][].markPx` | string | Current mark price for the spot pair. | +| `[1][].midPx` | string | Current midpoint between the best bid and ask. | +| `[1][].prevDayPx` | string | Market price approximately 24 hours earlier. | + +## Response example + +```json +[ + { + "tokens": [ + { "name": "USDC", "szDecimals": 8, "weiDecimals": 8, "index": 0 } + ], + "universe": [{ "name": "PURR/USDC", "tokens": [1, 0] }] + }, + [ + { + "dayNtlVlm": "8906.0", + "markPx": "0.14", + "midPx": "0.209265", + "prevDayPx": "0.20432" + } + ] +] +``` diff --git a/content/api-reference/data/hypercore/rest/ledger-and-funding/user-funding.mdx b/content/api-reference/data/hypercore/rest/ledger-and-funding/user-funding.mdx new file mode 100644 index 000000000..b76d54c7e --- /dev/null +++ b/content/api-reference/data/hypercore/rest/ledger-and-funding/user-funding.mdx @@ -0,0 +1,90 @@ +--- +title: "User funding" +description: "HyperCore private-preview documentation." +--- + + + +# User funding + +Returns a user's funding-payment history over a time range. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| ----------- | ------- | -------- | ----------------------------------------------------------------- | +| `type` | string | Yes | Selects `userFunding`. | +| `user` | string | Yes | Master or sub-account address. | +| `startTime` | integer | Yes | Inclusive start time in milliseconds. | +| `endTime` | integer | No | Inclusive end time in milliseconds; defaults to the current time. | + +```json +{ + "type": "userFunding", + "user": "0x0000000000000000000000000000000000000000", + "startTime": 1735689600000, + "endTime": 1735776000000 +} +``` + +## Response fields + +| Field | Type | Description | +| ---------------------- | --------------- | ------------------------------------------------------------------- | +| `[]` | array | Funding-payment records for the requested time range. | +| `[].delta` | object | Event-specific funding payload. | +| `[].delta.type` | string | Event kind; this read returns `funding`. | +| `[].delta.coin` | string | Market identifier. | +| `[].delta.usdc` | string | Funding payment in USDC; negative values are payments made. | +| `[].delta.szi` | string | Signed position size when the funding payment was applied. | +| `[].delta.fundingRate` | string | Funding rate. | +| `[].delta.nSamples` | integer \| null | Number of samples used, or `null` when no sample count is supplied. | +| `[].hash` | string | Transaction hash that recorded the funding payment. | +| `[].time` | integer | Millisecond timestamp of the funding event. | + +## Response example + + + + +```json +[ + { + "delta": { + "type": "funding", + "coin": "ETH", + "usdc": "-3.625312", + "szi": "49.1477", + "fundingRate": "0.0000417", + "nSamples": null + }, + "hash": "0xa166e3fa63c25663024b03f2e0da011a00307e4017465df020210d3d432e7cb8", + "time": 1681222254710 + } +] +``` + + + + +```json +[ + { + "delta": { + "type": "funding", + "coin": "xyz:XYZ100", + "usdc": "2.378343", + "szi": "-15.0", + "fundingRate": "0.00000625", + "nSamples": null + }, + "hash": "0xa166e3fa63c25663024b03f2e0da011a00307e4017465df020210d3d432e7cb9", + "time": 1767654000068 + } +] +``` + + + diff --git a/content/api-reference/data/hypercore/rest/ledger-and-funding/user-non-funding-ledger-updates.mdx b/content/api-reference/data/hypercore/rest/ledger-and-funding/user-non-funding-ledger-updates.mdx new file mode 100644 index 000000000..eb49519e1 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/ledger-and-funding/user-non-funding-ledger-updates.mdx @@ -0,0 +1,52 @@ +--- +title: "Non-funding ledger updates" +description: "HyperCore private-preview documentation." +--- + + + +# Non-funding ledger updates + +Returns deposits, transfers, withdrawals, and other non-funding ledger activity over a time range. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| ----------- | ------- | -------- | ----------------------------------------------------------------- | +| `type` | string | Yes | Selects `userNonFundingLedgerUpdates`. | +| `user` | string | Yes | Master or sub-account address. | +| `startTime` | integer | Yes | Inclusive start time in milliseconds. | +| `endTime` | integer | No | Inclusive end time in milliseconds; defaults to the current time. | + +```json +{ + "type": "userNonFundingLedgerUpdates", + "user": "0x0000000000000000000000000000000000000000", + "startTime": 1735689600000, + "endTime": 1735776000000 +} +``` + +## Response fields + +| Field | Type | Description | +| --------------- | ------- | -------------------------------------------------------- | +| `[]` | array | Non-funding ledger events for the requested time range. | +| `[].delta` | object | Event-specific payload; use `type` to select its schema. | +| `[].delta.type` | string | Ledger event kind that determines the `delta` shape. | +| `[].hash` | string | Transaction hash that recorded the ledger event. | +| `[].time` | integer | Millisecond timestamp of the ledger event. | + +## Response example + +```json +[ + { + "delta": { "type": "deposit", "usdc": "100.0" }, + "hash": "0xa166e3fa63c25663024b03f2e0da011a00307e4017465df020210d3d432e7cb8", + "time": 1681222254710 + } +] +``` diff --git a/content/api-reference/data/hypercore/rest/market-data-and-snapshots/all-mids.mdx b/content/api-reference/data/hypercore/rest/market-data-and-snapshots/all-mids.mdx new file mode 100644 index 000000000..aee74485a --- /dev/null +++ b/content/api-reference/data/hypercore/rest/market-data-and-snapshots/all-mids.mdx @@ -0,0 +1,39 @@ +--- +title: "All mids" +description: "HyperCore private-preview documentation." +--- + + + +# All mids + +Returns the current mid price for each market on a perpetual DEX. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ----------------------------------------------------- | +| `type` | string | Yes | Selects `allMids`. | +| `dex` | string | No | Perpetual DEX name; omit for the first perpetual DEX. | + +```json +{ + "type": "allMids", + "dex": "" +} +``` + +## Response fields + +| Field | Type | Description | +| ---------- | ------ | ---------------------------------------------------- | +| `Response` | object | Map of asset identifier to decimal-string mid price. | +| `` | string | Decimal-string mid price for the asset identifier. | + +## Response example + +```json +{ "APE": "4.33245", "ARB": "1.21695" } +``` diff --git a/content/api-reference/data/hypercore/rest/market-data-and-snapshots/candle-snapshot.mdx b/content/api-reference/data/hypercore/rest/market-data-and-snapshots/candle-snapshot.mdx new file mode 100644 index 000000000..c1256673c --- /dev/null +++ b/content/api-reference/data/hypercore/rest/market-data-and-snapshots/candle-snapshot.mdx @@ -0,0 +1,70 @@ +--- +title: "Candle snapshot" +description: "HyperCore private-preview documentation." +--- + + + +# Candle snapshot + +Returns up to 5,000 OHLCV candles for charting a market over a bounded time range. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------ | +| `type` | string | Yes | Selects `candleSnapshot`. | +| `req` | object | Yes | Nested candle request. | +| `req.coin` | string | Yes | Market identifier; HIP-3 markets use a DEX-prefixed name. | +| `req.interval` | string | Yes | One of `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`, `3d`, `1w`, or `1M`. | +| `req.startTime` | integer | Yes | Inclusive start time in milliseconds. | +| `req.endTime` | integer | Yes | Inclusive end time in milliseconds. | + +```json +{ + "type": "candleSnapshot", + "req": { + "coin": "BTC", + "interval": "15m", + "startTime": 1735689600000, + "endTime": 1735776000000 + } +} +``` + +## Response fields + +| Field | Type | Description | +| ------ | ------- | ------------------------------------------------------- | +| `[]` | array | Candles ordered by the requested time range. | +| `[].T` | integer | Candle close time in milliseconds. | +| `[].c` | string | Closing price as a decimal string. | +| `[].h` | string | Highest traded price during the interval. | +| `[].i` | string | Candle interval, such as `15m` or `1h`. | +| `[].l` | string | Lowest traded price during the interval. | +| `[].n` | integer | Number of trades included in the candle. | +| `[].o` | string | Opening price as a decimal string. | +| `[].s` | string | Market symbol; HIP-3 markets include the DEX prefix. | +| `[].t` | integer | Candle open time in milliseconds. | +| `[].v` | string | Traded volume during the interval, as a decimal string. | + +## Response example + +```json +[ + { + "T": 1681924499999, + "c": "29258.0", + "h": "29309.0", + "i": "15m", + "l": "29250.0", + "n": 189, + "o": "29295.0", + "s": "BTC", + "t": 1681923600000, + "v": "0.98639" + } +] +``` diff --git a/content/api-reference/data/hypercore/rest/market-data-and-snapshots/l4-snapshots.mdx b/content/api-reference/data/hypercore/rest/market-data-and-snapshots/l4-snapshots.mdx new file mode 100644 index 000000000..c6a5efd95 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/market-data-and-snapshots/l4-snapshots.mdx @@ -0,0 +1,75 @@ +--- +title: "L4 book snapshots" +description: "HyperCore private-preview documentation." +--- + + + +# L4 book snapshots + +Alchemy-original read that returns an order-level L4 snapshot for checkpointing an order-status stream. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| ---------------------- | ------- | -------- | ------------------------------------------------ | +| `type` | string | Yes | Selects the Alchemy-original `l4Snapshots` read. | +| `includeUsers` | boolean | No | Include order owners. | +| `includeTriggerOrders` | boolean | No | Include trigger orders. | + +```json +{ + "type": "l4Snapshots", + "includeUsers": true, + "includeTriggerOrders": true +} +``` + +## Response fields + +| Field | Type | Description | +| -------------------- | ------- | ---------------------------------------------------- | +| `[]` | array | Per-market snapshot tuples. | +| `[][0]` | string | Market identifier. | +| `[][1]` | array | Bid and ask sides. | +| `[][1][].coin` | string | Order market. | +| `[][1][].side` | string | `B` for a bid or `A` for an ask. | +| `[][1][].limitPx` | string | Order limit price. | +| `[][1][].sz` | string | Order size. | +| `[][1][].oid` | integer | Order identifier. | +| `[][1][].timestamp` | integer | Millisecond time when the resting order was created. | +| `[][1][].isTrigger` | boolean | Whether the order is a trigger order. | +| `[][1][].triggerPx` | string | Trigger price. | +| `[][1][].reduceOnly` | boolean | Whether the order is reduce-only. | +| `[][1][].origSz` | string | Original order size. | + +## Response example + +```json +[ + [ + "BTC", + [ + [ + { + "coin": "BTC", + "side": "B", + "limitPx": "103988.0", + "sz": "0.2782", + "oid": 30112287571, + "timestamp": 1747157301016, + "isTrigger": false, + "triggerPx": "0.0", + "reduceOnly": false, + "origSz": "0.2782" + } + ], + [] + ] + ] +] +``` + +Within a price level, orders are sorted in time order. Trigger orders come last and are identified by `isTrigger`. diff --git a/content/api-reference/data/hypercore/rest/market-data-and-snapshots/trigger-order-snapshot.mdx b/content/api-reference/data/hypercore/rest/market-data-and-snapshots/trigger-order-snapshot.mdx new file mode 100644 index 000000000..ff40cd726 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/market-data-and-snapshots/trigger-order-snapshot.mdx @@ -0,0 +1,35 @@ +--- +title: "Trigger-order snapshot" +description: "HyperCore private-preview documentation." +--- + + + +# Trigger-order snapshot + +Alchemy-original read for a trigger-order snapshot. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------- | +| `type` | string | Yes | Selects `triggerOrderSnapshot`. | + +```json +{ + "type": "triggerOrderSnapshot" +} +``` + +## Response fields + +| Field | Type | Description | +| ---------- | ------ | -------------------------------------------------------- | +| `Response` | object | Trigger-order snapshot payload. | +| `` | object | The response contract requires engineering confirmation. | + +## Response example + +Use this Alchemy-original read when a client needs a REST checkpoint rather than an in-band stream snapshot. Its response contract requires engineering confirmation, so no unverified field names or example are published. diff --git a/content/api-reference/data/hypercore/rest/metadata/meta.mdx b/content/api-reference/data/hypercore/rest/metadata/meta.mdx new file mode 100644 index 000000000..6bbd080eb --- /dev/null +++ b/content/api-reference/data/hypercore/rest/metadata/meta.mdx @@ -0,0 +1,62 @@ +--- +title: "Perpetual metadata" +description: "HyperCore private-preview documentation." +--- + + + +# Perpetual metadata + +Returns perpetual market definitions and margin tiers for a selected DEX. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ----------------------------------------------------- | +| `type` | string | Yes | Selects `meta`. | +| `dex` | string | No | Perpetual DEX name; omit for the first perpetual DEX. | + +```json +{ + "type": "meta", + "dex": "" +} +``` + +## Response fields + +| Field | Type | Description | +| --------------------------------------------- | ----------------- | ----------------------------------------------------------------------- | +| `universe[]` | array | Ordered perpetual market definitions; index aligns with asset contexts. | +| `universe[].name` | string | Perpetual market symbol, for example `BTC`. | +| `universe[].szDecimals` | integer | Number of decimal places accepted for order sizes. | +| `universe[].maxLeverage` | integer | Maximum leverage permitted for the market. | +| `universe[].marginTableId` | integer | Identifier of the leverage-tier table used by this market. | +| `universe[].onlyIsolated` | boolean | Whether the market permits isolated margin only. | +| `universe[].isDelisted` | boolean | Whether trading has been delisted for the market. | +| `universe[].marginMode` | cross \| isolated | Allowed margin mode: `cross` or `isolated`. | +| `marginTables` | array | Leverage-tier definitions referenced by `marginTableId`. | +| `marginTables[][0]` | integer | Margin-table identifier referenced by market definitions. | +| `marginTables[][1].description` | string | Human-readable description of this margin table. | +| `marginTables[][1].marginTiers[]` | array | Notional thresholds and their maximum leverage limits. | +| `marginTables[][1].marginTiers[].lowerBound` | string | Minimum notional at which this margin tier applies. | +| `marginTables[][1].marginTiers[].maxLeverage` | integer | Maximum leverage allowed within this notional tier. | + +## Response example + +```json +{ + "universe": [{ "name": "BTC", "szDecimals": 5, "maxLeverage": 50 }], + "marginTables": [ + [ + 50, + { + "description": "", + "marginTiers": [{ "lowerBound": "0.0", "maxLeverage": 50 }] + } + ] + ] +} +``` diff --git a/content/api-reference/data/hypercore/rest/metadata/spot-meta.mdx b/content/api-reference/data/hypercore/rest/metadata/spot-meta.mdx new file mode 100644 index 000000000..f4ca265fc --- /dev/null +++ b/content/api-reference/data/hypercore/rest/metadata/spot-meta.mdx @@ -0,0 +1,65 @@ +--- +title: "Spot metadata" +description: "HyperCore private-preview documentation." +--- + + + +# Spot metadata + +Returns spot token and spot-pair definitions. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------- | +| `type` | string | Yes | Selects `spotMeta`. | + +```json +{ + "type": "spotMeta" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------------------ | -------------- | --------------------------------------------------------- | +| `tokens[]` | array | Spot-token definitions used by spot-pair entries. | +| `tokens[].name` | string | Spot-token symbol, for example `USDC`. | +| `tokens[].szDecimals` | integer | Number of decimal places accepted for order sizes. | +| `tokens[].weiDecimals` | integer | Decimal places in the token’s smallest unit. | +| `tokens[].index` | integer | Zero-based index used to reference this token. | +| `tokens[].tokenId` | string | Onchain identifier assigned to the spot token. | +| `tokens[].isCanonical` | boolean | Whether this token is in the canonical spot universe. | +| `tokens[].evmContract` | string \| null | EVM contract address, or `null` when none is assigned. | +| `tokens[].fullName` | string \| null | Full token name, or `null` when not supplied. | +| `universe[]` | array | Ordered spot-pair definitions. | +| `universe[].name` | string | Spot-pair symbol, for example `PURR/USDC`. | +| `universe[].tokens` | array | Indices of the base and quote tokens in the token list. | +| `universe[].index` | integer | Pair index used in the `@{index}` spot identifier. | +| `universe[].isCanonical` | boolean | Whether this pair belongs to the canonical spot universe. | + +## Response example + +```json +{ + "tokens": [ + { + "name": "USDC", + "szDecimals": 8, + "weiDecimals": 8, + "index": 0, + "tokenId": "0x6d1e7cde53ba9467b783cb7c530ce054", + "isCanonical": true, + "evmContract": null, + "fullName": null + } + ], + "universe": [ + { "name": "PURR/USDC", "tokens": [1, 0], "index": 0, "isCanonical": true } + ] +} +``` diff --git a/content/api-reference/data/hypercore/rest/orders-and-fills/frontend-open-orders.mdx b/content/api-reference/data/hypercore/rest/orders-and-fills/frontend-open-orders.mdx new file mode 100644 index 000000000..2a63b7886 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/orders-and-fills/frontend-open-orders.mdx @@ -0,0 +1,69 @@ +--- +title: "Frontend open orders" +description: "HyperCore private-preview documentation." +--- + + + +# Frontend open orders + +Returns open orders with trigger, reduce-only, and order-type details used by trading interfaces. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ----------------------------------------------------- | +| `type` | string | Yes | Selects `frontendOpenOrders`. | +| `user` | string | Yes | Master or sub-account address. | +| `dex` | string | No | Perpetual DEX name; omit for the first perpetual DEX. | + +```json +{ + "type": "frontendOpenOrders", + "user": "0x0000000000000000000000000000000000000000", + "dex": "" +} +``` + +## Response fields + +| Field | Type | Description | +| --------------------- | ------- | ------------------------------------------------------- | +| `[]` | array | Open-order entries. | +| `[].coin` | string | Market identifier. | +| `[].isPositionTpsl` | boolean | Whether the order applies to an entire position. | +| `[].isTrigger` | boolean | Whether this is a conditional trigger order. | +| `[].limitPx` | string | Limit price, as a decimal string. | +| `[].oid` | integer | Order identifier. | +| `[].orderType` | string | Order instruction, such as limit or trigger order. | +| `[].origSz` | string | Original order size before fills or reductions. | +| `[].reduceOnly` | boolean | Whether execution may only reduce an existing position. | +| `[].side` | string | `B` for a bid or `A` for an ask. | +| `[].sz` | string | Size. | +| `[].timestamp` | integer | Millisecond time when the order was created. | +| `[].triggerCondition` | string | Price condition that activates the trigger order. | +| `[].triggerPx` | string | Price threshold that activates the trigger order. | + +## Response example + +```json +[ + { + "coin": "BTC", + "isPositionTpsl": false, + "isTrigger": false, + "limitPx": "29792.0", + "oid": 91490942, + "orderType": "Limit", + "origSz": "5.0", + "reduceOnly": false, + "side": "A", + "sz": "5.0", + "timestamp": 1681247412573, + "triggerCondition": "N/A", + "triggerPx": "0.0" + } +] +``` diff --git a/content/api-reference/data/hypercore/rest/orders-and-fills/open-orders.mdx b/content/api-reference/data/hypercore/rest/orders-and-fills/open-orders.mdx new file mode 100644 index 000000000..df9ccf23c --- /dev/null +++ b/content/api-reference/data/hypercore/rest/orders-and-fills/open-orders.mdx @@ -0,0 +1,55 @@ +--- +title: "Open orders" +description: "HyperCore private-preview documentation." +--- + + + +# Open orders + +Returns a user's current open orders for a selected perpetual DEX. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ----------------------------------------------------- | +| `type` | string | Yes | Selects `openOrders`. | +| `user` | string | Yes | Master or sub-account address. | +| `dex` | string | No | Perpetual DEX name; omit for the first perpetual DEX. | + +```json +{ + "type": "openOrders", + "user": "0x0000000000000000000000000000000000000000", + "dex": "" +} +``` + +## Response fields + +| Field | Type | Description | +| -------------- | ------- | -------------------------------------------- | +| `[]` | array | Open-order entries. | +| `[].coin` | string | Market identifier. | +| `[].limitPx` | string | Limit price, as a decimal string. | +| `[].oid` | integer | Order identifier. | +| `[].side` | string | `B` for a bid or `A` for an ask. | +| `[].sz` | string | Size. | +| `[].timestamp` | integer | Millisecond time when the order was created. | + +## Response example + +```json +[ + { + "coin": "BTC", + "limitPx": "29792.0", + "oid": 91490942, + "side": "A", + "sz": "0.0", + "timestamp": 1681247412573 + } +] +``` diff --git a/content/api-reference/data/hypercore/rest/outcome-markets/outcome-meta.mdx b/content/api-reference/data/hypercore/rest/outcome-markets/outcome-meta.mdx new file mode 100644 index 000000000..46026ea30 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/outcome-markets/outcome-meta.mdx @@ -0,0 +1,56 @@ +--- +title: "Outcome metadata" +description: "HyperCore private-preview documentation." +--- + + + +# Outcome metadata + +Returns registered outcome-market specifications and questions. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ---------------------- | +| `type` | string | Yes | Selects `outcomeMeta`. | + +```json +{ + "type": "outcomeMeta" +} +``` + +## Response fields + +| Field | Type | Description | +| ----------------------------- | ------- | --------------------------------------------------- | +| `outcomes[]` | array | Registered outcome-market specifications. | +| `outcomes[].outcome` | integer | Numeric identifier for the outcome market. | +| `outcomes[].name` | string | Display name for the outcome market. | +| `outcomes[].description` | string | Machine-readable attributes that define the market. | +| `outcomes[].sideSpecs[]` | array | Permitted outcome sides for this market. | +| `outcomes[].sideSpecs[].name` | string | Display label for an allowed outcome side. | +| `questions[]` | array | Question records associated with outcome markets. | +| `deployers` | array | Addresses registered to deploy outcome markets. | +| `feeScale` | integer | Fee-scale setting used for outcome-market fees. | + +## Response example + +```json +{ + "outcomes": [ + { + "outcome": 123, + "name": "Recurring", + "description": "class:priceBinary|underlying:HYPE|expiry:20260310-1100|targetPrice:34.5|period:3m", + "sideSpecs": [{ "name": "Yes" }, { "name": "No" }] + } + ], + "questions": [], + "deployers": [], + "feeScale": 0 +} +``` diff --git a/content/api-reference/data/hypercore/rest/outcome-markets/outcome-templates.mdx b/content/api-reference/data/hypercore/rest/outcome-markets/outcome-templates.mdx new file mode 100644 index 000000000..b21df3910 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/outcome-markets/outcome-templates.mdx @@ -0,0 +1,51 @@ +--- +title: "Outcome templates" +description: "HyperCore private-preview documentation." +--- + + + +# Outcome templates + +Returns registered outcome templates for HIP-4 deployment planning. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | --------------------------- | +| `type` | string | Yes | Selects `outcomeTemplates`. | + +```json +{ + "type": "outcomeTemplates" +} +``` + +## Response fields + +| Field | Type | Description | +| ---------------- | ------- | ------------------------------------------------------- | +| `[]` | array | Outcome-template entries. | +| `[].id` | integer | Numeric identifier used when selecting the template. | +| `[].role` | string | Role the template configures for an outcome deployment. | +| `[].name` | string | Human-readable label shown for the template. | +| `[].description` | string | Human-readable explanation of the template's purpose. | +| `[].keywords` | array | Search terms associated with the template. | + +## Response example + +```json +[ + { + "id": 1, + "role": "creator", + "name": "Price binary", + "description": "A binary price outcome template.", + "keywords": ["price", "binary"] + } +] +``` + +Mainnet returned an empty list in the capture. The populated shape above was observed on testnet, where permissionless HIP-4 deployment is available. For deployment context, see [Deploying Hyperliquid markets](/docs/chains/deploying-markets). diff --git a/content/api-reference/data/hypercore/rest/outcome-markets/settled-outcome.mdx b/content/api-reference/data/hypercore/rest/outcome-markets/settled-outcome.mdx new file mode 100644 index 000000000..f61e71e6a --- /dev/null +++ b/content/api-reference/data/hypercore/rest/outcome-markets/settled-outcome.mdx @@ -0,0 +1,56 @@ +--- +title: "Settled outcome" +description: "HyperCore private-preview documentation." +--- + + + +# Settled outcome + +Returns the specification and settlement details for one outcome identifier. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------- | -------- | ------------------------- | +| `type` | string | Yes | Selects `settledOutcome`. | +| `outcome` | integer | Yes | Outcome identifier. | + +```json +{ + "type": "settledOutcome", + "outcome": 95 +} +``` + +## Response fields + +| Field | Type | Description | +| ----------------------- | ------- | ------------------------------------------------- | +| `spec` | object | Configuration that defined the settled outcome. | +| `spec.outcome` | integer | Numeric identifier of the settled outcome market. | +| `spec.name` | string | Displayed title of the settled outcome. | +| `spec.description` | string | Human-readable wording of the outcome question. | +| `spec.sideSpecs[]` | array | Allowed outcome sides at settlement. | +| `spec.sideSpecs[].name` | string | Display label for that selectable side. | +| `spec.quoteToken` | string | Token used to quote the outcome market. | +| `settleFraction` | string | Settlement fraction. | +| `details` | string | Supporting information used for settlement. | + +## Response example + +```json +{ + "spec": { + "outcome": 95, + "name": "Recurring", + "description": "class:priceBinary|underlying:BTC|expiry:20260526-0600|targetPrice:77363|period:1d", + "sideSpecs": [{ "name": "Yes" }, { "name": "No" }], + "quoteToken": "USDC" + }, + "settleFraction": "0.0", + "details": "price:76876.9" +} +``` diff --git a/content/api-reference/data/hypercore/rest/overview.mdx b/content/api-reference/data/hypercore/rest/overview.mdx index ba174be27..cb2fb8369 100644 --- a/content/api-reference/data/hypercore/rest/overview.mdx +++ b/content/api-reference/data/hypercore/rest/overview.mdx @@ -9,25 +9,42 @@ description: "HyperCore private-preview documentation." ## Interfaces -The REST reference provides native-compatible reads through `POST /{apiKey}/info` and purpose-built POST routes at the provisional base URL `https://api.g.alchemy.com/hypercore/v1`. The base URL will be confirmed before general availability. +The REST reference provides native-compatible reads through `POST /{apiKey}/info` and purpose-built POST routes at `https://api.g.alchemy.com/hypercore/v1`. -## Native-compatible reads + -Use `/info` with a `type` discriminator for the native-compatible types. Four of those types also have purpose-built routes; the other six are currently available only through `/info`. +The `/info` reads documented here are served today at +`https://hyperliquid-mainnet.g.alchemy.com/v2/{apiKey}/info`. The HyperCore REST +host is the target for these reads at general availability. -| Native type | Available via `/info` | Purpose-built route | -| --- | --- | --- | -| `userFills` | Yes | `POST /{apiKey}/user-fills` | -| `userFillsByTime` | Yes | `POST /{apiKey}/user-fills-by-time` | -| `historicalOrders` | Yes | `POST /{apiKey}/historical-orders` | -| `userFunding` | Yes | — | -| `userNonFundingLedgerUpdates` | Yes | — | -| `delegations` | Yes | — | -| `delegatorHistory` | Yes | — | -| `clearinghouseState` | Yes | `POST /{apiKey}/clearinghouse-state` | -| `spotClearinghouseState` | Yes | — | -| `frontendOpenOrders` | Yes | — | + -## Enriched composites +### Native `/info` conventions -`POST /{apiKey}/portfolio-state` and `POST /{apiKey}/extra-agents` are enriched composites rather than native types. +Time-range responses return at most 500 elements or distinct blocks of data. For a +larger range, use the last returned timestamp as the next `startTime`. + +For perpetuals, `coin` is the name returned by `meta`. For spot, use `PURR/USDC` +for PURR and `@{index}` for other pairs, where `index` is the pair index in +`spotMeta.universe`. + +Pass the actual master or sub-account address when querying account data. An agent +wallet address returns an empty result. + +For deployment context, see [Deploying Hyperliquid markets](/docs/chains/deploying-markets). + +## Read paths + +Every read other than the seven routes below uses `POST /{apiKey}/info` with a +`type` discriminator. The resource-family pages in this reference document each +request body and response contract. + +| Purpose-built route | Corresponding read | +| -------------------------------------- | ---------------------------- | +| `POST /{apiKey}/user-fills` | `userFills` | +| `POST /{apiKey}/user-fills-by-time` | `userFillsByTime` | +| `POST /{apiKey}/clearinghouse-state` | `clearinghouseState` | +| `POST /{apiKey}/historical-orders` | `historicalOrders` | +| `POST /{apiKey}/portfolio-state` | Enriched portfolio composite | +| `POST /{apiKey}/extra-agents` | Enriched agent composite | +| `POST /{apiKey}/l2-book-diff-snapshot` | L2 diff bootstrap snapshot | diff --git a/content/api-reference/data/hypercore/rest/roles-agents-and-limits/max-builder-fee.mdx b/content/api-reference/data/hypercore/rest/roles-agents-and-limits/max-builder-fee.mdx new file mode 100644 index 000000000..4935b22a5 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/roles-agents-and-limits/max-builder-fee.mdx @@ -0,0 +1,40 @@ +--- +title: "Maximum builder fee" +description: "HyperCore private-preview documentation." +--- + + + +# Maximum builder fee + +Returns the maximum builder fee a user approved for one builder. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `maxBuilderFee`. | +| `user` | string | Yes | Master or sub-account address. | +| `builder` | string | Yes | Builder address. | + +```json +{ + "type": "maxBuilderFee", + "user": "0x0000000000000000000000000000000000000000", + "builder": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ---------- | ------- | -------------------------------------------------------------------- | +| `Response` | integer | Maximum builder fee in thousandths of a percent; `1` means `0.001%`. | + +## Response example + +```json +1 +``` diff --git a/content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-fees.mdx b/content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-fees.mdx new file mode 100644 index 000000000..bd68b3d88 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-fees.mdx @@ -0,0 +1,94 @@ +--- +title: "User fees" +description: "HyperCore private-preview documentation." +--- + + + +# User fees + +Returns an account's fee schedule, current rates, and daily volume history. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `userFees`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "userFees", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------------------------------ | --------------- | -------------------------------------------------------------------- | +| `dailyUserVlm[]` | array | Daily user and exchange volume buckets. | +| `dailyUserVlm[].date` | string | UTC calendar date for this volume bucket. | +| `dailyUserVlm[].userCross` | string | User taker notional volume for the UTC day. | +| `dailyUserVlm[].userAdd` | string | User maker notional volume for the UTC day. | +| `dailyUserVlm[].exchange` | string | Exchange-wide notional volume for the same UTC day. | +| `feeSchedule` | object | Base rates and volume-tier adjustments that determine user fees. | +| `feeSchedule.cross` | string | Base perpetual taker fee rate as a decimal fraction. | +| `feeSchedule.add` | string | Base perpetual maker fee rate as a decimal fraction. | +| `feeSchedule.spotCross` | string | Base spot taker fee rate as a decimal fraction. | +| `feeSchedule.spotAdd` | string | Base spot maker fee rate as a decimal fraction. | +| `feeSchedule.tiers` | object | VIP and market-maker tiers that adjust the base fee rates. | +| `feeSchedule.referralDiscount` | string | Referral discount fraction available to eligible users. | +| `feeSchedule.stakingDiscountTiers[]` | array | Staking thresholds and associated fee-discount fractions. | +| `userCrossRate` | string | Current perpetual taker fee rate after applicable discounts. | +| `userAddRate` | string | Current perpetual maker fee rate after applicable discounts. | +| `userSpotCrossRate` | string | Current spot taker fee rate after applicable discounts. | +| `userSpotAddRate` | string | Current spot maker fee rate after applicable discounts. | +| `activeReferralDiscount` | string | Referral discount fraction currently applied to user fees. | +| `trial` | object \| null | Fee-trial details, or `null` when no trial applies. | +| `feeTrialReward` | string | Fee-trial reward amount, as a decimal string. | +| `nextTrialAvailableTimestamp` | integer \| null | Time in milliseconds when another trial may be available, or `null`. | +| `stakingLink` | object | Link between this account and its staking account. | +| `activeStakingDiscount` | object | Staking-based discount currently applied to user fees. | + +## Response example + +```json +{ + "dailyUserVlm": [ + { + "date": "2025-05-23", + "userCross": "0.0", + "userAdd": "0.0", + "exchange": "2852367.0770729999" + } + ], + "feeSchedule": { + "cross": "0.00045", + "add": "0.00015", + "spotCross": "0.0007", + "spotAdd": "0.0004", + "tiers": { "vip": [] }, + "referralDiscount": "0.04", + "stakingDiscountTiers": [] + }, + "userCrossRate": "0.000315", + "userAddRate": "0.000105", + "userSpotCrossRate": "0.00049", + "userSpotAddRate": "0.00028", + "activeReferralDiscount": "0.0", + "trial": null, + "feeTrialReward": "0.0", + "nextTrialAvailableTimestamp": null, + "stakingLink": { + "type": "tradingUser", + "stakingUser": "0x54c049d9c7d3c92c2462bf3d28e083f3d6805061" + }, + "activeStakingDiscount": { + "bpsOfMaxSupply": "4.7577998927", + "discount": "0.3" + } +} +``` diff --git a/content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-rate-limit.mdx b/content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-rate-limit.mdx new file mode 100644 index 000000000..4a796d230 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-rate-limit.mdx @@ -0,0 +1,46 @@ +--- +title: "User rate limit" +description: "HyperCore private-preview documentation." +--- + + + +# User rate limit + +Returns the native request allowance and usage for an account. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `userRateLimit`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "userRateLimit", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------------ | ------- | -------------------------------------- | +| `cumVlm` | string | Cumulative volume. | +| `nRequestsUsed` | integer | Requests used after reserved capacity. | +| `nRequestsCap` | integer | Current request cap. | +| `nRequestsSurplus` | integer | Reserved request capacity remaining. | + +## Response example + +```json +{ + "cumVlm": "2854574.593578", + "nRequestsUsed": 2890, + "nRequestsCap": 2864574, + "nRequestsSurplus": 0 +} +``` diff --git a/content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-role.mdx b/content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-role.mdx new file mode 100644 index 000000000..02b8d9c94 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/roles-agents-and-limits/user-role.mdx @@ -0,0 +1,81 @@ +--- +title: "User role" +description: "HyperCore private-preview documentation." +--- + + + +# User role + +Returns the account role and linked address where the role has one. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `userRole`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "userRole", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- | +| `role` | user \| agent \| vault \| subAccount \| missing | Account classification: `missing`, `user`, `agent`, `vault`, or `subAccount`. | +| `data` | object | Role-specific details; present for agent and sub-account roles. | +| `data.user` | string | Principal user address represented by the agent. | +| `data.master` | string | Master address that controls this sub-account. | + +## Response example + + + + +```json +{ "role": "user" } +``` + + + + +```json +{ + "role": "agent", + "data": { "user": "0x0000000000000000000000000000000000000000" } +} +``` + + + + +```json +{ "role": "vault" } +``` + + + + +```json +{ + "role": "subAccount", + "data": { "master": "0x0000000000000000000000000000000000000000" } +} +``` + + + + +```json +{ "role": "missing" } +``` + + + diff --git a/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegations.mdx b/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegations.mdx new file mode 100644 index 000000000..0976c5e27 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegations.mdx @@ -0,0 +1,47 @@ +--- +title: "Delegations" +description: "HyperCore private-preview documentation." +--- + + + +# Delegations + +Returns a user's active validator delegations. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `delegations`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "delegations", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------------------- | ------- | -------------------------------------------------- | +| `[]` | array | Current delegation positions for the account. | +| `[].validator` | string | Address of the validator receiving the delegation. | +| `[].amount` | string | Delegated stake as a decimal string. | +| `[].lockedUntilTimestamp` | integer | Delegation unlock time in milliseconds. | + +## Response example + +```json +[ + { + "validator": "0x5ac99df645f3414876c816caa18b2d234024b487", + "amount": "12060.16529862", + "lockedUntilTimestamp": 1735466781353 + } +] +``` diff --git a/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-history.mdx b/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-history.mdx new file mode 100644 index 000000000..8df8d8b32 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-history.mdx @@ -0,0 +1,57 @@ +--- +title: "Delegator history" +description: "HyperCore private-preview documentation." +--- + + + +# Delegator history + +Returns a user's delegation, deposit, and withdrawal history. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `delegatorHistory`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "delegatorHistory", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| -------------------------------- | ------- | ------------------------------------------------------ | +| `[]` | array | Delegation and undelegation events for the account. | +| `[].time` | integer | Ledger-event timestamp in milliseconds. | +| `[].hash` | string | Transaction hash for the delegation action. | +| `[].delta` | object | Ledger change whose member identifies the action type. | +| `[].delta.delegate` | object | Details of the delegation or undelegation action. | +| `[].delta.delegate.validator` | string | Address of the validator receiving or losing stake. | +| `[].delta.delegate.amount` | string | Stake amount moved by the action, as a decimal string. | +| `[].delta.delegate.isUndelegate` | boolean | `true` for an undelegation; `false` for a delegation. | + +## Response example + +```json +[ + { + "time": 1735380381353, + "hash": "0x55492465cb523f90815a041a226ba90147008d4b221a24ae8dc35a0dbede4ea4", + "delta": { + "delegate": { + "validator": "0x5ac99df645f3414876c816caa18b2d234024b487", + "amount": "10000.0", + "isUndelegate": false + } + } + } +] +``` diff --git a/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-rewards.mdx b/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-rewards.mdx new file mode 100644 index 000000000..202d86698 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-rewards.mdx @@ -0,0 +1,52 @@ +--- +title: "Delegator rewards" +description: "HyperCore private-preview documentation." +--- + + + +# Delegator rewards + +Returns a user's delegation and commission reward history. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `delegatorRewards`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "delegatorRewards", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ---------------- | ------- | ---------------------------------------------------------- | +| `[]` | array | Reward records for the requested delegator. | +| `[].time` | integer | Reward-record timestamp in milliseconds. | +| `[].source` | string | Reward category, for example `delegation` or `commission`. | +| `[].totalAmount` | string | Reward amount. | + +## Response example + +```json +[ + { + "time": 1736726400073, + "source": "delegation", + "totalAmount": "0.73117184" + }, + { + "time": 1736726400073, + "source": "commission", + "totalAmount": "130.76445876" + } +] +``` diff --git a/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-summary.mdx b/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-summary.mdx new file mode 100644 index 000000000..a305eb985 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-summary.mdx @@ -0,0 +1,46 @@ +--- +title: "Delegator summary" +description: "HyperCore private-preview documentation." +--- + + + +# Delegator summary + +Returns a user's delegated, undelegated, and pending-withdrawal staking balances. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `delegatorSummary`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "delegatorSummary", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------------------ | ------- | ------------------------------ | +| `delegated` | string | Total delegated amount. | +| `undelegated` | string | Amount not delegated. | +| `totalPendingWithdrawal` | string | Amount pending withdrawal. | +| `nPendingWithdrawals` | integer | Number of pending withdrawals. | + +## Response example + +```json +{ + "delegated": "12060.16529862", + "undelegated": "0.0", + "totalPendingWithdrawal": "0.0", + "nPendingWithdrawals": 0 +} +``` diff --git a/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/validator-l1-votes.mdx b/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/validator-l1-votes.mdx new file mode 100644 index 000000000..d15fbff57 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/staking-delegation-and-validators/validator-l1-votes.mdx @@ -0,0 +1,39 @@ +--- +title: "Validator L1 votes" +description: "HyperCore private-preview documentation." +--- + + + +# Validator L1 votes + +Returns the native validator L1-vote collection when it is available for the requested network. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | --------------------------- | +| `type` | string | Yes | Selects `validatorL1Votes`. | + +```json +{ + "type": "validatorL1Votes" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------- | ------ | --------------------------------------------------------------- | +| `[]` | array | Validator-vote entries. | +| `[].` | object | No populated native response was available to establish fields. | + +## Response example + +```json +[] +``` + +The native API accepted this request on mainnet and testnet, but the captures returned empty arrays. This page documents the confirmed request and direct-array response only; vote-entry fields will be added after a populated native payload is observed. diff --git a/content/api-reference/data/hypercore/rest/token-deployment/perp-deploy-auction-status.mdx b/content/api-reference/data/hypercore/rest/token-deployment/perp-deploy-auction-status.mdx new file mode 100644 index 000000000..7e9f435ee --- /dev/null +++ b/content/api-reference/data/hypercore/rest/token-deployment/perp-deploy-auction-status.mdx @@ -0,0 +1,46 @@ +--- +title: "Perpetual deployment auction status" +description: "HyperCore private-preview documentation." +--- + + + +# Perpetual deployment auction status + +Returns the current perpetual deployment auction state. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ---------------------------------- | +| `type` | string | Yes | Selects `perpDeployAuctionStatus`. | + +```json +{ + "type": "perpDeployAuctionStatus" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------------ | -------------- | ------------------------------------------------------------ | +| `startTimeSeconds` | integer | Unix time in seconds when the auction starts. | +| `durationSeconds` | integer | Length of the auction window in seconds. | +| `startGas` | string | Opening auction gas price in HYPE. | +| `currentGas` | string \| null | Current auction gas price, or `null` before it is available. | +| `endGas` | string \| null | Auction end gas price, or `null` while the auction is open. | + +## Response example + +```json +{ + "startTimeSeconds": 1747656000, + "durationSeconds": 111600, + "startGas": "500.0", + "currentGas": "500.0", + "endGas": null +} +``` diff --git a/content/api-reference/data/hypercore/rest/token-deployment/spot-deploy-state.mdx b/content/api-reference/data/hypercore/rest/token-deployment/spot-deploy-state.mdx new file mode 100644 index 000000000..9030f6ff9 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/token-deployment/spot-deploy-state.mdx @@ -0,0 +1,73 @@ +--- +title: "Spot deployment state" +description: "HyperCore private-preview documentation." +--- + + + +# Spot deployment state + +Returns the caller's spot-token deployment states and the current deployment auction. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `spotDeployState`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "spotDeployState", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| --------------------------------------- | -------------- | -------------------------------------------------------------------- | +| `states[]` | array | Deployment-state entries. | +| `states[].token` | integer | Numeric token index assigned to the deployment. | +| `states[].spec` | object | Registration configuration submitted for the token. | +| `states[].spec.name` | string | Display name requested for the token. | +| `states[].spec.szDecimals` | integer | Number of decimal places accepted for order sizes. | +| `states[].spec.weiDecimals` | integer | Decimal places in the token’s smallest unit. | +| `states[].fullName` | string \| null | Full token name, or `null` when not supplied. | +| `states[].spots` | array | Spot-pair indices already registered for the token. | +| `states[].maxSupply` | integer | Maximum token supply permitted by the deployment. | +| `states[].hyperliquidityGenesisBalance` | string | Genesis allocation reserved for Hyperliquidity, as a decimal string. | +| `states[].totalGenesisBalanceWei` | string | Total genesis balance in the token’s smallest unit. | +| `states[].userGenesisBalances` | array | Address-and-balance pairs allocated at genesis. | +| `states[].existingTokenGenesisBalances` | array | Existing-token index and genesis-balance pairs. | +| `gasAuction` | object | Current Dutch-auction state for token deployment. | +| `gasAuction.startTimeSeconds` | integer | Unix time in seconds when the auction starts. | +| `gasAuction.durationSeconds` | integer | Length of the auction window in seconds. | +| `gasAuction.startGas` | string | Opening auction gas price in HYPE. | +| `gasAuction.currentGas` | string \| null | Current auction gas price, or `null` before it is available. | +| `gasAuction.endGas` | string \| null | Auction end gas price, or `null` while the auction is open. | + +## Response example + +```json +{ + "states": [ + { + "token": 150, + "spec": { "name": "HYPE", "szDecimals": 2, "weiDecimals": 8 }, + "fullName": "Hyperliquid", + "spots": [107], + "maxSupply": 1000000000 + } + ], + "gasAuction": { + "startTimeSeconds": 1733929200, + "durationSeconds": 111600, + "startGas": "181305.90046", + "currentGas": null, + "endGas": "181291.247358" + } +} +``` diff --git a/content/api-reference/data/hypercore/rest/token-deployment/spot-pair-deploy-auction-status.mdx b/content/api-reference/data/hypercore/rest/token-deployment/spot-pair-deploy-auction-status.mdx new file mode 100644 index 000000000..0720aad93 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/token-deployment/spot-pair-deploy-auction-status.mdx @@ -0,0 +1,46 @@ +--- +title: "Spot-pair deployment auction status" +description: "HyperCore private-preview documentation." +--- + + + +# Spot-pair deployment auction status + +Returns the current spot-pair deployment auction state. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | -------------------------------------- | +| `type` | string | Yes | Selects `spotPairDeployAuctionStatus`. | + +```json +{ + "type": "spotPairDeployAuctionStatus" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------------ | -------------- | ------------------------------------------------------------ | +| `startTimeSeconds` | integer | Unix time in seconds when the auction starts. | +| `durationSeconds` | integer | Length of the auction window in seconds. | +| `startGas` | string | Opening auction gas price in HYPE. | +| `currentGas` | string \| null | Current auction gas price, or `null` before it is available. | +| `endGas` | string \| null | Auction end gas price, or `null` while the auction is open. | + +## Response example + +```json +{ + "startTimeSeconds": 1755468000, + "durationSeconds": 111600, + "startGas": "500.0", + "currentGas": "500.0", + "endGas": null +} +``` diff --git a/content/api-reference/data/hypercore/rest/vaults/leading-vaults.mdx b/content/api-reference/data/hypercore/rest/vaults/leading-vaults.mdx new file mode 100644 index 000000000..5da8adbd6 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/vaults/leading-vaults.mdx @@ -0,0 +1,41 @@ +--- +title: "Leading vaults" +description: "HyperCore private-preview documentation." +--- + + + +# Leading vaults + +Returns the leading-vault collection associated with a user when it is available. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------- | +| `type` | string | Yes | Selects `leadingVaults`. | +| `user` | string | Yes | Account address to query. | + +```json +{ + "type": "leadingVaults", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------- | ------ | --------------------------------------------------------------- | +| `[]` | array | Leading-vault entries. | +| `[].` | object | No populated native response was available to establish fields. | + +## Response example + +```json +[] +``` + +The native API accepts the required `user` parameter on mainnet and testnet. The available captures returned empty arrays, so this page documents the confirmed request and direct-array response only; entry fields will be added after a populated native payload is observed. diff --git a/content/api-reference/data/hypercore/rest/vaults/user-vault-equities.mdx b/content/api-reference/data/hypercore/rest/vaults/user-vault-equities.mdx new file mode 100644 index 000000000..c97c944d3 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/vaults/user-vault-equities.mdx @@ -0,0 +1,45 @@ +--- +title: "User vault equities" +description: "HyperCore private-preview documentation." +--- + + + +# User vault equities + +Returns the current equity a user has in each vault. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `userVaultEquities`. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "userVaultEquities", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ----------------- | ------ | -------------------------------------------------- | +| `[]` | array | Current equity positions across the user's vaults. | +| `[].vaultAddress` | string | Onchain address that identifies the vault. | +| `[].equity` | string | User's current vault equity as a decimal string. | + +## Response example + +```json +[ + { + "vaultAddress": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303", + "equity": "742500.082809" + } +] +``` diff --git a/content/api-reference/data/hypercore/rest/vaults/vault-details.mdx b/content/api-reference/data/hypercore/rest/vaults/vault-details.mdx new file mode 100644 index 000000000..826c07e19 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/vaults/vault-details.mdx @@ -0,0 +1,92 @@ +--- +title: "Vault details" +description: "HyperCore private-preview documentation." +--- + + + +# Vault details + +Returns a vault's configuration, performance history, and follower state. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| -------------- | ------ | -------- | ------------------------------ | +| `type` | string | Yes | Selects `vaultDetails`. | +| `vaultAddress` | string | Yes | Vault address. | +| `user` | string | Yes | Master or sub-account address. | + +```json +{ + "type": "vaultDetails", + "vaultAddress": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303", + "user": "0x0000000000000000000000000000000000000000" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------------------------------ | -------------- | ------------------------------------------------------------------- | +| `name` | string | Display name assigned to the vault. | +| `vaultAddress` | string | Onchain address that identifies the vault. | +| `leader` | string | Address authorized to manage the vault's positions. | +| `description` | string | Vault-provided summary for prospective followers. | +| `portfolio` | array | Performance history by interval. | +| `portfolio[][0]` | string | Time interval label for the paired performance data. | +| `portfolio[][1].accountValueHistory` | array | Timestamped account-value observations for that interval. | +| `portfolio[][1].pnlHistory` | array | Timestamped profit-and-loss observations for that interval. | +| `portfolio[][1].vlm` | string | Trading volume recorded for that interval as a decimal string. | +| `apr` | number | Annualized return. | +| `followerState` | object \| null | Follower state for the requesting user, or `null` when none exists. | +| `leaderFraction` | number | Fraction of vault equity owned by the vault leader. | +| `leaderCommission` | number | Fraction of follower profit charged as leader commission. | +| `followers[]` | array | Accounts with an equity position in the vault. | +| `followers[].user` | string | Address of the account following the vault. | +| `followers[].vaultEquity` | string | Follower's vault equity as a decimal string. | +| `followers[].pnl` | string | Follower profit and loss for the current reporting period. | +| `followers[].allTimePnl` | string | Follower cumulative profit and loss since joining. | +| `followers[].daysFollowing` | integer | Whole days since the account began following the vault. | +| `followers[].vaultEntryTime` | integer | Time in milliseconds when the follower entered the vault. | +| `followers[].lockupUntil` | integer | Time in milliseconds before which the follower cannot withdraw. | +| `maxDistributable` | number | Maximum amount currently available for distribution. | +| `maxWithdrawable` | number | Maximum amount currently available for withdrawal. | +| `isClosed` | boolean | Whether the vault is closed. | +| `relationship` | object | Vault relationship metadata, such as its parent or child links. | +| `allowDeposits` | boolean | Whether deposits are allowed. | +| `alwaysCloseOnWithdraw` | boolean | Whether withdrawals close positions. | + +## Response example + +```json +{ + "name": "Test", + "vaultAddress": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303", + "leader": "0x677d831aef5328190852e24f13c46cac05f984e7", + "description": "Community-owned vault", + "portfolio": [ + [ + "day", + { + "accountValueHistory": [[1734397526634, "329265410.90790099"]], + "pnlHistory": [[1734397526634, "0.0"]], + "vlm": "0.0" + } + ] + ], + "apr": 0.36387129259090006, + "followerState": null, + "leaderFraction": 0.0007904828725729887, + "leaderCommission": 0, + "followers": [], + "maxDistributable": 94856870.164485, + "maxWithdrawable": 742557.680863, + "isClosed": false, + "relationship": { "type": "parent", "data": { "childAddresses": [] } }, + "allowDeposits": true, + "alwaysCloseOnWithdraw": false +} +``` diff --git a/content/api-reference/data/hypercore/rest/vaults/vault-summaries.mdx b/content/api-reference/data/hypercore/rest/vaults/vault-summaries.mdx new file mode 100644 index 000000000..dec46c8d4 --- /dev/null +++ b/content/api-reference/data/hypercore/rest/vaults/vault-summaries.mdx @@ -0,0 +1,39 @@ +--- +title: "Vault summaries" +description: "HyperCore private-preview documentation." +--- + + + +# Vault summaries + +Returns the native vault-summary collection when it is available for the requested network. + +## Request + +`POST /{apiKey}/info` + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------- | +| `type` | string | Yes | Selects `vaultSummaries`. | + +```json +{ + "type": "vaultSummaries" +} +``` + +## Response fields + +| Field | Type | Description | +| ------------- | ------ | --------------------------------------------------------------- | +| `[]` | array | Vault-summary entries. | +| `[].` | object | No populated native response was available to establish fields. | + +## Response example + +```json +[] +``` + +The native API accepted this request on mainnet and testnet, but the captures returned empty arrays. This page documents the confirmed request and direct-array response only; summary-entry fields will be added after a populated native payload is observed. diff --git a/content/api-reference/deploying-markets/overview.mdx b/content/api-reference/deploying-markets/overview.mdx new file mode 100644 index 000000000..2e9a67736 --- /dev/null +++ b/content/api-reference/deploying-markets/overview.mdx @@ -0,0 +1,59 @@ +--- +title: "Deploying Hyperliquid markets" +description: "How HIP-3 perpetual DEXs and HIP-4 outcome markets are deployed on Hyperliquid." +--- + + + +# Deploying Hyperliquid markets + +Hyperliquid supports two permissionless market-deployment primitives with different market models and operating responsibilities. + +## HIP-3 perpetual DEXs + +[HIP-3](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-3-builder-deployed-perpetuals) lets a deployer create a perpetual DEX. Each DEX has independent margining, order books, and deployer settings. + +A HIP-3 deployer defines its markets, including the oracle definition and contract specifications, then operates those markets by maintaining oracle prices, leverage limits, and settlement when needed. The current mainnet staking requirement is 500,000 HYPE and remains in place for at least 183 days after the DEX is deployed. + +Deploying and operating a HIP-3 market involves: + +* Selecting collateral, market specifications, and margin settings +* Registering the DEX and its assets through the [HIP-3 deployer actions](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/hip-3-deployer-actions) +* Operating a resilient oracle update process +* Setting market controls, including funding, open-interest, and fee settings +* Planning liquidity, monitoring, settlement, and incident response + +## HIP-4 outcome markets + +[HIP-4](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets) provides fully collateralized contracts that settle within a fixed range. It is designed for uses such as prediction markets and bounded options-like instruments rather than leveraged perpetual trading. + +Outcome markets have two sides, each represented by a token. Questions group outcomes where exactly one outcome settles to Yes and the others settle to No. The [HIP-4 deployer actions](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/hip-4-deployer-actions) describe template-based deployment: validators vote on templates, and deployers instantiate approved templates with their market values. + +## HIP-4 availability + +Permissionless HIP-4 deployment is available on testnet through approved outcome templates. The Foundation documents testnet limits of 10 active outcomes per deployer and 50 deployed outcomes per day. + +The current mainnet outcome metadata reports no outcome deployers, while the Foundation's HIP-4 overview describes the initial mainnet release as recurring outcomes. Alchemy prepares teams for testnet deployment and for permissionless mainnet deployment when it opens; Alchemy does not offer mainnet market deployment today. + +Each outcome deployer has a venue name. The Foundation requires that venue name to be unique, two to four lowercase ASCII letters, and subject to the same naming rules and shared namespace as HIP-3 perpetual DEX names. The outcome metadata response identifies deployers by both deployer address and venue. Query available templates with the outcomeTemplates info request. + +## Preparing to deploy + +A market deployment is an operating commitment as well as an onchain action. Establish the market definition, oracle and settlement design, collateral model, liquidity plan, monitoring, and response ownership before launch. + +Alchemy is standing up a Hyperliquid validator. This work is giving our team direct visibility into the technical requirements of market deployment as the validator comes online. + +For HIP-3, we work with partners to help prospective deployers source the required stake. After launch, we will work with an ecosystem of partners to support deployers across market operations, including oracle providers. + +## Next steps + +The [HyperCore REST reference](/docs/data/hypercore/rest-api) includes deployment +state, deployment-auction, outcome metadata, settled-outcome, and outcome-template +reads. + +Use the Foundation documentation for the action-level requirements and signed request formats: + +* [HIP-3 builder-deployed perpetuals](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-3-builder-deployed-perpetuals) +* [HIP-3 deployer actions](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/hip-3-deployer-actions) +* [HIP-4 outcome markets](https://hyperliquid.gitbook.io/hyperliquid-docs/hyperliquid-improvement-proposals-hips/hip-4-outcome-markets) +* [HIP-4 deployer actions](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/hip-4-deployer-actions) diff --git a/content/api-reference/hypercore-grpc/stream-bbo-book.mdx b/content/api-reference/hypercore-grpc/stream-bbo-book.mdx index 440a013fd..571c2e852 100644 --- a/content/api-reference/hypercore-grpc/stream-bbo-book.mdx +++ b/content/api-reference/hypercore-grpc/stream-bbo-book.mdx @@ -11,8 +11,6 @@ description: "HyperCore private-preview documentation." This is ideal for live price and spread displays, routing decisions, and applications where full depth is wasted bandwidth. -> The contract below is proposed and will be confirmed before general availability. - ## Overview * Emitted only when the best bid or the best ask changes for a market diff --git a/content/api-reference/hypercore-grpc/stream-blocks.mdx b/content/api-reference/hypercore-grpc/stream-blocks.mdx index b4bc04321..e814d9a57 100644 --- a/content/api-reference/hypercore-grpc/stream-blocks.mdx +++ b/content/api-reference/hypercore-grpc/stream-blocks.mdx @@ -12,8 +12,6 @@ the block contained, together with its execution results. This is ideal for full indexers, action and response analysis, deposit and transfer monitoring, and reconciliation against your own records. -> The contract below is proposed and will be confirmed before general availability. - ## Overview HyperCore produces a block roughly every 70 ms, and block numbers increment by exactly diff --git a/content/api-reference/hypercore-grpc/stream-l2-book-diff.mdx b/content/api-reference/hypercore-grpc/stream-l2-book-diff.mdx index b04405fed..78ee40d71 100644 --- a/content/api-reference/hypercore-grpc/stream-l2-book-diff.mdx +++ b/content/api-reference/hypercore-grpc/stream-l2-book-diff.mdx @@ -11,8 +11,6 @@ description: "HyperCore private-preview documentation." a local order book at a fraction of snapshot bandwidth. This is ideal for latency-sensitive consumers that need continuous book state. -> The contract below is proposed and will be confirmed before general availability. - ## Overview * Each message contains changes for the markets that changed in its block @@ -135,9 +133,9 @@ not match your current position for that market, you have a gap. A message flagged as a snapshot replaces your local state. Anything else is a diff that must chain onto your previous block. -If continuity is broken, a fresh snapshot is pushed to you. There is no separate -resynchronization message to handle and no epoch to track — receiving a snapshot is the -signal to discard local state and adopt it. +If continuity is broken, a fresh snapshot is pushed to you. The snapshot flag is the +only continuity signal you need to handle — receiving it means discard local state +and adopt the snapshot. 1. After applying each message, persist `cursor` and the per-market `seq`. 2. On reconnect, send `cursor`. diff --git a/content/api-reference/hypercore-grpc/stream-l2-book.mdx b/content/api-reference/hypercore-grpc/stream-l2-book.mdx index ba53727dc..5d244d4a2 100644 --- a/content/api-reference/hypercore-grpc/stream-l2-book.mdx +++ b/content/api-reference/hypercore-grpc/stream-l2-book.mdx @@ -12,8 +12,6 @@ each market whose book changed. This is ideal for order book displays, depth ana pricing, and applications that need current book state without maintaining it incrementally. -> The contract below is proposed and will be confirmed before general availability. - ## Overview * Every message is a complete snapshot for the market it names diff --git a/content/api-reference/hypercore-grpc/stream-l4-book-updates.mdx b/content/api-reference/hypercore-grpc/stream-l4-book-updates.mdx index ff9968185..a3517bf69 100644 --- a/content/api-reference/hypercore-grpc/stream-l4-book-updates.mdx +++ b/content/api-reference/hypercore-grpc/stream-l4-book-updates.mdx @@ -11,8 +11,6 @@ description: "HyperCore private-preview documentation." including its position in the price-level queue. This is ideal for market making, queue-position analysis, liquidity attribution, and reconstructing an exact book. -> The contract below is proposed and will be confirmed before general availability. - ## Overview * The first message after subscribing is a full snapshot: every resting order is delivered @@ -111,9 +109,9 @@ position that makes order-level consumption useful beyond aggregated levels. A message flagged as a snapshot replaces your local state. Anything else is a diff that must chain onto your previous block. -If continuity is broken, a fresh snapshot is pushed to you. There is no separate -resynchronization message to handle and no epoch to track — receiving a snapshot is the -signal to discard local state and adopt it. +If continuity is broken, a fresh snapshot is pushed to you. The snapshot flag is the +only continuity signal you need to handle — receiving it means discard local state +and adopt the snapshot. ## Choosing a book stream diff --git a/content/api-reference/hypercore-grpc/stream-l4-book.mdx b/content/api-reference/hypercore-grpc/stream-l4-book.mdx index 10317934b..88efd8034 100644 --- a/content/api-reference/hypercore-grpc/stream-l4-book.mdx +++ b/content/api-reference/hypercore-grpc/stream-l4-book.mdx @@ -7,6 +7,6 @@ description: "HyperCore private-preview documentation." # Stream L4 book -`StreamL4Book` is under evaluation. Consumers wanting order-level book data should use [StreamL4BookUpdates](/docs/chains/hypercore-grpc/api-reference/stream-l4-book-updates), which provides typed per-order diffs across multiple markets with queue-position information. This is ideal for consumers that need order-level book data. +`StreamL4Book` is under evaluation. -> The contract below is proposed and will be confirmed before general availability. +Consumers wanting order-level book data should use [StreamL4BookUpdates](/docs/chains/hypercore-grpc/api-reference/stream-l4-book-updates), which provides typed per-order diffs across multiple markets with queue-position information. This is ideal for consumers that need order-level book data. diff --git a/content/api-reference/hypercore-grpc/stream-tpsl-updates.mdx b/content/api-reference/hypercore-grpc/stream-tpsl-updates.mdx index de67f4c85..c01f7ca4b 100644 --- a/content/api-reference/hypercore-grpc/stream-tpsl-updates.mdx +++ b/content/api-reference/hypercore-grpc/stream-tpsl-updates.mdx @@ -11,8 +11,6 @@ description: "HyperCore private-preview documentation." orders. This is ideal for trigger heatmaps, stop and liquidation monitoring, frontend overlays, and alerting. -> The contract below is proposed and will be confirmed before general availability. - ## Overview * The first message after subscribing is a snapshot of all open trigger orders, delivered @@ -118,6 +116,6 @@ set. A message flagged as a snapshot replaces your local state. Anything else is a diff that must chain onto your previous block. -If continuity is broken, a fresh snapshot is pushed to you. There is no separate -resynchronization message to handle and no epoch to track — receiving a snapshot is the -signal to discard local state and adopt it. +If continuity is broken, a fresh snapshot is pushed to you. The snapshot flag is the +only continuity signal you need to handle — receiving it means discard local state +and adopt the snapshot. diff --git a/content/api-reference/hypercore-peering/overview.mdx b/content/api-reference/hypercore-peering/overview.mdx new file mode 100644 index 000000000..d8367ec36 --- /dev/null +++ b/content/api-reference/hypercore-peering/overview.mdx @@ -0,0 +1,192 @@ +--- +title: "HyperCore node peering" +description: "Dedicated peer connections for teams running their own Hyperliquid node." +--- + + + +# HyperCore node peering + +A Hyperliquid non-validating node receives data only as fast and as completely as its +peers allow. Node peering gives you dedicated, reserved peers on Alchemy +infrastructure in Tokyo, including uncommitted mempool transactions. + + + Peering provides no preferential access. Every peering customer receives the same + peer configuration, the same delivery, and the same price. + + +## Why peers matter + +Two properties of the Hyperliquid gossip network determine what a node can receive. + +**Mempool delivery requires an unbroken chain of configured peers.** Uncommitted +transactions reach your node only when `split_client_blocks` is enabled on every peer +between your node and the validating network. A peer without it forwards committed +blocks and nothing more, which is why most public peers cannot supply mempool data. + +**Public root peers are shared.** The Hyperliquid community operates a published list +of open root peers, discoverable through the `gossipRootIps` info endpoint. They are +free and work for committed blocks, but connection slots are contended, peers rotate, +and mempool delivery is not available. + +Peering addresses both: reserved slots that are not contended, and +`split_client_blocks` enabled end to end. + +## What you get + +* **Allowlisted peer connections** to Alchemy nodes, reserved for your node's public IP +* **Mempool delivery**, with `split_client_blocks` enabled through to the validating network +* **Tokyo placement**, colocated with the Alchemy Hyperliquid validator once we go live +* **99.99% uptime SLA** on peer availability, monitored and alerted +* **Direct engineer support**, including APAC hours + +## Capacity + +Peer slots are allowlisted per node IP and provisioned from reserved capacity rather +than shared public slots. Capacity scales with the number of connected peers; we add +infrastructure ahead of demand rather than oversubscribing existing slots. + +## Gossip priority + +Hyperliquid runs a Dutch auction for gossip read priority, and nodes may optionally +honor the resulting ordering when forwarding data to peers. The Hyperliquid +Foundation's non-validating node respects the auction ordering. + +If you have bid for a gossip priority slot, your position is preserved through our +peers rather than discarded. Priority ordering is the chain's mechanism, applied +uniformly — it is not an Alchemy allocation. + +## Pricing + +**$499 per month.** Flat, published, and identical for every customer. + +There is no volume tier, no negotiated rate, and no discount contingent on staking, +trading activity, or any other commercial relationship with Alchemy. Peering does not +require an Alchemy API plan. + +## Getting started + + + + +Email [abdul.manan@alchemy.com](mailto:abdul.manan@alchemy.com) with your +organization, your node's public IP address, and the region it runs in. We add your IP +to `reserved_peer_ips` on our nodes so incoming connections from your node are +always accepted. Provisioning takes two to five business days. + + + + +Add the peer addresses we return to `~/override_gossip_config.json`: + +```json +{ + "root_node_ips": [{ "Ip": "" }, { "Ip": "" }], + "try_new_peers": false, + "chain": "Mainnet", + "split_client_blocks": true +} +``` + +`try_new_peers: false` keeps your node on the reserved peers rather than drifting to +public ones. `split_client_blocks: true` enables mempool delivery; uncommitted +transactions are written to `~/hl/data/mempool_txs/{date}`. + + + + +Confirm `applied block X` lines appear in your node output and that files land in +`~/hl/data/mempool_txs/`. Mempool files contain actions only, not responses, since +those transactions have not yet been committed. + + + + +A seven business day evaluation period is available on request. + +## Node requirements + +Peering does not change what your node needs. The Hyperliquid non-validator baseline +is 16 vCPUs, 128 GB RAM, and 500 GB SSD on Ubuntu 24.04, with gossip ports 4001 and +4002 open publicly. Default settings produce roughly 100 GB of logs per day, and +enabling mempool capture adds to that materially. Size disk and retention before +provisioning. + +For lowest latency, run your node in Tokyo. + +## Specifications + + + +| Specification | Detail | +| --- | --- | +| Peer connections | Allowlisted per node IP via `reserved_peer_ips` | +| Region | Tokyo | +| Node type supported | Non-validating | +| Mempool | Included, `split_client_blocks` enabled end to end | +| Gossip priority | Auction ordering respected | +| Uptime SLA | 99.99% on peer availability | +| Support | Direct engineer email, APAC hours | +| Price | $499 per month, flat | +| Provisioning | 2–5 business days, engineer-provisioned | +| API plan required | No | + + + +## Peering or a managed API + +Peering is useful only if you already operate a Hyperliquid node. If you want the data +without running node infrastructure, use the HyperCore APIs. + +| | Node peering | HyperCore APIs | +| --- | --- | --- | +| **You run the node** | Yes | No | +| **What you connect to** | Reserved peer connections on Alchemy nodes | Managed endpoints | +| **Delivery** | Gossip: committed blocks and mempool | WebSocket, gRPC, REST, JSON-RPC | +| **Mempool** | Yes, to local disk | Not exposed | +| **Best for** | Teams already committed to their own node | Everyone else | + +## Frequently asked questions + + + + + +No. Reserved slots and end-to-end mempool configuration mean your node is not +competing for connections and is not missing data. They do not place you ahead of +other peers, and every peering customer receives the same configuration. + + + + + +Mempool delivery requires `split_client_blocks` enabled on every peer between your +node and the validating network, not only on your own node. Most public root peers +have not enabled it, so they forward committed blocks and nothing else. + + + + + +Availability of your reserved peer connections, monitored and alerted by the team +operating them. It does not cover your own node's uptime. + + + + + +Email us and we will update `reserved_peer_ips`. Allowlisting is per IP address, so +send the new one ahead of a planned migration to avoid an interruption. + + + + + +Yes, though `try_new_peers: false` is recommended while peered so your node stays on +the reserved connections. Public root peers remain discoverable through the +`gossipRootIps` info endpoint if you want them as a backstop. + + + + diff --git a/content/api-reference/websockets/hypercore/active-asset-context.mdx b/content/api-reference/websockets/hypercore/active-asset-context.mdx index 4d226273c..a59bb5254 100644 --- a/content/api-reference/websockets/hypercore/active-asset-context.mdx +++ b/content/api-reference/websockets/hypercore/active-asset-context.mdx @@ -54,15 +54,13 @@ description: "HyperCore private-preview documentation." ## Payload fields -The payload shape is proposed. - | Field | Type | Description | | --- | --- | --- | -| coin | string | Market identifier. | -| markPrice | string | Illustrative markPrice value. | -| oraclePrice | string | Illustrative oraclePrice value. | -| fundingRate | string | Illustrative fundingRate value. | -| openInterest | string | Illustrative openInterest value. | +| coin | string | Market symbol for the selected asset. | +| markPrice | string | Current mark price for the asset. | +| oraclePrice | string | Current oracle price for the asset. | +| fundingRate | string | Current funding rate for the perpetual market. | +| openInterest | string | Current aggregate open interest for the market. | ## Unsubscribe ```json { diff --git a/content/api-reference/websockets/hypercore/all-candles.mdx b/content/api-reference/websockets/hypercore/all-candles.mdx index 3d491e471..e683435b9 100644 --- a/content/api-reference/websockets/hypercore/all-candles.mdx +++ b/content/api-reference/websockets/hypercore/all-candles.mdx @@ -7,10 +7,9 @@ description: "HyperCore private-preview documentation." # allCandles stream -Multi-interval delivery and per-subscription interval limits are still being finalized to ensure reliable delivery at high event volumes. +Streams candles for the requested markets and intervals. ## Subscribe -> The values below illustrate the intended request shape. ```json { @@ -51,11 +50,15 @@ Multi-interval delivery and per-subscription interval limits are still being fin "interval": "1m", "candles": [ { - "coin": "BTC", - "openTime": 1780000000000, - "close": "100005.0", - "volume": "12.4", - "isFinal": false + "s": "BTC", + "t": 1780000000000, + "T": 1780000059999, + "o": "100000.0", + "h": "100010.0", + "l": "99995.0", + "c": "100005.0", + "v": "12.4", + "x": false } ] } @@ -64,18 +67,20 @@ Multi-interval delivery and per-subscription interval limits are still being fin ## Payload fields -The payload shape is proposed. - | Field | Type | Description | | --- | --- | --- | | interval | string | Candle interval. | | candles | array | Candle records. | | candles[] | object | Candle records. | -| candles[].coin | string | Market identifier. | -| candles[].openTime | integer | Illustrative openTime value. | -| candles[].close | string | Illustrative close value. | -| candles[].volume | string | Illustrative volume value. | -| candles[].isFinal | boolean | Finality indicator. | +| candles[].s | string | Market symbol for the candle. | +| candles[].t | integer | Start time of the candle interval, in milliseconds. | +| candles[].T | integer | End time of the candle interval, in milliseconds. | +| candles[].o | string | Opening price for the candle interval. | +| candles[].h | string | Highest traded price in the candle interval. | +| candles[].l | string | Lowest traded price in the candle interval. | +| candles[].c | string | Closing price for the candle interval. | +| candles[].v | string | Volume traded in the base asset during the candle interval. | +| candles[].x | boolean | Whether the candle is final. | ## Unsubscribe ```json { diff --git a/content/api-reference/websockets/hypercore/all-fills.mdx b/content/api-reference/websockets/hypercore/all-fills.mdx index 296ce69cf..3c01620c8 100644 --- a/content/api-reference/websockets/hypercore/all-fills.mdx +++ b/content/api-reference/websockets/hypercore/all-fills.mdx @@ -8,21 +8,19 @@ description: "HyperCore private-preview documentation." # allFills stream ## Subscribe -> The values below illustrate the intended request shape. ```json { "method": "subscribe", "subscription": { "type": "allFills", - "coins": [ - "BTC" - ] + "coins": ["BTC"] } } ``` ## Acknowledgement + ```json { "channel": "subscriptionResponse", @@ -45,12 +43,33 @@ description: "HyperCore private-preview documentation." "data": { "fills": [ { + "user": "0x1111111111111111111111111111111111111111", "coin": "BTC", "px": "100000.0", "sz": "0.01", "side": "B", - "tradeId": "trade_01", - "time": 1780000000000 + "time": 1780000000000, + "startPosition": "0.00", + "dir": "Open Long", + "closedPnl": "0.0", + "hash": "0xabc123", + "oid": 12345, + "crossed": false, + "fee": "0.20", + "tid": 87654321, + "liquidation": { + "liquidatedUser": "0x3333333333333333333333333333333333333333", + "markPx": "99990.0", + "method": "market" + }, + "feeToken": "USDC", + "builderFee": "0.01", + "cloid": "client-order-01", + "deployerFee": "0.01", + "priorityGas": "0.001", + "builder": "0x2222222222222222222222222222222222222222", + "twapId": null, + "txIndex": 3 } ] } @@ -59,30 +78,50 @@ description: "HyperCore private-preview documentation." ## Payload fields -The payload shape is proposed. - | Field | Type | Description | | --- | --- | --- | | fills | array | Fill records. | -| fills[] | object | Fill records. | -| fills[].coin | string | Market identifier. | -| fills[].px | string | Price value. | -| fills[].sz | string | Size value. | +| fills[] | object | Fill record. | +| fills[].user | string | User identifier for the fill. | +| Field | Type | Description | +| --- | --- | --- | +| fills[].coin | string | Market symbol for the fill. | +| fills[].px | string | Execution price. | +| fills[].sz | string | Executed size. | | fills[].side | string | Side code: A is ask/sell; B is bid/buy. | -| fills[].tradeId | string | Illustrative tradeId value. | -| fills[].time | integer | Source time. | +| fills[].time | integer | Time of the fill, in milliseconds. | +| fills[].startPosition | string | Position size immediately before the fill. | +| fills[].dir | string | Display direction for the fill. | +| fills[].closedPnl | string | Realized profit or loss closed by the fill. | +| fills[].hash | string | Layer-1 transaction hash for the fill. | +| fills[].oid | integer | Identifier of the order that produced the fill. | +| fills[].crossed | boolean | Whether the order crossed the spread. | +| fills[].fee | string | Fee charged for the fill; a negative value is a rebate. | +| fills[].tid | integer | Trade identifier. | +| fills[].liquidation | object or null | Liquidation details when the fill is a liquidation. | +| fills[].liquidation.liquidatedUser | string | Address of the liquidated user, when present. | +| fills[].liquidation.markPx | string | Mark price at liquidation. | +| fills[].liquidation.method | string | Liquidation method: market or backstop. | +| fills[].feeToken | string | Token in which the fee was paid. | +| fills[].builderFee | string | Amount paid to the builder and included in fee. | +| fills[].cloid | string or null | Client order identifier. | +| fills[].deployerFee | string | Fee paid to the HIP-3 deployer. | +| fills[].priorityGas | string or null | Order-priority fee paid in HYPE. | +| fills[].builder | string | Builder address associated with the fill. | +| fills[].twapId | integer or null | Identifier of the TWAP that produced the fill. | +| fills[].txIndex | integer | Transaction index of the fill within its block. | ## Unsubscribe + ```json { "method": "unsubscribe", "subscription": { "type": "allFills", - "coins": [ - "BTC" - ] + "coins": ["BTC"] } } ``` + ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. diff --git a/content/api-reference/websockets/hypercore/all-isolated-margin-updates.mdx b/content/api-reference/websockets/hypercore/all-isolated-margin-updates.mdx index cc2a1a885..4aae295d0 100644 --- a/content/api-reference/websockets/hypercore/all-isolated-margin-updates.mdx +++ b/content/api-reference/websockets/hypercore/all-isolated-margin-updates.mdx @@ -7,7 +7,7 @@ description: "HyperCore private-preview documentation." # allIsolatedMarginUpdates stream -Carries isolated-margin updates across the available stream scope. +Streams isolated-margin and isolated-margin top-up updates across users. ## Subscribe @@ -19,17 +19,52 @@ Carries isolated-margin updates across the available stream scope. } } ``` -## Acknowledgement + +## Event envelope ```json { - "channel": "subscriptionResponse", - "data": { - "type": "allIsolatedMarginUpdates" - } + "type": "allIsolatedMarginUpdates", + "channel": "allIsolatedMarginUpdates", + "seq": 1, + "cursor": 1704067201000, + "updates": [{ + "update_type": "isolated_margin", + "time": 1704067201000, + "user": "0x1111111111111111111111111111111111111111", + "coin": "xyz:GOLD", + "is_buy": false, + "ntli": "0.223223", + "tx_index": 0 + }] } ``` +An isolated-margin top-up update uses update_type top_up_isolated_margin and includes target_leverage instead of is_buy and ntli. + +## Payload fields + +| Field | Type | Description | Source tier | +| --- | --- | --- | --- | +| type | string | Event type. | Extended-provider | +| channel | string | Routing channel for the event. | Extended-provider | +| seq | integer | Monotonic sequence number for the stream. | Extended-provider | +| cursor | integer | Resume cursor for the event position. | Extended-provider | +| updates | array | Margin update records. | Extended-provider | +| updates[] | object | Isolated-margin or isolated-margin top-up record. | Extended-provider | +| updates[].update_type | string | Update discriminator: isolated_margin or top_up_isolated_margin. | Extended-provider | +| updates[].time | integer | Event time in milliseconds. | Extended-provider | +| updates[].user | string | Address whose margin setting changed. | Extended-provider | +| updates[].coin | string | Market identifier. | Extended-provider | +| updates[].is_buy | boolean | Isolated-margin side for an isolated_margin update. | Extended-provider | +| updates[].ntli | string | Isolated-margin notional value for an isolated_margin update. | Extended-provider | +| updates[].target_leverage | string | Target leverage for a top_up_isolated_margin update. | Extended-provider | +| updates[].tx_index | integer | Index of the transaction within its block. | Extended-provider | + +## Behavior + +The stream batches update records. The cursor identifies the event position for resumption. + ## Unsubscribe ```json @@ -41,9 +76,6 @@ Carries isolated-margin updates across the available stream scope. } ``` -## Payload schema - -The payload schema is pending engineering confirmation. ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. Store and return the cursor unmodified. diff --git a/content/api-reference/websockets/hypercore/all-leverage-updates.mdx b/content/api-reference/websockets/hypercore/all-leverage-updates.mdx index f73d11cab..a8e500303 100644 --- a/content/api-reference/websockets/hypercore/all-leverage-updates.mdx +++ b/content/api-reference/websockets/hypercore/all-leverage-updates.mdx @@ -7,7 +7,7 @@ description: "HyperCore private-preview documentation." # allLeverageUpdates stream -Carries leverage-setting updates across the available stream scope. +Streams leverage, isolated-margin, and isolated-margin top-up updates across users. ## Subscribe @@ -19,17 +19,54 @@ Carries leverage-setting updates across the available stream scope. } } ``` -## Acknowledgement + +## Event envelope ```json { - "channel": "subscriptionResponse", - "data": { - "type": "allLeverageUpdates" - } + "type": "allLeverageUpdates", + "channel": "allLeverageUpdates", + "seq": 1, + "cursor": 1704067200000, + "updates": [{ + "update_type": "leverage", + "time": 1704067200000, + "user": "0x1111111111111111111111111111111111111111", + "coin": "ETH", + "is_cross": true, + "leverage": 10, + "tx_index": 0 + }] } ``` +The stream also emits isolated_margin records with is_buy and ntli, and top_up_isolated_margin records with target_leverage. + +## Payload fields + +| Field | Type | Description | Source tier | +| --- | --- | --- | --- | +| type | string | Event type. | Extended-provider | +| channel | string | Routing channel for the event. | Extended-provider | +| seq | integer | Monotonic sequence number for the stream. | Extended-provider | +| cursor | integer | Resume cursor for the event position. | Extended-provider | +| updates | array | Leverage-setting update records. | Extended-provider | +| updates[] | object | Leverage, isolated-margin, or isolated-margin top-up record. | Extended-provider | +| updates[].update_type | string | Update discriminator: leverage, isolated_margin, or top_up_isolated_margin. | Extended-provider | +| updates[].time | integer | Event time in milliseconds. | Extended-provider | +| updates[].user | string | Address whose setting changed. | Extended-provider | +| updates[].coin | string | Market identifier. | Extended-provider | +| updates[].is_cross | boolean | Whether a leverage update uses cross margin. | Extended-provider | +| updates[].leverage | integer | Leverage setting for a leverage update. | Extended-provider | +| updates[].is_buy | boolean | Isolated-margin side for an isolated_margin update. | Extended-provider | +| updates[].ntli | string | Isolated-margin notional value for an isolated_margin update. | Extended-provider | +| updates[].target_leverage | string | Target leverage for a top_up_isolated_margin update. | Extended-provider | +| updates[].tx_index | integer | Index of the transaction within its block. | Extended-provider | + +## Behavior + +The stream batches update records. The cursor identifies the event position for resumption. + ## Unsubscribe ```json @@ -41,9 +78,6 @@ Carries leverage-setting updates across the available stream scope. } ``` -## Payload schema - -The payload schema is pending engineering confirmation. ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. Store and return the cursor unmodified. diff --git a/content/api-reference/websockets/hypercore/all-twap-status-updates.mdx b/content/api-reference/websockets/hypercore/all-twap-status-updates.mdx index 05157f577..e7732fb42 100644 --- a/content/api-reference/websockets/hypercore/all-twap-status-updates.mdx +++ b/content/api-reference/websockets/hypercore/all-twap-status-updates.mdx @@ -8,21 +8,19 @@ description: "HyperCore private-preview documentation." # allTwapStatusUpdates stream ## Subscribe -> The values below illustrate the intended request shape. ```json { "method": "subscribe", "subscription": { "type": "allTwapStatusUpdates", - "coins": [ - "BTC" - ] + "coins": ["BTC"] } } ``` ## Acknowledgement + ```json { "channel": "subscriptionResponse", @@ -43,38 +41,63 @@ description: "HyperCore private-preview documentation." "blockTime": 1780000000000, "cursor": "", "data": { - "twapId": "twap_01", + "time": "2025-09-03T10:48:14.285201806", + "createdAt": 1756896494285, + "twapId": 12345, + "user": "0x1111111111111111111111111111111111111111", "coin": "BTC", - "status": "active", - "executedSize": "0.20", - "remainingSize": "0.80" + "side": "B", + "status": "activated", + "statusMessage": null, + "sz": "1.00", + "minutes": 60, + "reduceOnly": false, + "randomize": true, + "executedSz": "0.20", + "executedNtl": "20000.0", + "txIndex": 3, + "triggerPx": "100000.0", + "triggerAbove": true, + "stopPx": "95000.0" } } ``` ## Payload fields -The payload shape is proposed. - | Field | Type | Description | | --- | --- | --- | -| twapId | string | Illustrative twapId value. | -| coin | string | Market identifier. | -| status | string | Illustrative status value. | -| executedSize | string | Illustrative executedSize value. | -| remainingSize | string | Illustrative remainingSize value. | +| time | string | Time of the status update. | +| createdAt | integer | Time the TWAP was created, in milliseconds. | +| twapId | integer | Identifier for the TWAP order. | +| user | string | Address that owns the TWAP order. | +| coin | string | Market symbol for the TWAP order. | +| side | string | Side code: A is ask/sell; B is bid/buy. | +| status | string | TWAP status: activated, finished, terminated, stopped, waitingForTrigger, or error. | +| statusMessage | string or null | Status detail; populated for an error status. | +| sz | string | Total TWAP size. | +| minutes | integer | Duration of the TWAP in minutes. | +| reduceOnly | boolean | Whether the TWAP only reduces an existing position. | +| randomize | boolean | Whether the TWAP schedule is randomized. | +| executedSz | string | Cumulative size executed by the TWAP order. | +| executedNtl | string | Cumulative notional executed by the TWAP order. | +| txIndex | integer | Transaction index of the update within its block. | +| triggerPx | string | Trigger price for a trigger TWAP. | +| triggerAbove | boolean | Direction that activates a trigger TWAP relative to triggerPx. | +| stopPx | string | Stop price attached to the TWAP. | + ## Unsubscribe + ```json { "method": "unsubscribe", "subscription": { "type": "allTwapStatusUpdates", - "coins": [ - "BTC" - ] + "coins": ["BTC"] } } ``` + ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. diff --git a/content/api-reference/websockets/hypercore/builder-fills.mdx b/content/api-reference/websockets/hypercore/builder-fills.mdx index 2ddfe1988..d57cdbe72 100644 --- a/content/api-reference/websockets/hypercore/builder-fills.mdx +++ b/content/api-reference/websockets/hypercore/builder-fills.mdx @@ -8,21 +8,19 @@ description: "HyperCore private-preview documentation." # builderFills stream ## Subscribe -> The values below illustrate the intended request shape. ```json { "method": "subscribe", "subscription": { "type": "builderFills", - "builders": [ - "0x2222222222222222222222222222222222222222" - ] + "builders": ["0x2222222222222222222222222222222222222222"] } } ``` ## Acknowledgement + ```json { "channel": "subscriptionResponse", @@ -45,11 +43,33 @@ description: "HyperCore private-preview documentation." "data": { "fills": [ { - "builder": "0x2222222222222222222222222222222222222222", + "user": "0x1111111111111111111111111111111111111111", "coin": "BTC", "px": "100000.0", "sz": "0.01", - "tradeId": "trade_03" + "side": "B", + "time": 1780000000000, + "startPosition": "0.00", + "dir": "Open Long", + "closedPnl": "0.0", + "hash": "0xabc123", + "oid": 12345, + "crossed": false, + "fee": "0.20", + "tid": 87654321, + "liquidation": { + "liquidatedUser": "0x3333333333333333333333333333333333333333", + "markPx": "99990.0", + "method": "market" + }, + "feeToken": "USDC", + "builderFee": "0.01", + "cloid": "client-order-01", + "deployerFee": "0.01", + "priorityGas": "0.001", + "builder": "0x2222222222222222222222222222222222222222", + "twapId": null, + "txIndex": 3 } ] } @@ -58,29 +78,50 @@ description: "HyperCore private-preview documentation." ## Payload fields -The payload shape is proposed. - | Field | Type | Description | | --- | --- | --- | | fills | array | Fill records. | -| fills[] | object | Fill records. | -| fills[].builder | string | Illustrative builder value. | -| fills[].coin | string | Market identifier. | -| fills[].px | string | Price value. | -| fills[].sz | string | Size value. | -| fills[].tradeId | string | Illustrative tradeId value. | +| fills[] | object | Fill record. | +| fills[].user | string | User identifier for the fill. | +| Field | Type | Description | +| --- | --- | --- | +| fills[].coin | string | Market symbol for the fill. | +| fills[].px | string | Execution price. | +| fills[].sz | string | Executed size. | +| fills[].side | string | Side code: A is ask/sell; B is bid/buy. | +| fills[].time | integer | Time of the fill, in milliseconds. | +| fills[].startPosition | string | Position size immediately before the fill. | +| fills[].dir | string | Display direction for the fill. | +| fills[].closedPnl | string | Realized profit or loss closed by the fill. | +| fills[].hash | string | Layer-1 transaction hash for the fill. | +| fills[].oid | integer | Identifier of the order that produced the fill. | +| fills[].crossed | boolean | Whether the order crossed the spread. | +| fills[].fee | string | Fee charged for the fill; a negative value is a rebate. | +| fills[].tid | integer | Trade identifier. | +| fills[].liquidation | object or null | Liquidation details when the fill is a liquidation. | +| fills[].liquidation.liquidatedUser | string | Address of the liquidated user, when present. | +| fills[].liquidation.markPx | string | Mark price at liquidation. | +| fills[].liquidation.method | string | Liquidation method: market or backstop. | +| fills[].feeToken | string | Token in which the fee was paid. | +| fills[].builderFee | string | Amount paid to the builder and included in fee. | +| fills[].cloid | string or null | Client order identifier. | +| fills[].deployerFee | string | Fee paid to the HIP-3 deployer. | +| fills[].priorityGas | string or null | Order-priority fee paid in HYPE. | +| fills[].builder | string | Builder address associated with the fill. | +| fills[].twapId | integer or null | Identifier of the TWAP that produced the fill. | +| fills[].txIndex | integer | Transaction index of the fill within its block. | ## Unsubscribe + ```json { "method": "unsubscribe", "subscription": { "type": "builderFills", - "builders": [ - "0x2222222222222222222222222222222222222222" - ] + "builders": ["0x2222222222222222222222222222222222222222"] } } ``` + ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. diff --git a/content/api-reference/websockets/hypercore/builder-liquidation.mdx b/content/api-reference/websockets/hypercore/builder-liquidation.mdx index 3e014e935..ef48ea4f8 100644 --- a/content/api-reference/websockets/hypercore/builder-liquidation.mdx +++ b/content/api-reference/websockets/hypercore/builder-liquidation.mdx @@ -1,13 +1,13 @@ --- -title: "builderLiquidation stream" +title: "builderLiquidations stream" description: "HyperCore private-preview documentation." --- -# builderLiquidation stream +# builderLiquidations stream -Intended to carry liquidation activity in builder contexts. The subscription scope is pending confirmation. +Streams liquidation fills associated with a builder. ## Subscribe @@ -15,35 +15,108 @@ Intended to carry liquidation activity in builder contexts. The subscription sco { "method": "subscribe", "subscription": { - "type": "builderLiquidation" + "type": "builderLiquidations", + "builder": "0x2222222222222222222222222222222222222222", + "aggregateByTime": true } } ``` -## Acknowledgement + +## Event envelope ```json { - "channel": "subscriptionResponse", - "data": { - "type": "builderLiquidation" - } + "type": "builderLiquidations", + "channel": "builderLiquidations", + "seq": 1, + "cursor": "500:1704067200000:3", + "liquidations": [[ + "0x1111111111111111111111111111111111111111", + { + "coin": "ETH", + "px": "2150.50", + "sz": "1.5", + "side": "B", + "time": 1704067200000, + "startPosition": "1.5", + "dir": "Open Long", + "closedPnl": "125.50", + "hash": "0xabc...def", + "oid": 12345678, + "crossed": false, + "fee": "2.50", + "tid": 87654321, + "cloid": "client-123", + "builderFee": null, + "deployerFee": null, + "feeToken": "USDC", + "builder": "0x2222222222222222222222222222222222222222", + "twapId": null, + "txIndex": 1, + "liquidation": { + "liquidatedUser": "0x3333333333333333333333333333333333333333", + "markPx": "2148.00", + "method": "market" + } + } + ]] } ``` +## Payload fields + +| Field | Type | Description | Source tier | +| --- | --- | --- | --- | +| type | string | Event type. | Extended-provider | +| channel | string | Routing channel for the event. | Extended-provider | +| seq | integer | Monotonic sequence number for the stream. | Extended-provider | +| cursor | string | Resume cursor for the event position. | Extended-provider | +| liquidations | array | Pairs of user address and liquidation fill. | Extended-provider | +| liquidations[] | tuple | User address followed by a liquidation fill. | Extended-provider | +| liquidations[]\[0] | string | Address associated with the fill. | Extended-provider | +| liquidations[]\[1] | object | Liquidation fill record. | Extended-provider | +| liquidations[]\[1].coin | string | Market symbol. | Foundation-native | +| liquidations[]\[1].px | string | Fill price. | Foundation-native | +| liquidations[]\[1].sz | string | Filled size. | Foundation-native | +| liquidations[]\[1].side | string | Side code: A is ask/sell; B is bid/buy. | Foundation-native | +| liquidations[]\[1].time | integer | Fill time in milliseconds. | Foundation-native | +| liquidations[]\[1].startPosition | string | Position size before the fill. | Foundation-native | +| liquidations[]\[1].dir | string | Position-direction classification for the fill. | Foundation-native | +| liquidations[]\[1].closedPnl | string | Realized profit and loss from the fill. | Foundation-native | +| liquidations[]\[1].hash | string | Transaction hash containing the fill. | Foundation-native | +| liquidations[]\[1].oid | integer | Order identifier. | Foundation-native | +| liquidations[]\[1].crossed | boolean | Whether the fill crossed the book. | Foundation-native | +| liquidations[]\[1].fee | string | Fee charged for the fill. | Foundation-native | +| liquidations[]\[1].tid | integer | Trade identifier. | Foundation-native | +| liquidations[]\[1].cloid | string | Client-supplied order identifier, when present. | Extended-provider | +| liquidations[]\[1].builderFee | string | Builder fee charged for the fill, when present. | Foundation-native | +| liquidations[]\[1].deployerFee | string | Deployer fee charged for the fill, when present. | Extended-provider | +| liquidations[]\[1].feeToken | string | Token used to pay the fee. | Foundation-native | +| liquidations[]\[1].builder | string | Builder address associated with the fill. | Extended-provider | +| liquidations[]\[1].twapId | integer \| null | TWAP identifier, when the fill belongs to a TWAP. | Extended-provider | +| liquidations[]\[1].txIndex | integer | Index of the transaction within its block. | Extended-provider | +| liquidations[]\[1].liquidation | object | Liquidation details. | Extended-provider | +| liquidations[]\[1].liquidation.liquidatedUser | string | Address of the liquidated user. | Extended-provider | +| liquidations[]\[1].liquidation.markPx | string | Mark price at liquidation. | Extended-provider | +| liquidations[]\[1].liquidation.method | string | Liquidation method: market or backstop. | Extended-provider | + +## Behavior + +The stream batches liquidation fills for the requested builder. The aggregateByTime parameter controls time aggregation, and the cursor identifies the event position for resumption. + ## Unsubscribe ```json { "method": "unsubscribe", "subscription": { - "type": "builderLiquidation" + "type": "builderLiquidations", + "builder": "0x2222222222222222222222222222222222222222", + "aggregateByTime": true } } ``` -## Payload schema - -The payload schema is pending engineering confirmation. ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. Store and return the cursor unmodified. diff --git a/content/api-reference/websockets/hypercore/builder-order-updates.mdx b/content/api-reference/websockets/hypercore/builder-order-updates.mdx index efadde054..745656dcf 100644 --- a/content/api-reference/websockets/hypercore/builder-order-updates.mdx +++ b/content/api-reference/websockets/hypercore/builder-order-updates.mdx @@ -8,21 +8,19 @@ description: "HyperCore private-preview documentation." # builderOrderUpdates stream ## Subscribe -> The values below illustrate the intended request shape. ```json { "method": "subscribe", "subscription": { "type": "builderOrderUpdates", - "builders": [ - "0x2222222222222222222222222222222222222222" - ] + "builders": ["0x2222222222222222222222222222222222222222"] } } ``` ## Acknowledgement + ```json { "channel": "subscriptionResponse", @@ -43,44 +41,80 @@ description: "HyperCore private-preview documentation." "blockTime": 1780000000000, "cursor": "", "data": { - "orders": [ - { - "builder": "0x2222222222222222222222222222222222222222", - "orderId": "12345", + "orders": [{ + "time": "2024-01-01T00:00:00.000000000", + "user": "0x1111111111111111111111111111111111111111", + "hash": "0xabc...def", + "builder": { "b": "0x2222222222222222222222222222222222222222", "f": 100 }, + "status": "filled", + "txIndex": 3, + "statusTimestamp": 1780000000000, + "order": { + "oid": 12345, "coin": "BTC", - "status": "filled", - "filledSize": "0.10" + "side": "B", + "limitPx": "100000.0", + "sz": "0.10", + "timestamp": 1780000000000, + "triggerCondition": "N/A", + "isTrigger": false, + "triggerPx": "0.0", + "children": [], + "isPositionTpsl": false, + "reduceOnly": false, + "orderType": "Limit", + "origSz": "0.10", + "tif": "Gtc", + "cloid": null } - ] + }] } } ``` ## Payload fields -The payload shape is proposed. +| Field | Type | Description | Source tier | +| --- | --- | --- | --- | +| orders | array | Order status records. | Our own choice | +| orders[] | object | Order status record. | Our own choice | +| orders[].time | string | Time the node recorded the order-status event. | Foundation-native | +| orders[].user | string | User identifier. | Foundation-native | +| orders[].hash | string | Transaction hash associated with the update. | Extended-provider | +| orders[].builder | object | Builder metadata for the update, containing the builder address and fee rate. | Extended-provider | +| orders[].status | string | Current state of the order. | Foundation-native | +| orders[].txIndex | integer | Index of the transaction within its block. | Extended-provider | +| orders[].statusTimestamp | integer | Milliseconds timestamp for the status update. | Foundation-native | +| orders[].order | object | Order fields. | Foundation-native | +| orders[].order.oid | integer | Identifier assigned to the order. | Foundation-native | +| orders[].order.coin | string | Market symbol for the order. | Foundation-native | +| orders[].order.side | string | Side code: A is ask/sell; B is bid/buy. | Foundation-native | +| orders[].order.limitPx | string | Limit price for the order. | Foundation-native | +| orders[].order.sz | string | Filled size for the order status. | Foundation-native | +| orders[].order.timestamp | integer | Milliseconds timestamp when the order was created. | Foundation-native | +| orders[].order.triggerCondition | string | Condition that controls trigger-order execution. | Foundation-native | +| orders[].order.isTrigger | boolean | Whether the order is a trigger order. | Foundation-native | +| orders[].order.triggerPx | string | Price that activates a trigger order. | Foundation-native | +| orders[].order.children | array | Child orders associated with the order. | Foundation-native | +| orders[].order.isPositionTpsl | boolean | Whether the order is a position take-profit or stop-loss order. | Foundation-native | +| orders[].order.reduceOnly | boolean | Whether execution can only reduce the position. | Foundation-native | +| orders[].order.orderType | string | Order type. | Foundation-native | +| orders[].order.origSz | string | Original order size. | Foundation-native | +| orders[].order.tif | string | Time-in-force instruction. | Foundation-native | +| orders[].order.cloid | string \| null | Client-supplied order identifier, when present. | Foundation-native | -| Field | Type | Description | -| --- | --- | --- | -| orders | array | Order records. | -| orders[] | object | Order records. | -| orders[].builder | string | Illustrative builder value. | -| orders[].orderId | string | Illustrative orderId value. | -| orders[].coin | string | Market identifier. | -| orders[].status | string | Illustrative status value. | -| orders[].filledSize | string | Illustrative filledSize value. | ## Unsubscribe + ```json { "method": "unsubscribe", "subscription": { "type": "builderOrderUpdates", - "builders": [ - "0x2222222222222222222222222222222222222222" - ] + "builders": ["0x2222222222222222222222222222222222222222"] } } ``` + ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. diff --git a/content/api-reference/websockets/hypercore/candles.mdx b/content/api-reference/websockets/hypercore/candles.mdx index 80409e462..d9ad645c9 100644 --- a/content/api-reference/websockets/hypercore/candles.mdx +++ b/content/api-reference/websockets/hypercore/candles.mdx @@ -62,19 +62,17 @@ description: "HyperCore private-preview documentation." ## Payload fields -The payload shape is proposed. - | Field | Type | Description | | --- | --- | --- | -| coin | string | Market identifier. | +| coin | string | Market symbol for the candle. | | interval | string | Candle interval. | -| openTime | integer | Illustrative openTime value. | -| closeTime | integer | Illustrative closeTime value. | -| open | string | Illustrative open value. | -| high | string | Illustrative high value. | -| low | string | Illustrative low value. | -| close | string | Illustrative close value. | -| volume | string | Illustrative volume value. | +| openTime | integer | Start time of the candle interval, in milliseconds. | +| closeTime | integer | End time of the candle interval, in milliseconds. | +| open | string | Opening price for the candle interval. | +| high | string | Highest price during the candle interval. | +| low | string | Lowest price during the candle interval. | +| close | string | Closing price for the candle interval. | +| volume | string | Volume traded in the base asset during the candle interval. | | isFinal | boolean | Finality indicator. | ## Unsubscribe ```json diff --git a/content/api-reference/websockets/hypercore/funding-rates.mdx b/content/api-reference/websockets/hypercore/funding-rates.mdx index a73a598c1..22e361c14 100644 --- a/content/api-reference/websockets/hypercore/funding-rates.mdx +++ b/content/api-reference/websockets/hypercore/funding-rates.mdx @@ -8,21 +8,19 @@ description: "HyperCore private-preview documentation." # fundingRates stream ## Subscribe -> The values below illustrate the intended request shape. ```json { "method": "subscribe", "subscription": { "type": "fundingRates", - "coins": [ - "BTC" - ] + "coins": ["BTC"] } } ``` ## Acknowledgement + ```json { "channel": "subscriptionResponse", @@ -33,8 +31,6 @@ description: "HyperCore private-preview documentation." } ``` -Whether an event includes `nextFundingTime` is pending verification. - ## Event envelope ```json @@ -46,33 +42,30 @@ Whether an event includes `nextFundingTime` is pending verification. "cursor": "", "data": { "coin": "BTC", - "fundingRate": "0.00001", - "nextFundingTime": 1780003600000 + "fundingRate": "0.00001" } } ``` ## Payload fields -The payload shape is proposed. - | Field | Type | Description | | --- | --- | --- | -| coin | string | Market identifier. | -| fundingRate | string | Illustrative fundingRate value. | -| nextFundingTime | integer | Pending verification; shown only in the illustrative payload. | +| coin | string | Market symbol for the funding update. | +| fundingRate | string | Funding rate for the market. | + ## Unsubscribe + ```json { "method": "unsubscribe", "subscription": { "type": "fundingRates", - "coins": [ - "BTC" - ] + "coins": ["BTC"] } } ``` + ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. diff --git a/content/api-reference/websockets/hypercore/l2-book-diff.mdx b/content/api-reference/websockets/hypercore/l2-book-diff.mdx index 35b0de8c6..7b0fa7553 100644 --- a/content/api-reference/websockets/hypercore/l2-book-diff.mdx +++ b/content/api-reference/websockets/hypercore/l2-book-diff.mdx @@ -11,29 +11,41 @@ description: "HyperCore private-preview documentation." local order book without receiving a complete snapshot on every update. This is ideal for latency-sensitive consumers needing continuous book state. -For the corresponding gRPC diff stream, see [StreamL2BookDiff](/docs/chains/hypercore-grpc/api-reference/stream-l2-book-diff). [l2Book](/docs/chains/websockets/hypercore/streams/l2-book) is the snapshot representation. +For the corresponding gRPC diff stream, see [StreamL2BookDiff](/docs/chains/hypercore-grpc/api-reference/stream-l2-book-diff). [l2Book](/docs/chains/websockets/hypercore/streams/l2-book) provides standalone snapshots for displays; it is not a bootstrap source for a diff-maintained book. ## Subscribe ```json -{"method":"subscribe","subscription":{"type":"l2BookDiff","coins":["BTC","ETH"],"nSigFigs":5,"mantissa":2,"nLevels":20}} +{ + "method": "subscribe", + "subscription": { + "type": "l2BookDiff", + "coins": ["BTC", "ETH"], + "nSigFigs": 5, + "mantissa": 2, + "nLevels": 20 + } +} ``` Use `marketTypes` instead of `coins` to subscribe to all markets of selected types: ```json -{"method":"subscribe","subscription":{"type":"l2BookDiff","marketTypes":["spot"]}} +{ + "method": "subscribe", + "subscription": { "type": "l2BookDiff", "marketTypes": ["spot"] } +} ``` ## Subscription parameters -| Parameter | Type | Required | Source | Description | -| --- | --- | --- | --- | --- | -| `coins` | string[] | No | Alchemy extension | Markets to subscribe to. Omit to subscribe to every market of the types in `marketTypes`, which defaults to perpetuals. The native API takes a single `coin` per subscription; the plural array is an Alchemy extension. | -| `marketTypes` | string[] | No | Alchemy extension | Restricts delivery by market type. Accepted values: `perp`, `spot`, `outcome`, or `*`. Defaults to `["perp"]`. Rejected if combined with `coins`. | -| `nSigFigs` | number | No | Foundation native | Aggregate price levels to N significant figures. Accepted values: `2`, `3`, `4`, `5`. | -| `mantissa` | number | No | Foundation native | Snap prices to a mantissa step. Accepted values: `2` or `5`. Valid only when `nSigFigs` is `5`. | -| `nLevels` | number | No | Alchemy extension | Levels per side: `1`, `10`, `20` (default), or `50`. | +| Parameter | Type | Required | Source | Description | +| ------------- | -------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `coins` | string[] | No | Alchemy extension | Markets to subscribe to. Omit to subscribe to every market of the types in `marketTypes`, which defaults to perpetuals. The native API takes a single `coin` per subscription; the plural array is an Alchemy extension. | +| `marketTypes` | string[] | No | Alchemy extension | Restricts delivery by market type. Accepted values: `perp`, `spot`, `outcome`, or `*`. Defaults to `["perp"]`. Rejected if combined with `coins`. | +| `nSigFigs` | number | No | Foundation native | Aggregate price levels to N significant figures. Accepted values: `2`, `3`, `4`, `5`. | +| `mantissa` | number | No | Foundation native | Snap prices to a mantissa step. Accepted values: `2` or `5`. Valid only when `nSigFigs` is `5`. | +| `nLevels` | number | No | Alchemy extension | Levels per side: `1`, `10`, `20` (default), or `50`. | The default never grows. New market types must be added to `marketTypes` explicitly, or pass `["*"]` to opt in to future types automatically. @@ -42,30 +54,52 @@ Aggregation rounds bids down and asks up. With `nSigFigs: 5` and `mantissa: 2`, ## Acknowledgement ```json -{"channel":"subscriptionResponse","data":{"subscriptionId":"sub_01","type":"l2BookDiff"}} +{ + "channel": "subscriptionResponse", + "data": { "subscriptionId": "sub_01", "type": "l2BookDiff" } +} ``` ## Event envelope ```json -{"channel":"l2BookDiff","subscriptionId":"sub_01","blockHeight":123456,"blockTime":1780000000000,"cursor":"","data":{"height":123456,"time":1780000000000,"isSnapshot":false,"diffs":[{"coin":"BTC","seq":42,"prev_seq":41,"levels":[[{"px":"100000.0","sz":"1.50","n":4}],[]]}]}} +{ + "channel": "l2BookDiff", + "subscriptionId": "sub_01", + "blockHeight": 123456, + "blockTime": 1780000000000, + "cursor": "", + "data": { + "height": 123456, + "time": 1780000000000, + "isSnapshot": false, + "diffs": [ + { + "coin": "BTC", + "seq": 42, + "prev_seq": 41, + "levels": [[{ "px": "100000.0", "sz": "1.50", "n": 4 }], []] + } + ] + } +} ``` ## Payload fields -| Field | Type | Description | -| --- | --- | --- | -| `height` | integer | Block height. | -| `time` | integer | Block timestamp in milliseconds. | -| `isSnapshot` | boolean | `true` when the message contains a complete replacement snapshot; absent or `false` for an incremental update. | -| `diffs` | array | One entry per market that changed in this block. | -| `diffs[].coin` | string | Market symbol. | -| `diffs[].seq` | integer | Per-market sequence number, incrementing by one per diff for that market. | -| `diffs[].prev_seq` | integer | The preceding per-market sequence number, for gap detection. | -| `diffs[].levels` | array | Two-element tuple of `[bids, asks]`, containing changed levels only. | -| `diffs[].levels[][].px` | string | Price, as a decimal string. | -| `diffs[].levels[][].sz` | string | New total size at this price level. `"0"` means the level was removed. | -| `diffs[].levels[][].n` | integer | Number of orders at this level. `0` when the level was removed. | +| Field | Type | Description | +| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------- | +| `height` | integer | Block height. | +| `time` | integer | Block timestamp in milliseconds. | +| `isSnapshot` | boolean | `true` when the message contains a complete replacement snapshot; absent or `false` for an incremental update. | +| `diffs` | array | One entry per market that changed in this block. | +| `diffs[].coin` | string | Market symbol. | +| `diffs[].seq` | integer | Per-market sequence number, incrementing by one per diff for that market. | +| `diffs[].prev_seq` | integer | The preceding per-market sequence number, for gap detection. | +| `diffs[].levels` | array | Two-element tuple of `[bids, asks]`, containing changed levels only. | +| `diffs[].levels[][].px` | string | Price, as a decimal string. | +| `diffs[].levels[][].sz` | string | New total size at this price level. `"0"` means the level was removed. | +| `diffs[].levels[][].n` | integer | Number of orders at this level. `0` when the level was removed. | ## Applying diffs @@ -77,24 +111,28 @@ Aggregation rounds bids down and asks up. With `nSigFigs: 5` and `mantissa: 2`, ## Snapshot-to-diff bootstrap -1. Subscribe to `l2Book` and install the received snapshot as local book state. -2. The snapshot establishes the local book state. -3. Subscribe to `l2BookDiff` for the same coin scope and apply its diffs to that state. -4. If continuity is broken, discard local state and start again from a fresh snapshot. +The first message for each subscribed market carries the current aggregated book with `isSnapshot: true`. Install it as local state. Normal subsequent messages are diffs; a later `isSnapshot: true` message replaces state for recovery. + +Apply subsequent diffs in height order. For each market, the first diff must carry `prev_seq` equal to the snapshot's `seq`; continue comparing `prev_seq` to your stored position after every diff. A later message with `isSnapshot: true` uses the same replacement mechanism for recovery: discard local state for the affected market and adopt it. + +For a snapshot shared by many consumers, or to let a slow client digest a large book while buffering live updates, use [the REST snapshot read](/docs/data/hypercore/rest-api) instead. `l2Book` carries no per-market sequence, so it is not a bootstrap source for a diff-maintained book. ## Choosing a book stream -| | l2Book | l2BookDiff | bbo | l4BookUpdates | -| --- | --- | --- | --- | --- | -| **Delivers** | Complete aggregated snapshot | Changed aggregated levels | Best bid and ask only | Changed individual orders | -| **Client state** | None required | Maintains a local book | None required | Maintains a local book | -| **Detail** | Aggregated levels | Aggregated levels | Top of book | Individual orders, with queue position | -| **Use case** | Displays, periodic reads | Efficient live book | Price and spread tracking | Market making, queue analysis | +| | l2Book | l2BookDiff | bbo | l4BookUpdates | +| ---------------- | ---------------------------- | ------------------------- | ------------------------- | -------------------------------------- | +| **Delivers** | Complete aggregated snapshot | Changed aggregated levels | Best bid and ask only | Changed individual orders | +| **Client state** | None required | Maintains a local book | None required | Maintains a local book | +| **Detail** | Aggregated levels | Aggregated levels | Top of book | Individual orders, with queue position | +| **Use case** | Displays, periodic reads | Efficient live book | Price and spread tracking | Market making, queue analysis | ## Unsubscribe ```json -{"method":"unsubscribe","subscription":{"type":"l2BookDiff","coins":["BTC","ETH"]}} +{ + "method": "unsubscribe", + "subscription": { "type": "l2BookDiff", "coins": ["BTC", "ETH"] } +} ``` ## Recovery @@ -103,4 +141,4 @@ Aggregation rounds bids down and asks up. With `nSigFigs: 5` and `mantissa: 2`, * On reconnect, supply `cursor` in the subscription object. * Check `prev_seq` against your position for that market on every diff. * A message with `isSnapshot: true` replaces your local state. Any message without it is a diff that must chain onto your previous state. -* If continuity is broken, a fresh message with `isSnapshot: true` is pushed to you. There is no separate resynchronization message and no epoch to track — `isSnapshot: true` is the signal to discard local state and adopt the supplied snapshot. +* If continuity is broken, a fresh message with `isSnapshot: true` is pushed to you. `isSnapshot` is the only continuity signal you need to handle — receiving it means discard local state and adopt the supplied snapshot. diff --git a/content/api-reference/websockets/hypercore/l4-book-updates.mdx b/content/api-reference/websockets/hypercore/l4-book-updates.mdx index 24ede934b..96fab2b52 100644 --- a/content/api-reference/websockets/hypercore/l4-book-updates.mdx +++ b/content/api-reference/websockets/hypercore/l4-book-updates.mdx @@ -11,57 +11,89 @@ description: "HyperCore private-preview documentation." including its position in the price-level queue. This is ideal for market making, queue-position analysis, liquidity attribution, and reconstructing an order-level book. -For the corresponding gRPC update stream, see [StreamL4BookUpdates](/docs/chains/hypercore-grpc/api-reference/stream-l4-book-updates). For the snapshot-to-diff recovery pattern, see [l2BookDiff](/docs/chains/websockets/hypercore/streams/l2-book-diff#snapshot-to-diff-bootstrap). +For the corresponding gRPC update stream, see [StreamL4BookUpdates](/docs/chains/hypercore-grpc/api-reference/stream-l4-book-updates). ## Subscribe ```json -{"method":"subscribe","subscription":{"type":"l4BookUpdates","coins":["BTC","ETH"]}} +{ + "method": "subscribe", + "subscription": { "type": "l4BookUpdates", "coins": ["BTC", "ETH"] } +} ``` Use `marketTypes` instead of `coins` to subscribe to all markets of selected types: ```json -{"method":"subscribe","subscription":{"type":"l4BookUpdates","marketTypes":["spot"]}} +{ + "method": "subscribe", + "subscription": { "type": "l4BookUpdates", "marketTypes": ["spot"] } +} ``` ## Subscription parameters -| Parameter | Type | Required | Source | Description | -| --- | --- | --- | --- | --- | -| `coins` | string[] | No | Alchemy extension | Markets to subscribe to. Omit to subscribe to every market of the types in `marketTypes`, which defaults to perpetuals. The native API takes a single `coin` per subscription; the plural array is an Alchemy extension. | -| `marketTypes` | string[] | No | Alchemy extension | Restricts delivery by market type. Accepted values: `perp`, `spot`, `outcome`, or `*`. Defaults to `["perp"]`. Rejected if combined with `coins`. | +| Parameter | Type | Required | Source | Description | +| ------------- | -------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `coins` | string[] | No | Alchemy extension | Markets to subscribe to. Omit to subscribe to every market of the types in `marketTypes`, which defaults to perpetuals. The native API takes a single `coin` per subscription; the plural array is an Alchemy extension. | +| `marketTypes` | string[] | No | Alchemy extension | Restricts delivery by market type. Accepted values: `perp`, `spot`, `outcome`, or `*`. Defaults to `["perp"]`. Rejected if combined with `coins`. | The default never grows. New market types must be added to `marketTypes` explicitly, or pass `["*"]` to opt in to future types automatically. ## Acknowledgement ```json -{"channel":"subscriptionResponse","data":{"subscriptionId":"sub_01","type":"l4BookUpdates"}} +{ + "channel": "subscriptionResponse", + "data": { "subscriptionId": "sub_01", "type": "l4BookUpdates" } +} ``` ## Event envelope ```json -{"channel":"l4BookUpdates","subscriptionId":"sub_01","blockHeight":123456,"blockTime":1780000000000,"cursor":"","data":{"height":123456,"time":1780000000000,"isSnapshot":false,"diffs":[{"type":"new","coin":"BTC","oid":12345,"user":"0x1111111111111111111111111111111111111111","side":"B","px":"100000.0","sz":"0.10","insertBefore":12346}]}} +{ + "channel": "l4BookUpdates", + "subscriptionId": "sub_01", + "blockHeight": 123456, + "blockTime": 1780000000000, + "cursor": "", + "data": { + "height": 123456, + "timestamp": 1780000000000, + "isSnapshot": false, + "diffs": [ + { + "type": "new", + "coin": "BTC", + "oid": 12345, + "user": "0x1111111111111111111111111111111111111111", + "side": "B", + "px": "100000.0", + "sz": "0.10", + "insertBefore": 12346 + } + ] + } +} ``` ## Payload fields -| Field | Type | Description | -| --- | --- | --- | -| `height` | integer | Block height. | -| `time` | integer | Block timestamp in milliseconds. | -| `isSnapshot` | boolean | `true` when the message contains a complete replacement snapshot; absent or `false` for an incremental update. | -| `diffs` | array | Per-order changes in this block. | -| `diffs[].type` | string | `new`, `update`, or `remove`. | -| `diffs[].coin` | string | Market symbol. | -| `diffs[].oid` | integer | Order ID, unique and stable for the life of the order. | -| `diffs[].user` | string | Address that placed the order. | -| `diffs[].side` | string | `B` for bid, `A` for ask. | -| `diffs[].px` | string | Limit price, as a decimal string. | -| `diffs[].sz` | string | Current size. Present on `new` and `update`, absent on `remove`. | -| `diffs[].insertBefore` | integer | Optional, on `new` only. Queue placement — see below. | +| Field | Type | Description | +| ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------- | +| `height` | integer | Block height. | +| `timestamp` | integer | Block timestamp in milliseconds. | +| `isSnapshot` | boolean | `true` when the message contains a complete replacement snapshot; absent or `false` for an incremental update. | +| `diffs` | array | Per-order changes in this block. | +| `diffs[].type` | string | `new`, `update`, or `remove`. | +| `diffs[].coin` | string | Market symbol. | +| `diffs[].oid` | integer | Order ID, unique and stable for the life of the order. | +| `diffs[].user` | string | Address that placed the order. | +| `diffs[].side` | string | `B` for bid, `A` for ask. | +| `diffs[].px` | string | Limit price, as a decimal string. | +| `diffs[].sz` | string | Current size. Present on `new` and `update`, absent on `remove`. | +| `diffs[].insertBefore` | integer | Optional, on `new` only. Queue placement — see below. | ## Queue position @@ -73,19 +105,28 @@ The default never grows. New market types must be added to `marketTypes` explici * `remove` is terminal — the order was filled or cancelled * Grouping these orders by price produces the corresponding level-aggregated view — sum the sizes and count the orders at each price — so one subscription can serve both order-level and level-aggregated needs. This corresponds to an unaggregated `l2Book`; it does not reproduce a book requested with `nSigFigs` or `mantissa` applied. +## Bootstrap + +The first message after subscribing carries a full order-book snapshot with `isSnapshot: true`, delivering every resting order as a `new` diff. Install it as local state, then apply later diffs. A later message with `isSnapshot: true` uses the same replacement mechanism for recovery. + +For a snapshot shared by many consumers, or to let a slow client digest a large book while buffering live updates, use [the REST snapshot read](/docs/data/hypercore/rest-api) instead. + ## Choosing a book stream -| | l2Book | l2BookDiff | bbo | l4BookUpdates | -| --- | --- | --- | --- | --- | -| **Delivers** | Complete aggregated snapshot | Changed aggregated levels | Best bid and ask only | Changed individual orders | -| **Client state** | None required | Maintains a local book | None required | Maintains a local book | -| **Detail** | Aggregated levels | Aggregated levels | Top of book | Individual orders, with queue position | -| **Use case** | Displays, periodic reads | Efficient live book | Price and spread tracking | Market making, queue analysis | +| | l2Book | l2BookDiff | bbo | l4BookUpdates | +| ---------------- | ---------------------------- | ------------------------- | ------------------------- | -------------------------------------- | +| **Delivers** | Complete aggregated snapshot | Changed aggregated levels | Best bid and ask only | Changed individual orders | +| **Client state** | None required | Maintains a local book | None required | Maintains a local book | +| **Detail** | Aggregated levels | Aggregated levels | Top of book | Individual orders, with queue position | +| **Use case** | Displays, periodic reads | Efficient live book | Price and spread tracking | Market making, queue analysis | ## Unsubscribe ```json -{"method":"unsubscribe","subscription":{"type":"l4BookUpdates","coins":["BTC","ETH"]}} +{ + "method": "unsubscribe", + "subscription": { "type": "l4BookUpdates", "coins": ["BTC", "ETH"] } +} ``` ## Recovery @@ -95,4 +136,4 @@ The default never grows. New market types must be added to `marketTypes` explici * Persist `cursor` after applying a message. * On reconnect, supply `cursor` in the subscription object. * A message with `isSnapshot: true` replaces your local state. Any message without it is a diff that must chain onto your previous state. -* If continuity is broken, a fresh message with `isSnapshot: true` is pushed to you. There is no separate resynchronization message and no epoch to track — `isSnapshot: true` is the signal to discard local state and adopt the supplied snapshot. +* If continuity is broken, a fresh message with `isSnapshot: true` is pushed to you. `isSnapshot` is the only continuity signal you need to handle — receiving it means discard local state and adopt the supplied snapshot. diff --git a/content/api-reference/websockets/hypercore/liquidation-fills.mdx b/content/api-reference/websockets/hypercore/liquidation-fills.mdx index 35f77a246..042d18955 100644 --- a/content/api-reference/websockets/hypercore/liquidation-fills.mdx +++ b/content/api-reference/websockets/hypercore/liquidation-fills.mdx @@ -8,21 +8,19 @@ description: "HyperCore private-preview documentation." # liquidationFills stream ## Subscribe -> The values below illustrate the intended request shape. ```json { "method": "subscribe", "subscription": { "type": "liquidationFills", - "coins": [ - "BTC" - ] + "coins": ["BTC"] } } ``` ## Acknowledgement + ```json { "channel": "subscriptionResponse", @@ -45,12 +43,33 @@ description: "HyperCore private-preview documentation." "data": { "fills": [ { + "user": "0x1111111111111111111111111111111111111111", "coin": "BTC", - "px": "99000.0", - "sz": "0.50", - "side": "A", - "isLiquidation": true, - "tradeId": "trade_02" + "px": "100000.0", + "sz": "0.01", + "side": "B", + "time": 1780000000000, + "startPosition": "0.00", + "dir": "Open Long", + "closedPnl": "0.0", + "hash": "0xabc123", + "oid": 12345, + "crossed": false, + "fee": "0.20", + "tid": 87654321, + "liquidation": { + "liquidatedUser": "0x3333333333333333333333333333333333333333", + "markPx": "99990.0", + "method": "market" + }, + "feeToken": "USDC", + "builderFee": "0.01", + "cloid": "client-order-01", + "deployerFee": "0.01", + "priorityGas": "0.001", + "builder": "0x2222222222222222222222222222222222222222", + "twapId": null, + "txIndex": 3 } ] } @@ -59,30 +78,50 @@ description: "HyperCore private-preview documentation." ## Payload fields -The payload shape is proposed. - | Field | Type | Description | | --- | --- | --- | | fills | array | Fill records. | -| fills[] | object | Fill records. | -| fills[].coin | string | Market identifier. | -| fills[].px | string | Price value. | -| fills[].sz | string | Size value. | +| fills[] | object | Fill record. | +| fills[].user | string | User identifier for the fill. | +| Field | Type | Description | +| --- | --- | --- | +| fills[].coin | string | Market symbol for the fill. | +| fills[].px | string | Execution price. | +| fills[].sz | string | Executed size. | | fills[].side | string | Side code: A is ask/sell; B is bid/buy. | -| fills[].isLiquidation | boolean | Illustrative isLiquidation value. | -| fills[].tradeId | string | Illustrative tradeId value. | +| fills[].time | integer | Time of the fill, in milliseconds. | +| fills[].startPosition | string | Position size immediately before the fill. | +| fills[].dir | string | Display direction for the fill. | +| fills[].closedPnl | string | Realized profit or loss closed by the fill. | +| fills[].hash | string | Layer-1 transaction hash for the fill. | +| fills[].oid | integer | Identifier of the order that produced the fill. | +| fills[].crossed | boolean | Whether the order crossed the spread. | +| fills[].fee | string | Fee charged for the fill; a negative value is a rebate. | +| fills[].tid | integer | Trade identifier. | +| fills[].liquidation | object or null | Liquidation details when the fill is a liquidation. | +| fills[].liquidation.liquidatedUser | string | Address of the liquidated user, when present. | +| fills[].liquidation.markPx | string | Mark price at liquidation. | +| fills[].liquidation.method | string | Liquidation method: market or backstop. | +| fills[].feeToken | string | Token in which the fee was paid. | +| fills[].builderFee | string | Amount paid to the builder and included in fee. | +| fills[].cloid | string or null | Client order identifier. | +| fills[].deployerFee | string | Fee paid to the HIP-3 deployer. | +| fills[].priorityGas | string or null | Order-priority fee paid in HYPE. | +| fills[].builder | string | Builder address associated with the fill. | +| fills[].twapId | integer or null | Identifier of the TWAP that produced the fill. | +| fills[].txIndex | integer | Transaction index of the fill within its block. | ## Unsubscribe + ```json { "method": "unsubscribe", "subscription": { "type": "liquidationFills", - "coins": [ - "BTC" - ] + "coins": ["BTC"] } } ``` + ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. diff --git a/content/api-reference/websockets/hypercore/set-oracle-updates.mdx b/content/api-reference/websockets/hypercore/set-oracle-updates.mdx index 6682644e5..fdae306cb 100644 --- a/content/api-reference/websockets/hypercore/set-oracle-updates.mdx +++ b/content/api-reference/websockets/hypercore/set-oracle-updates.mdx @@ -7,22 +7,24 @@ description: "HyperCore private-preview documentation." # setOracleUpdates stream +For a native REST read of the current perpetual oracle price, use the `oraclePx` +field in `metaAndAssetCtxs` from the [HyperCore REST API](/docs/data/hypercore/rest-api). +This stream is the separate HIP-3 oracle-update node-file surface. + ## Subscribe -> The values below illustrate the intended request shape. ```json { "method": "subscribe", "subscription": { "type": "setOracleUpdates", - "coins": [ - "BTC" - ] + "dex": "vntls" } } ``` ## Acknowledgement + ```json { "channel": "subscriptionResponse", @@ -43,34 +45,41 @@ description: "HyperCore private-preview documentation." "blockTime": 1780000000000, "cursor": "", "data": { - "coin": "BTC", - "oraclePrice": "99995.0", - "source": "validatorSet" + "block_time": "2025-10-06T14:56:40.274583420", + "dex": "vntls", + "success": true, + "error": null, + "oracle_pxs": [["vntls:vANDRL", "52.146"]], + "mark_pxs": [[["vntls:vANDRL", "50.809"]]], + "external_perp_pxs": [["vntls:vANDRL", "50.809"]] } } ``` ## Payload fields -The payload shape is proposed. - | Field | Type | Description | | --- | --- | --- | -| coin | string | Market identifier. | -| oraclePrice | string | Illustrative oraclePrice value. | -| source | string | Illustrative source value. | +| block_time | string | Time of the oracle update. | +| dex | string | Perpetual DEX that received the oracle update. | +| success | boolean | Whether the oracle update action succeeded. | +| error | string or null | Error returned for a failed oracle update. | +| oracle_pxs | array | Oracle prices for assets on the DEX, as asset-and-price pairs. | +| mark_pxs | array | Mark-price tiers; each tier is an array of asset-and-price pairs. | +| external_perp_pxs | array | External perpetual prices for assets on the DEX, as asset-and-price pairs. | + ## Unsubscribe + ```json { "method": "unsubscribe", "subscription": { "type": "setOracleUpdates", - "coins": [ - "BTC" - ] + "dex": "vntls" } } ``` + ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. diff --git a/content/api-reference/websockets/hypercore/tpsl-updates.mdx b/content/api-reference/websockets/hypercore/tpsl-updates.mdx index c50565f07..5c7d1f75d 100644 --- a/content/api-reference/websockets/hypercore/tpsl-updates.mdx +++ b/content/api-reference/websockets/hypercore/tpsl-updates.mdx @@ -16,50 +16,84 @@ For the corresponding gRPC stream, see [StreamTpslUpdates](/docs/chains/hypercor ## Subscribe ```json -{"method":"subscribe","subscription":{"type":"tpslUpdates","coins":["BTC","ETH"]}} +{ + "method": "subscribe", + "subscription": { "type": "tpslUpdates", "coins": ["BTC", "ETH"] } +} ``` ## Subscription parameters -| Parameter | Type | Required | Source | Description | -| --- | --- | --- | --- | --- | -| `coins` | string[] | No | Alchemy extension | Markets to subscribe to. Omit to subscribe to all perpetual markets. | +| Parameter | Type | Required | Source | Description | +| --------- | -------- | -------- | ----------------- | -------------------------------------------------------------------- | +| `coins` | string[] | No | Alchemy extension | Markets to subscribe to. Omit to subscribe to all perpetual markets. | Trigger orders exist only on perpetual markets, so no market-type filter applies. ## Acknowledgement ```json -{"channel":"subscriptionResponse","data":{"subscriptionId":"sub_01","type":"tpslUpdates"}} +{ + "channel": "subscriptionResponse", + "data": { "subscriptionId": "sub_01", "type": "tpslUpdates" } +} ``` ## Event envelope ```json -{"channel":"tpslUpdates","subscriptionId":"sub_01","blockHeight":123456,"blockTime":1780000000000,"cursor":"","data":{"height":123456,"time":1780000000000,"isSnapshot":false,"diffs":[{"type":"add","oid":12345,"coin":"BTC","user":"0x1111111111111111111111111111111111111111","side":"B","triggerPx":"99000.0","limitPx":"98900.0","sz":"0.10","triggerCondition":"Price below 99000","orderType":"Stop Limit","isPositionTpsl":false,"reduceOnly":true,"timestamp":1780000000000}]}} +{ + "channel": "tpslUpdates", + "subscriptionId": "sub_01", + "blockHeight": 123456, + "blockTime": 1780000000000, + "cursor": "", + "data": { + "height": 123456, + "time": 1780000000000, + "isSnapshot": false, + "diffs": [ + { + "type": "add", + "oid": 12345, + "coin": "BTC", + "user": "0x1111111111111111111111111111111111111111", + "side": "B", + "triggerPx": "99000.0", + "limitPx": "98900.0", + "sz": "0.10", + "triggerCondition": "Price below 99000", + "orderType": "Stop Limit", + "isPositionTpsl": false, + "reduceOnly": true, + "timestamp": 1780000000000 + } + ] + } +} ``` ## Payload fields -| Field | Type | Description | -| --- | --- | --- | -| `height` | integer | Block height. | -| `time` | integer | Block timestamp in milliseconds. | -| `isSnapshot` | boolean | `true` when the message contains a complete replacement snapshot; absent or `false` for an incremental update. | -| `diffs[].type` | string | `add` or `remove`. | -| `diffs[].oid` | integer | Order ID. | -| `diffs[].coin` | string | Market symbol. | -| `diffs[].user` | string | Address that placed the order. | -| `diffs[].side` | string | `B` for buy, `A` for sell. | -| `diffs[].triggerPx` | string | Price at which the order triggers. | -| `diffs[].limitPx` | string | Limit price applied once triggered. | -| `diffs[].sz` | string | Order size. `"0.0"` indicates a position-level TP/SL sized by the position rather than a fixed quantity. | -| `diffs[].triggerCondition` | string | Human-readable condition, for example `Price above 50000`. | -| `diffs[].orderType` | string | For example `Stop Market`, `Take Profit Limit`. | -| `diffs[].isPositionTpsl` | boolean | True when attached to a position rather than standing alone. | -| `diffs[].reduceOnly` | boolean | True when the order can only reduce a position. | -| `diffs[].timestamp` | integer | Order creation time in milliseconds. | -| `diffs[].reason` | string | Present on `remove` only. Why the order left the book. | +| Field | Type | Description | +| -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- | +| `height` | integer | Block height. | +| `time` | integer | Block timestamp in milliseconds. | +| `isSnapshot` | boolean | `true` when the message contains a complete replacement snapshot; absent or `false` for an incremental update. | +| `diffs[].type` | string | `add` or `remove`. | +| `diffs[].oid` | integer | Order ID. | +| `diffs[].coin` | string | Market symbol. | +| `diffs[].user` | string | Address that placed the order. | +| `diffs[].side` | string | `B` for buy, `A` for sell. | +| `diffs[].triggerPx` | string | Price at which the order triggers. | +| `diffs[].limitPx` | string | Limit price applied once triggered. | +| `diffs[].sz` | string | Order size. `"0.0"` indicates a position-level TP/SL sized by the position rather than a fixed quantity. | +| `diffs[].triggerCondition` | string | Human-readable condition, for example `Price above 50000`. | +| `diffs[].orderType` | string | For example `Stop Market`, `Take Profit Limit`. | +| `diffs[].isPositionTpsl` | boolean | True when attached to a position rather than standing alone. | +| `diffs[].reduceOnly` | boolean | True when the order can only reduce a position. | +| `diffs[].timestamp` | integer | Order creation time in milliseconds. | +| `diffs[].reason` | string | Present on `remove` only. Why the order left the book. | ## Update behavior @@ -67,24 +101,33 @@ Trigger orders exist only on perpetual markets, so no market-type filter applies * A `remove` is always terminal * Perpetual markets only +## Bootstrap + +The first message after subscribing carries a snapshot of all open trigger orders with `isSnapshot: true`, delivering each order as an `add` diff. Install it as local state, then apply later diffs. A later message with `isSnapshot: true` uses the same replacement mechanism for recovery. + +For a snapshot shared by many consumers, or to let a slow client digest a large trigger-order set while buffering live updates, use [the REST snapshot read](/docs/data/hypercore/rest-api) instead. + ## Removal reasons -| Reason | Meaning | -| --- | --- | -| `triggered` | Condition met; the order was placed on the book | -| `canceled` | Cancelled by the user | -| `reduceOnlyCanceled` | Reduce-only order cancelled because the position closed | -| `marginCanceled` | Cancelled due to insufficient margin | -| `rejected` | Rejected by the matching engine | -| `siblingFilledCanceled` | A paired TP/SL order triggered, cancelling this one | -| `liquidatedCanceled` | Cancelled because the position was liquidated | +| Reason | Meaning | +| ----------------------- | ------------------------------------------------------- | +| `triggered` | Condition met; the order was placed on the book | +| `canceled` | Cancelled by the user | +| `reduceOnlyCanceled` | Reduce-only order cancelled because the position closed | +| `marginCanceled` | Cancelled due to insufficient margin | +| `rejected` | Rejected by the matching engine | +| `siblingFilledCanceled` | A paired TP/SL order triggered, cancelling this one | +| `liquidatedCanceled` | Cancelled because the position was liquidated | `reason` is informational — treat every `remove` as terminal regardless of its value. New reason values may appear as HyperCore adds order statuses, so do not branch on an exhaustive set. ## Unsubscribe ```json -{"method":"unsubscribe","subscription":{"type":"tpslUpdates","coins":["BTC","ETH"]}} +{ + "method": "unsubscribe", + "subscription": { "type": "tpslUpdates", "coins": ["BTC", "ETH"] } +} ``` ## Recovery @@ -94,4 +137,4 @@ Trigger orders exist only on perpetual markets, so no market-type filter applies * Persist `cursor` after applying a message. * On reconnect, supply `cursor` in the subscription object. * A message with `isSnapshot: true` replaces your local state. Any message without it is a diff that must chain onto your previous state. -* If continuity is broken, a fresh message with `isSnapshot: true` is pushed to you. There is no separate resynchronization message and no epoch to track — `isSnapshot: true` is the signal to discard local state and adopt the supplied snapshot. +* If continuity is broken, a fresh message with `isSnapshot: true` is pushed to you. `isSnapshot` is the only continuity signal you need to handle — receiving it means discard local state and adopt the supplied snapshot. diff --git a/content/api-reference/websockets/hypercore/trades.mdx b/content/api-reference/websockets/hypercore/trades.mdx new file mode 100644 index 000000000..d5c9f5331 --- /dev/null +++ b/content/api-reference/websockets/hypercore/trades.mdx @@ -0,0 +1,72 @@ +--- +title: "trades stream" +description: "HyperCore private-preview documentation." +--- + + + +# trades stream + +Subscribe to real-time trades for one market. + +## Subscribe + +```json +{ + "method": "subscribe", + "subscription": { + "type": "trades", + "coin": "BTC" + } +} +``` + +## Event + +```json +{ + "channel": "trades", + "data": [ + { + "coin": "BTC", + "side": "B", + "px": "72581.0", + "sz": "0.00017", + "time": 1787259217020, + "hash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "tid": 877707108085800, + "users": [ + "0x9b54264d7502f80163ea949038aad771eae67e38", + "0x706bb519b05b7dc01d048af9a5e29d1ef5d6d9e3" + ] + } + ] +} +``` + +## Payload fields + +| Field | Type | Description | +| --- | --- | --- | +| data | array | Trade records. | +| data[] | object | Trade record. | +| data[].coin | string | Market symbol for the trade. | +| data[].side | string | Taker side: A is ask/sell; B is bid/buy. | +| data[].px | string | Trade price. | +| data[].sz | string | Trade size. | +| data[].time | integer | Trade time in milliseconds. | +| data[].hash | string | Layer-1 transaction hash for the trade. | +| data[].tid | integer | Trade identifier. | +| data[].users | array | Buyer and seller addresses, in that order. | + +## Unsubscribe + +```json +{ + "method": "unsubscribe", + "subscription": { + "type": "trades", + "coin": "BTC" + } +} +``` diff --git a/content/api-reference/websockets/hypercore/user-fills.mdx b/content/api-reference/websockets/hypercore/user-fills.mdx index 817ac863f..0e8889f15 100644 --- a/content/api-reference/websockets/hypercore/user-fills.mdx +++ b/content/api-reference/websockets/hypercore/user-fills.mdx @@ -8,21 +8,19 @@ description: "HyperCore private-preview documentation." # userFills stream ## Subscribe -> The values below illustrate the intended request shape. ```json { "method": "subscribe", "subscription": { "type": "userFills", - "users": [ - "0x1111111111111111111111111111111111111111" - ] + "users": ["0x1111111111111111111111111111111111111111"] } } ``` ## Acknowledgement + ```json { "channel": "subscriptionResponse", @@ -50,9 +48,28 @@ description: "HyperCore private-preview documentation." "px": "100000.0", "sz": "0.01", "side": "B", + "time": 1780000000000, + "startPosition": "0.00", + "dir": "Open Long", + "closedPnl": "0.0", + "hash": "0xabc123", + "oid": 12345, + "crossed": false, "fee": "0.20", - "tradeId": "trade_01", - "time": 1780000000000 + "tid": 87654321, + "liquidation": { + "liquidatedUser": "0x3333333333333333333333333333333333333333", + "markPx": "99990.0", + "method": "market" + }, + "feeToken": "USDC", + "builderFee": "0.01", + "cloid": "client-order-01", + "deployerFee": "0.01", + "priorityGas": "0.001", + "builder": "0x2222222222222222222222222222222222222222", + "twapId": null, + "txIndex": 3 } ] } @@ -61,32 +78,50 @@ description: "HyperCore private-preview documentation." ## Payload fields -The payload shape is proposed. - | Field | Type | Description | | --- | --- | --- | | fills | array | Fill records. | -| fills[] | object | Fill records. | -| fills[].user | string | User identifier. | -| fills[].coin | string | Market identifier. | -| fills[].px | string | Price value. | -| fills[].sz | string | Size value. | +| fills[] | object | Fill record. | +| fills[].user | string | User identifier for the fill. | +| Field | Type | Description | +| --- | --- | --- | +| fills[].coin | string | Market symbol for the fill. | +| fills[].px | string | Execution price. | +| fills[].sz | string | Executed size. | | fills[].side | string | Side code: A is ask/sell; B is bid/buy. | -| fills[].fee | string | Illustrative fee value. | -| fills[].tradeId | string | Illustrative tradeId value. | -| fills[].time | integer | Source time. | +| fills[].time | integer | Time of the fill, in milliseconds. | +| fills[].startPosition | string | Position size immediately before the fill. | +| fills[].dir | string | Display direction for the fill. | +| fills[].closedPnl | string | Realized profit or loss closed by the fill. | +| fills[].hash | string | Layer-1 transaction hash for the fill. | +| fills[].oid | integer | Identifier of the order that produced the fill. | +| fills[].crossed | boolean | Whether the order crossed the spread. | +| fills[].fee | string | Fee charged for the fill; a negative value is a rebate. | +| fills[].tid | integer | Trade identifier. | +| fills[].liquidation | object or null | Liquidation details when the fill is a liquidation. | +| fills[].liquidation.liquidatedUser | string | Address of the liquidated user, when present. | +| fills[].liquidation.markPx | string | Mark price at liquidation. | +| fills[].liquidation.method | string | Liquidation method: market or backstop. | +| fills[].feeToken | string | Token in which the fee was paid. | +| fills[].builderFee | string | Amount paid to the builder and included in fee. | +| fills[].cloid | string or null | Client order identifier. | +| fills[].deployerFee | string | Fee paid to the HIP-3 deployer. | +| fills[].priorityGas | string or null | Order-priority fee paid in HYPE. | +| fills[].builder | string | Builder address associated with the fill. | +| fills[].twapId | integer or null | Identifier of the TWAP that produced the fill. | +| fills[].txIndex | integer | Transaction index of the fill within its block. | ## Unsubscribe + ```json { "method": "unsubscribe", "subscription": { "type": "userFills", - "users": [ - "0x1111111111111111111111111111111111111111" - ] + "users": ["0x1111111111111111111111111111111111111111"] } } ``` + ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. diff --git a/content/api-reference/websockets/hypercore/user-isolated-margin-updates.mdx b/content/api-reference/websockets/hypercore/user-isolated-margin-updates.mdx index 7ed2d7792..237efbc3b 100644 --- a/content/api-reference/websockets/hypercore/user-isolated-margin-updates.mdx +++ b/content/api-reference/websockets/hypercore/user-isolated-margin-updates.mdx @@ -7,7 +7,7 @@ description: "HyperCore private-preview documentation." # userIsolatedMarginUpdates stream -Intended to carry user-context isolated-margin updates. The subscription scope is pending confirmation. +Streams isolated-margin and isolated-margin top-up updates for the requested addresses. ## Subscribe @@ -15,35 +15,69 @@ Intended to carry user-context isolated-margin updates. The subscription scope i { "method": "subscribe", "subscription": { - "type": "userIsolatedMarginUpdates" + "type": "userIsolatedMarginUpdates", + "addresses": ["0x1111111111111111111111111111111111111111"] } } ``` -## Acknowledgement + +## Event envelope ```json { - "channel": "subscriptionResponse", - "data": { - "type": "userIsolatedMarginUpdates" - } + "type": "userIsolatedMarginUpdates", + "channel": "userIsolatedMarginUpdates", + "seq": 1, + "cursor": 1704067201000, + "updates": [{ + "update_type": "isolated_margin", + "time": 1704067201000, + "user": "0x1111111111111111111111111111111111111111", + "coin": "BTC", + "is_buy": true, + "ntli": "500.00", + "tx_index": 0 + }] } ``` +An isolated-margin top-up update uses update_type top_up_isolated_margin and includes target_leverage instead of is_buy and ntli. + +## Payload fields + +| Field | Type | Description | Source tier | +| --- | --- | --- | --- | +| type | string | Event type. | Extended-provider | +| channel | string | Routing channel for the event. | Extended-provider | +| seq | integer | Monotonic sequence number for the stream. | Extended-provider | +| cursor | integer | Resume cursor for the event position. | Extended-provider | +| updates | array | Margin update records. | Extended-provider | +| updates[] | object | Isolated-margin or isolated-margin top-up record. | Extended-provider | +| updates[].update_type | string | Update discriminator: isolated_margin or top_up_isolated_margin. | Extended-provider | +| updates[].time | integer | Event time in milliseconds. | Extended-provider | +| updates[].user | string | Address whose margin setting changed. | Extended-provider | +| updates[].coin | string | Market identifier. | Extended-provider | +| updates[].is_buy | boolean | Isolated-margin side for an isolated_margin update. | Extended-provider | +| updates[].ntli | string | Isolated-margin notional value for an isolated_margin update. | Extended-provider | +| updates[].target_leverage | string | Target leverage for a top_up_isolated_margin update. | Extended-provider | +| updates[].tx_index | integer | Index of the transaction within its block. | Extended-provider | + +## Behavior + +The stream batches updates for the subscribed addresses. The cursor identifies the event position for resumption. + ## Unsubscribe ```json { "method": "unsubscribe", "subscription": { - "type": "userIsolatedMarginUpdates" + "type": "userIsolatedMarginUpdates", + "addresses": ["0x1111111111111111111111111111111111111111"] } } ``` -## Payload schema - -The payload schema is pending engineering confirmation. ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. Store and return the cursor unmodified. diff --git a/content/api-reference/websockets/hypercore/user-leverage-updates.mdx b/content/api-reference/websockets/hypercore/user-leverage-updates.mdx index 47be81d23..e09c2ecce 100644 --- a/content/api-reference/websockets/hypercore/user-leverage-updates.mdx +++ b/content/api-reference/websockets/hypercore/user-leverage-updates.mdx @@ -7,7 +7,7 @@ description: "HyperCore private-preview documentation." # userLeverageUpdates stream -Intended to carry user-context leverage-setting updates. The subscription scope is pending confirmation. +Streams leverage, isolated-margin, and isolated-margin top-up updates for the requested addresses. ## Subscribe @@ -15,35 +15,71 @@ Intended to carry user-context leverage-setting updates. The subscription scope { "method": "subscribe", "subscription": { - "type": "userLeverageUpdates" + "type": "userLeverageUpdates", + "addresses": ["0x1111111111111111111111111111111111111111"] } } ``` -## Acknowledgement + +## Event envelope ```json { - "channel": "subscriptionResponse", - "data": { - "type": "userLeverageUpdates" - } + "type": "userLeverageUpdates", + "channel": "userLeverageUpdates", + "seq": 1, + "cursor": 1704067200000, + "updates": [{ + "update_type": "leverage", + "time": 1704067200000, + "user": "0x1111111111111111111111111111111111111111", + "coin": "ETH", + "is_cross": true, + "leverage": 10, + "tx_index": 0 + }] } ``` +The stream also emits isolated_margin records with is_buy and ntli, and top_up_isolated_margin records with target_leverage. + +## Payload fields + +| Field | Type | Description | Source tier | +| --- | --- | --- | --- | +| type | string | Event type. | Extended-provider | +| channel | string | Routing channel for the event. | Extended-provider | +| seq | integer | Monotonic sequence number for the stream. | Extended-provider | +| cursor | integer | Resume cursor for the event position. | Extended-provider | +| updates | array | Leverage-setting update records. | Extended-provider | +| updates[] | object | Leverage, isolated-margin, or isolated-margin top-up record. | Extended-provider | +| updates[].update_type | string | Update discriminator: leverage, isolated_margin, or top_up_isolated_margin. | Extended-provider | +| updates[].time | integer | Event time in milliseconds. | Extended-provider | +| updates[].user | string | Address whose setting changed. | Extended-provider | +| updates[].coin | string | Market identifier. | Extended-provider | +| updates[].is_cross | boolean | Whether a leverage update uses cross margin. | Extended-provider | +| updates[].leverage | integer | Leverage setting for a leverage update. | Extended-provider | +| updates[].is_buy | boolean | Isolated-margin side for an isolated_margin update. | Extended-provider | +| updates[].ntli | string | Isolated-margin notional value for an isolated_margin update. | Extended-provider | +| updates[].target_leverage | string | Target leverage for a top_up_isolated_margin update. | Extended-provider | +| updates[].tx_index | integer | Index of the transaction within its block. | Extended-provider | + +## Behavior + +The stream batches updates for the subscribed addresses. The cursor identifies the event position for resumption. + ## Unsubscribe ```json { "method": "unsubscribe", "subscription": { - "type": "userLeverageUpdates" + "type": "userLeverageUpdates", + "addresses": ["0x1111111111111111111111111111111111111111"] } } ``` -## Payload schema - -The payload schema is pending engineering confirmation. ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. Store and return the cursor unmodified. diff --git a/content/api-reference/websockets/hypercore/user-order-updates.mdx b/content/api-reference/websockets/hypercore/user-order-updates.mdx index 13c04a205..48619abbe 100644 --- a/content/api-reference/websockets/hypercore/user-order-updates.mdx +++ b/content/api-reference/websockets/hypercore/user-order-updates.mdx @@ -8,21 +8,19 @@ description: "HyperCore private-preview documentation." # userOrderUpdates stream ## Subscribe -> The values below illustrate the intended request shape. ```json { "method": "subscribe", "subscription": { "type": "userOrderUpdates", - "users": [ - "0x1111111111111111111111111111111111111111" - ] + "users": ["0x1111111111111111111111111111111111111111"] } } ``` ## Acknowledgement + ```json { "channel": "subscriptionResponse", @@ -43,50 +41,80 @@ description: "HyperCore private-preview documentation." "blockTime": 1780000000000, "cursor": "", "data": { - "orders": [ - { - "user": "0x1111111111111111111111111111111111111111", - "orderId": "12345", + "orders": [{ + "time": "2024-01-01T00:00:00.000000000", + "user": "0x1111111111111111111111111111111111111111", + "hash": "0xabc...def", + "builder": { "b": "0x2222222222222222222222222222222222222222", "f": 100 }, + "status": "open", + "txIndex": 3, + "statusTimestamp": 1780000000000, + "order": { + "oid": 12345, "coin": "BTC", "side": "B", - "limitPrice": "100000.0", + "limitPx": "100000.0", "sz": "0.10", - "status": "open", - "filledSize": "0" + "timestamp": 1780000000000, + "triggerCondition": "N/A", + "isTrigger": false, + "triggerPx": "0.0", + "children": [], + "isPositionTpsl": false, + "reduceOnly": false, + "orderType": "Limit", + "origSz": "0.10", + "tif": "Gtc", + "cloid": null } - ] + }] } } ``` ## Payload fields -The payload shape is proposed. +| Field | Type | Description | Source tier | +| --- | --- | --- | --- | +| orders | array | Order status records. | Our own choice | +| orders[] | object | Order status record. | Our own choice | +| orders[].time | string | Time the node recorded the order-status event. | Foundation-native | +| orders[].user | string | User identifier. | Foundation-native | +| orders[].hash | string | Transaction hash associated with the update. | Extended-provider | +| orders[].builder | object | Builder metadata for the update, containing the builder address and fee rate. | Extended-provider | +| orders[].status | string | Current state of the order. | Foundation-native | +| orders[].txIndex | integer | Index of the transaction within its block. | Extended-provider | +| orders[].statusTimestamp | integer | Milliseconds timestamp for the status update. | Foundation-native | +| orders[].order | object | Order fields. | Foundation-native | +| orders[].order.oid | integer | Identifier assigned to the order. | Foundation-native | +| orders[].order.coin | string | Market symbol for the order. | Foundation-native | +| orders[].order.side | string | Side code: A is ask/sell; B is bid/buy. | Foundation-native | +| orders[].order.limitPx | string | Limit price for the order. | Foundation-native | +| orders[].order.sz | string | Filled size for the order status. | Foundation-native | +| orders[].order.timestamp | integer | Milliseconds timestamp when the order was created. | Foundation-native | +| orders[].order.triggerCondition | string | Condition that controls trigger-order execution. | Foundation-native | +| orders[].order.isTrigger | boolean | Whether the order is a trigger order. | Foundation-native | +| orders[].order.triggerPx | string | Price that activates a trigger order. | Foundation-native | +| orders[].order.children | array | Child orders associated with the order. | Foundation-native | +| orders[].order.isPositionTpsl | boolean | Whether the order is a position take-profit or stop-loss order. | Foundation-native | +| orders[].order.reduceOnly | boolean | Whether execution can only reduce the position. | Foundation-native | +| orders[].order.orderType | string | Order type. | Foundation-native | +| orders[].order.origSz | string | Original order size. | Foundation-native | +| orders[].order.tif | string | Time-in-force instruction. | Foundation-native | +| orders[].order.cloid | string \| null | Client-supplied order identifier, when present. | Foundation-native | -| Field | Type | Description | -| --- | --- | --- | -| orders | array | Order records. | -| orders[] | object | Order records. | -| orders[].user | string | User identifier. | -| orders[].orderId | string | Illustrative orderId value. | -| orders[].coin | string | Market identifier. | -| orders[].side | string | Side code: A is ask/sell; B is bid/buy. | -| orders[].limitPrice | string | Illustrative limitPrice value. | -| orders[].sz | string | Size value. | -| orders[].status | string | Illustrative status value. | -| orders[].filledSize | string | Illustrative filledSize value. | ## Unsubscribe + ```json { "method": "unsubscribe", "subscription": { "type": "userOrderUpdates", - "users": [ - "0x1111111111111111111111111111111111111111" - ] + "users": ["0x1111111111111111111111111111111111111111"] } } ``` + ## Resume -To resume a stream, supply `cursor` in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. +To resume a stream, supply cursor in the subscription object. The cursor is opaque: clients store and return it unmodified, and its format may change. diff --git a/content/docs.yml b/content/docs.yml index 61313d980..091f8f359 100644 --- a/content/docs.yml +++ b/content/docs.yml @@ -165,6 +165,8 @@ navigation: path: api-reference/websockets/hypercore/set-oracle-updates.mdx - page: tpslUpdates path: api-reference/websockets/hypercore/tpsl-updates.mdx + - page: trades + path: api-reference/websockets/hypercore/trades.mdx - page: userFills path: api-reference/websockets/hypercore/user-fills.mdx - page: userIsolatedMarginUpdates @@ -205,6 +207,18 @@ navigation: path: api-reference/hypercore-grpc/stream-bbo-book.mdx - page: StreamTpslUpdates path: api-reference/hypercore-grpc/stream-tpsl-updates.mdx + - section: HyperCore Node Peering + hidden: true + slug: hypercore-peering + contents: + - page: Overview + path: api-reference/hypercore-peering/overview.mdx + - section: Deploying Markets on Hyperliquid + hidden: true + slug: deploying-markets + contents: + - page: Overview + path: api-reference/deploying-markets/overview.mdx - section: Trace API contents: - page: Trace API Overview @@ -1614,6 +1628,100 @@ navigation: contents: - api: HyperCore Data API Endpoints api-name: hypercore + - section: Account state + contents: + - page: Spot clearinghouse state + path: api-reference/data/hypercore/rest/account-state/spot-clearinghouse-state.mdx + - page: Subaccounts + path: api-reference/data/hypercore/rest/account-state/sub-accounts.mdx + - page: DEX abstraction state + path: api-reference/data/hypercore/rest/account-state/user-dex-abstraction.mdx + - section: Orders and fills + contents: + - page: Frontend open orders + path: api-reference/data/hypercore/rest/orders-and-fills/frontend-open-orders.mdx + - page: Open orders + path: api-reference/data/hypercore/rest/orders-and-fills/open-orders.mdx + - section: Ledger and funding + contents: + - page: User funding + path: api-reference/data/hypercore/rest/ledger-and-funding/user-funding.mdx + - page: Non-funding ledger updates + path: api-reference/data/hypercore/rest/ledger-and-funding/user-non-funding-ledger-updates.mdx + - section: Market data and snapshots + contents: + - page: All mids + path: api-reference/data/hypercore/rest/market-data-and-snapshots/all-mids.mdx + - page: Candle snapshot + path: api-reference/data/hypercore/rest/market-data-and-snapshots/candle-snapshot.mdx + - page: L4 book snapshots + path: api-reference/data/hypercore/rest/market-data-and-snapshots/l4-snapshots.mdx + - page: Trigger-order snapshot + path: api-reference/data/hypercore/rest/market-data-and-snapshots/trigger-order-snapshot.mdx + - section: Asset context + contents: + - page: Active asset data + path: api-reference/data/hypercore/rest/asset-context/active-asset-data.mdx + - page: Perpetual metadata and asset contexts + path: api-reference/data/hypercore/rest/asset-context/meta-and-asset-ctxs.mdx + - page: Predicted fundings + path: api-reference/data/hypercore/rest/asset-context/predicted-fundings.mdx + - page: Spot metadata and asset contexts + path: api-reference/data/hypercore/rest/asset-context/spot-meta-and-asset-ctxs.mdx + - section: Metadata + contents: + - page: Perpetual metadata + path: api-reference/data/hypercore/rest/metadata/meta.mdx + - page: Spot metadata + path: api-reference/data/hypercore/rest/metadata/spot-meta.mdx + - section: Token deployment + contents: + - page: Perpetual deployment auction status + path: api-reference/data/hypercore/rest/token-deployment/perp-deploy-auction-status.mdx + - page: Spot deployment state + path: api-reference/data/hypercore/rest/token-deployment/spot-deploy-state.mdx + - page: Spot-pair deployment auction status + path: api-reference/data/hypercore/rest/token-deployment/spot-pair-deploy-auction-status.mdx + - section: Vaults + contents: + - page: Leading vaults + path: api-reference/data/hypercore/rest/vaults/leading-vaults.mdx + - page: User vault equities + path: api-reference/data/hypercore/rest/vaults/user-vault-equities.mdx + - page: Vault details + path: api-reference/data/hypercore/rest/vaults/vault-details.mdx + - page: Vault summaries + path: api-reference/data/hypercore/rest/vaults/vault-summaries.mdx + - section: Staking, delegation, and validators + contents: + - page: Delegations + path: api-reference/data/hypercore/rest/staking-delegation-and-validators/delegations.mdx + - page: Delegator history + path: api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-history.mdx + - page: Delegator rewards + path: api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-rewards.mdx + - page: Delegator summary + path: api-reference/data/hypercore/rest/staking-delegation-and-validators/delegator-summary.mdx + - page: Validator L1 votes + path: api-reference/data/hypercore/rest/staking-delegation-and-validators/validator-l1-votes.mdx + - section: Roles, agents, and limits + contents: + - page: Maximum builder fee + path: api-reference/data/hypercore/rest/roles-agents-and-limits/max-builder-fee.mdx + - page: User fees + path: api-reference/data/hypercore/rest/roles-agents-and-limits/user-fees.mdx + - page: User rate limit + path: api-reference/data/hypercore/rest/roles-agents-and-limits/user-rate-limit.mdx + - page: User role + path: api-reference/data/hypercore/rest/roles-agents-and-limits/user-role.mdx + - section: Outcome markets + contents: + - page: Outcome metadata + path: api-reference/data/hypercore/rest/outcome-markets/outcome-meta.mdx + - page: Outcome templates + path: api-reference/data/hypercore/rest/outcome-markets/outcome-templates.mdx + - page: Settled outcome + path: api-reference/data/hypercore/rest/outcome-markets/settled-outcome.mdx - page: Historical data path: api-reference/data/hypercore/historical-data/overview.mdx - section: Concepts diff --git a/src/openapi/hypercore/hypercore.yaml b/src/openapi/hypercore/hypercore.yaml index da376c268..4e63b65b3 100644 --- a/src/openapi/hypercore/hypercore.yaml +++ b/src/openapi/hypercore/hypercore.yaml @@ -7,20 +7,37 @@ info: HyperCore read and historical methods for private preview. servers: - url: https://api.g.alchemy.com/hypercore/v1 - description: Provisional base URL; it will be confirmed before general availability. + description: HyperCore REST base URL. tags: - - name: HyperCore Data API Endpoints + - name: Account state + description: User account and portfolio reads. + - name: Orders and fills + description: Order and fill reads. + - name: Ledger and funding + description: Ledger and funding reads. + - name: Market data and snapshots + description: Market-data reads and state snapshots. + - name: Asset context + description: Asset metadata and current context reads. + - name: Metadata + description: Perpetual and spot metadata reads. + - name: Token deployment + description: Token and market deployment reads. + - name: Vaults + description: Vault discovery and account-equity reads. + - name: Staking, delegation, and validators + description: Delegation and validator reads. + - name: Roles, agents, and limits + description: Roles, agents, fee approvals, and rate-limit reads. + - name: Outcome markets + description: Outcome-market metadata and settlement reads. paths: "/{apiKey}/info": post: - tags: - - HyperCore Data API Endpoints operationId: get-info summary: Execute a native-compatible HyperCore read description: | - This API is in private preview. Target October 2026; timing is subject to change. - - Execute a native-compatible HyperCore read selected by the required type discriminator. The remaining native methods will be documented as the service is finalized. + Execute a native-compatible HyperCore read selected by the required type discriminator. parameters: - "$ref": "#/components/parameters/apiKey" requestBody: @@ -42,20 +59,13 @@ paths: endTime: 1780086400000 responses: "200": - description: Successful response. The currently modeled shapes are selected by the requested type. - content: - application/json: - schema: - "$ref": "#/components/schemas/InfoResponse" + "$ref": "#/components/responses/InfoResponse" "/{apiKey}/user-fills": post: - tags: - - HyperCore Data API Endpoints + tags: [Orders and fills] operationId: get-user-fills summary: Get user fills description: | - This API is in private preview. Target October 2026; timing is subject to change. - Retrieve fills associated with a user. parameters: - "$ref": "#/components/parameters/apiKey" @@ -82,13 +92,10 @@ paths: "$ref": "#/components/examples/UserFillsResponse" "/{apiKey}/user-fills-by-time": post: - tags: - - HyperCore Data API Endpoints + tags: [Orders and fills] operationId: get-user-fills-by-time summary: Get user fills by time description: | - This API is in private preview. Target October 2026; timing is subject to change. - Retrieve fills associated with a user over a time range. parameters: - "$ref": "#/components/parameters/apiKey" @@ -117,13 +124,10 @@ paths: "$ref": "#/components/examples/UserFillsByTimeResponse" "/{apiKey}/clearinghouse-state": post: - tags: - - HyperCore Data API Endpoints + tags: [Account state] operationId: get-clearinghouse-state summary: Get clearinghouse state description: | - This API is in private preview. Target October 2026; timing is subject to change. - Retrieve clearinghouse state associated with a user. parameters: - "$ref": "#/components/parameters/apiKey" @@ -145,13 +149,10 @@ paths: "$ref": "#/components/examples/ClearinghouseStateResponse" "/{apiKey}/historical-orders": post: - tags: - - HyperCore Data API Endpoints + tags: [Orders and fills] operationId: get-historical-orders summary: Get historical orders description: | - This API is in private preview. Target October 2026; timing is subject to change. - Retrieve historical orders associated with a user. parameters: - "$ref": "#/components/parameters/apiKey" @@ -173,13 +174,10 @@ paths: "$ref": "#/components/examples/HistoricalOrdersResponse" "/{apiKey}/portfolio-state": post: - tags: - - HyperCore Data API Endpoints + tags: [Account state] operationId: get-portfolio-state summary: Get normalized portfolio state description: | - This API is in private preview. Target October 2026; timing is subject to change. - Retrieve a normalized portfolio-state composite for a user. parameters: - "$ref": "#/components/parameters/apiKey" @@ -206,13 +204,10 @@ paths: "$ref": "#/components/examples/PortfolioStateResponse" "/{apiKey}/extra-agents": post: - tags: - - HyperCore Data API Endpoints + tags: ["Roles, agents, and limits"] operationId: get-extra-agents summary: Get agent and API-wallet state description: | - This API is in private preview. Target October 2026; timing is subject to change. - Retrieve agent and API-wallet information associated with a user. parameters: - "$ref": "#/components/parameters/apiKey" @@ -232,6 +227,38 @@ paths: examples: default: "$ref": "#/components/examples/ExtraAgentsResponse" + "/{apiKey}/l2-book-diff-snapshot": + post: + tags: [Market data and snapshots] + operationId: get-l2-book-diff-snapshot + summary: Get an L2 book snapshot for diff-stream bootstrap + description: | + Retrieve aggregated L2 books at a common block height with each market's diff sequence. + parameters: + - "$ref": "#/components/parameters/apiKey" + requestBody: + required: true + content: + application/json: + schema: + "$ref": "#/components/schemas/L2BookDiffSnapshotRequest" + examples: + default: + value: + coins: [BTC, ETH] + nSigFigs: 5 + mantissa: 2 + nLevels: 20 + responses: + "200": + description: Successful response. + content: + application/json: + schema: + "$ref": "#/components/schemas/L2BookDiffSnapshotResponse" + examples: + default: + "$ref": "#/components/examples/L2BookDiffSnapshotResponse" components: parameters: apiKey: @@ -241,6 +268,82 @@ components: schema: type: string schemas: + InfoTypeRequest: + type: object + required: [type] + properties: + type: + type: string + description: HyperCore `/info` request discriminator. Most values are native-compatible reads; `portfolioState` and `extraAgents` are enriched composites, and `l4Snapshots` and `triggerOrderSnapshot` are Alchemy-original snapshot reads. + enum: + - openOrders + - frontendOpenOrders + - userFills + - userFillsByTime + - historicalOrders + - userFunding + - userNonFundingLedgerUpdates + - clearinghouseState + - spotClearinghouseState + - portfolioState + - extraAgents + - userRateLimit + - maxBuilderFee + - subAccounts + - userVaultEquities + - userRole + - userFees + - userDexAbstraction + - allMids + - candleSnapshot + - l4Snapshots + - triggerOrderSnapshot + - meta + - spotMeta + - metaAndAssetCtxs + - spotMetaAndAssetCtxs + - activeAssetData + - predictedFundings + - spotDeployState + - perpDeployAuctionStatus + - spotPairDeployAuctionStatus + - vaultSummaries + - vaultDetails + - leadingVaults + - delegations + - delegatorSummary + - delegatorHistory + - delegatorRewards + - validatorL1Votes + - outcomeMeta + - settledOutcome + - outcomeTemplates + user: + "$ref": "#/components/schemas/Address" + dex: + type: string + description: Perpetual DEX name. The empty string selects the first perpetual DEX. + builder: + "$ref": "#/components/schemas/Address" + coin: + type: string + startTime: + "$ref": "#/components/schemas/TimestampMs" + endTime: + "$ref": "#/components/schemas/TimestampMs" + interval: + type: string + vaultAddress: + "$ref": "#/components/schemas/Address" + outcome: + type: integer + includeUsers: + type: boolean + includeTriggerOrders: + type: boolean + additionalProperties: true + description: The fields required with `type` are defined by the selected native read. + NativeInfoResponse: {} Address: type: string pattern: "^0x[a-fA-F0-9]{40}$" @@ -270,7 +373,7 @@ components: items: type: string InfoRequest: - oneOf: + anyOf: - "$ref": "#/components/schemas/UserFillsRequest" - "$ref": "#/components/schemas/UserFillsByTimeRequest" - "$ref": "#/components/schemas/HistoricalOrdersRequest" @@ -281,6 +384,7 @@ components: - "$ref": "#/components/schemas/ClearinghouseStateRequest" - "$ref": "#/components/schemas/SpotClearinghouseStateRequest" - "$ref": "#/components/schemas/FrontendOpenOrdersRequest" + - "$ref": "#/components/schemas/InfoTypeRequest" discriminator: propertyName: type mapping: @@ -294,6 +398,36 @@ components: clearinghouseState: "#/components/schemas/ClearinghouseStateRequest" spotClearinghouseState: "#/components/schemas/SpotClearinghouseStateRequest" frontendOpenOrders: "#/components/schemas/FrontendOpenOrdersRequest" + openOrders: "#/components/schemas/InfoTypeRequest" + userRateLimit: "#/components/schemas/InfoTypeRequest" + maxBuilderFee: "#/components/schemas/InfoTypeRequest" + subAccounts: "#/components/schemas/InfoTypeRequest" + userVaultEquities: "#/components/schemas/InfoTypeRequest" + userRole: "#/components/schemas/InfoTypeRequest" + userFees: "#/components/schemas/InfoTypeRequest" + userDexAbstraction: "#/components/schemas/InfoTypeRequest" + allMids: "#/components/schemas/InfoTypeRequest" + candleSnapshot: "#/components/schemas/InfoTypeRequest" + l4Snapshots: "#/components/schemas/InfoTypeRequest" + triggerOrderSnapshot: "#/components/schemas/InfoTypeRequest" + meta: "#/components/schemas/InfoTypeRequest" + spotMeta: "#/components/schemas/InfoTypeRequest" + metaAndAssetCtxs: "#/components/schemas/InfoTypeRequest" + spotMetaAndAssetCtxs: "#/components/schemas/InfoTypeRequest" + activeAssetData: "#/components/schemas/InfoTypeRequest" + predictedFundings: "#/components/schemas/InfoTypeRequest" + spotDeployState: "#/components/schemas/InfoTypeRequest" + perpDeployAuctionStatus: "#/components/schemas/InfoTypeRequest" + spotPairDeployAuctionStatus: "#/components/schemas/InfoTypeRequest" + vaultSummaries: "#/components/schemas/InfoTypeRequest" + vaultDetails: "#/components/schemas/InfoTypeRequest" + leadingVaults: "#/components/schemas/InfoTypeRequest" + delegatorSummary: "#/components/schemas/InfoTypeRequest" + delegatorRewards: "#/components/schemas/InfoTypeRequest" + validatorL1Votes: "#/components/schemas/InfoTypeRequest" + outcomeMeta: "#/components/schemas/InfoTypeRequest" + settledOutcome: "#/components/schemas/InfoTypeRequest" + outcomeTemplates: "#/components/schemas/InfoTypeRequest" InfoResponse: oneOf: - "$ref": "#/components/schemas/UserFillsResponse" @@ -519,6 +653,183 @@ components: type: array items: "$ref": "#/components/schemas/Agent" + L2BookDiffSnapshotRequest: + type: object + required: + - coins + properties: + coins: + type: array + minItems: 1 + items: + type: string + description: Markets to include in the snapshot. + nSigFigs: + type: integer + enum: [2, 3, 4, 5] + description: Significant-figure aggregation for price levels. + mantissa: + type: integer + enum: [2, 5] + description: Mantissa step. Valid only when nSigFigs is 5. + nLevels: + type: integer + enum: [1, 10, 20, 50] + description: Levels per side. Defaults to 20. + L2BookLevel: + type: object + required: + - px + - sz + - n + properties: + px: + type: string + description: Price as a decimal string. + sz: + type: string + description: Total size at the price level. + n: + type: integer + description: Number of orders at the price level. + L2BookDiffSnapshotBook: + type: object + required: + - coin + - time + - levels + - seq + properties: + coin: + type: string + description: Market symbol. + time: + "$ref": "#/components/schemas/TimestampMs" + levels: + type: array + minItems: 2 + maxItems: 2 + items: + type: array + items: + "$ref": "#/components/schemas/L2BookLevel" + description: Two-element tuple of bids and asks. + seq: + type: integer + minimum: 0 + description: Per-market l2BookDiff sequence at the snapshot height. + L2BookDiffSnapshotResponse: + type: object + required: + - height + - books + properties: + height: + type: integer + description: Block height reflected by every returned book. + books: + type: array + items: + "$ref": "#/components/schemas/L2BookDiffSnapshotBook" + responses: + InfoResponse: + description: Successful native-compatible response. + content: + application/json: + schema: + "$ref": "#/components/schemas/NativeInfoResponse" + examples: + openOrders: + value: + - coin: BTC + limitPx: "29792.0" + oid: 91490942 + side: A + sz: "0.0" + timestamp: 1681247412573 + frontendOpenOrders: + value: + - coin: BTC + isPositionTpsl: false + isTrigger: false + limitPx: "29792.0" + oid: 91490942 + orderType: Limit + origSz: "5.0" + reduceOnly: false + side: A + sz: "5.0" + timestamp: 1681247412573 + triggerCondition: N/A + triggerPx: "0.0" + userRateLimit: + value: + cumVlm: "2854574.593578" + nRequestsUsed: 2890 + nRequestsCap: 2864574 + maxBuilderFee: + value: 1 + subAccounts: + value: + - name: Test + subAccountUser: "0x035605fc2f24d65300227189025e90a0d947f16c" + master: "0x8c967e73e6b15087c42a10d344cff4c96d877f1d" + clearinghouseState: + marginSummary: + accountValue: "29.78001" + totalNtlPos: "0.0" + totalRawUsd: "29.78001" + totalMarginUsed: "0.0" + crossMarginSummary: + accountValue: "29.78001" + totalNtlPos: "0.0" + totalRawUsd: "29.78001" + totalMarginUsed: "0.0" + crossMaintenanceMarginUsed: "0.0" + withdrawable: "29.78001" + assetPositions: [] + time: 1733968369395 + spotState: + balances: + - coin: USDC + token: 0 + total: "0.22" + hold: "0.0" + entryNtl: "0.0" + userVaultEquities: + value: + - vaultAddress: "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303" + equity: "742500.082809" + userRole: + value: { role: user } + userFees: + value: + dailyUserVlm: + - date: "2025-05-23" + userCross: "0.0" + userAdd: "0.0" + exchange: "2852367.0770729999" + userCrossRate: "0.000315" + userAddRate: "0.000105" + userSpotCrossRate: "0.00049" + userSpotAddRate: "0.00028" + activeReferralDiscount: "0.0" + trial: null + feeTrialReward: "0.0" + nextTrialAvailableTimestamp: null + delegations: + value: + - validator: "0x5ac99df645f3414876c816caa18b2d234024b487" + amount: "12060.16529862" + lockedUntilTimestamp: 1735466781353 + delegatorSummary: + value: + delegated: "12060.16529862" + undelegated: "0.0" + totalPendingWithdrawal: "0.0" + nPendingWithdrawals: 0 + userDexAbstraction: + value: true examples: UserFillsResponse: value: @@ -582,3 +893,17 @@ components: - address: "0x4444444444444444444444444444444444444444" name: market-maker permissions: [trade] + L2BookDiffSnapshotResponse: + value: + height: 123456 + books: + - coin: BTC + time: 1780000000000 + levels: + - - px: "100000.0" + sz: "1.25" + n: 3 + - - px: "100001.0" + sz: "0.80" + n: 2 + seq: 42 From 5e81dd302dc9e289f45935a09fa46db294558250 Mon Sep 17 00:00:00 2001 From: Abdul Manan Date: Fri, 21 Aug 2026 17:18:02 -0400 Subject: [PATCH 2/2] docs: fix duplicate HyperCore fill table headers --- content/api-reference/websockets/hypercore/all-fills.mdx | 2 -- content/api-reference/websockets/hypercore/builder-fills.mdx | 2 -- .../api-reference/websockets/hypercore/liquidation-fills.mdx | 2 -- content/api-reference/websockets/hypercore/user-fills.mdx | 2 -- 4 files changed, 8 deletions(-) diff --git a/content/api-reference/websockets/hypercore/all-fills.mdx b/content/api-reference/websockets/hypercore/all-fills.mdx index 3c01620c8..e11d9eabb 100644 --- a/content/api-reference/websockets/hypercore/all-fills.mdx +++ b/content/api-reference/websockets/hypercore/all-fills.mdx @@ -83,8 +83,6 @@ description: "HyperCore private-preview documentation." | fills | array | Fill records. | | fills[] | object | Fill record. | | fills[].user | string | User identifier for the fill. | -| Field | Type | Description | -| --- | --- | --- | | fills[].coin | string | Market symbol for the fill. | | fills[].px | string | Execution price. | | fills[].sz | string | Executed size. | diff --git a/content/api-reference/websockets/hypercore/builder-fills.mdx b/content/api-reference/websockets/hypercore/builder-fills.mdx index d57cdbe72..c08dc9142 100644 --- a/content/api-reference/websockets/hypercore/builder-fills.mdx +++ b/content/api-reference/websockets/hypercore/builder-fills.mdx @@ -83,8 +83,6 @@ description: "HyperCore private-preview documentation." | fills | array | Fill records. | | fills[] | object | Fill record. | | fills[].user | string | User identifier for the fill. | -| Field | Type | Description | -| --- | --- | --- | | fills[].coin | string | Market symbol for the fill. | | fills[].px | string | Execution price. | | fills[].sz | string | Executed size. | diff --git a/content/api-reference/websockets/hypercore/liquidation-fills.mdx b/content/api-reference/websockets/hypercore/liquidation-fills.mdx index 042d18955..b013abdda 100644 --- a/content/api-reference/websockets/hypercore/liquidation-fills.mdx +++ b/content/api-reference/websockets/hypercore/liquidation-fills.mdx @@ -83,8 +83,6 @@ description: "HyperCore private-preview documentation." | fills | array | Fill records. | | fills[] | object | Fill record. | | fills[].user | string | User identifier for the fill. | -| Field | Type | Description | -| --- | --- | --- | | fills[].coin | string | Market symbol for the fill. | | fills[].px | string | Execution price. | | fills[].sz | string | Executed size. | diff --git a/content/api-reference/websockets/hypercore/user-fills.mdx b/content/api-reference/websockets/hypercore/user-fills.mdx index 0e8889f15..d50ccbb51 100644 --- a/content/api-reference/websockets/hypercore/user-fills.mdx +++ b/content/api-reference/websockets/hypercore/user-fills.mdx @@ -83,8 +83,6 @@ description: "HyperCore private-preview documentation." | fills | array | Fill records. | | fills[] | object | Fill record. | | fills[].user | string | User identifier for the fill. | -| Field | Type | Description | -| --- | --- | --- | | fills[].coin | string | Market symbol for the fill. | | fills[].px | string | Execution price. | | fills[].sz | string | Executed size. |