Am/hypercore rest expansion

[abdulmanan-creator]

Description

HyperCore private-preview documentation. Contract work rather than formatting.

The REST reference expands from 8 documented operations to roughly 45 native-compatible
reads, grouped into eleven resource families. Request parameters, response-field
contracts, and populated examples are sourced from the Hyperliquid Foundation's /info
documentation, Alchemy's published Info endpoint page, and live probes against the
native API. Adds three new pages and unifies the order-book bootstrap model across the
stateful stream pages, which previously described incompatible procedures on WebSocket
versus gRPC.

Pages stay out of nav and site search via hidden: true on the two net-new top-level
sections; direct URLs resolve. A customer is actively reading these docs and the node
peering page is under external review.

Related Issues

No Linear ticket — this was authored directly rather than through docs-agent. Follows
the branch-and-PR workflow in the Docs Contribution Guide.

Changes Made

REST reference (36 new pages, 11 sections)

• Account state, orders and fills, ledger and funding, market data and snapshots, asset
  context, metadata, token deployment, vaults, staking/delegation/validators,
  roles/agents/limits, and outcome markets
• Five reads with genuinely multi-variant responses document each variant rather than
  flattening: userRole (5), metaAndAssetCtxs, activeAssetData, and userFunding
  (first perpetual DEX vs HIP-3)
• oraclePx documented on metaAndAssetCtxs as the native path to a current oracle
  price, cross-referenced from the setOracleUpdates stream

New pages

• HyperCore node peering
• Deploying markets on Hyperliquid (HIP-3 and HIP-4)
• trades WebSocket stream

Stream pages

• Single order-book bootstrap model across l2BookDiff, l4BookUpdates, and
  tpslUpdates on both transports, plus both book guides
• Real field types and descriptions replacing placeholders across the payload tables
• Fixed a duplicate markdown table header on the four fills pages

Navigation (content/docs.yml)

• Two new hidden: true top-level sections in the chains tab, siblings of
  HyperCore gRPC
• trades added to the existing HyperCore Streams block
• Eleven REST family sections inside the existing Data tab REST API section,
  alongside the generated api: block rather than replacing it

Known and deliberate

• Three snapshot operations are documented ahead of backend implementation
• Four pages state explicitly that their response shape is unconfirmed, where the
  native API accepted the request but returned only empty payloads
• The in-band bootstrap model reflects a settled product decision pending engineering
  confirmation; the REST snapshot path remains documented as the alternative

Testing

• I have tested these changes locally
• I have run the validation scripts (pnpm run validate)
• I have checked that the documentation builds correctly

pnpm generate, pnpm generate:rest, pnpm validate, pnpm validate:rest,
pnpm validate:docs-yml, and git diff --check all pass.

pnpm lint exits non-zero on a single pre-existing TypeScript error already on main:
src/content-indexer/visitors/processors/__tests__/process-openapi.test.ts(507,32),
Property 'path' does not exist on type 'NavItem'. No content failure contributes.

This is a content-only repo with no local dev server, so the PR preview is the
authoritative render check.

[github-actions]

🔗 Preview Mode

Name	Status	Preview	Updated (UTC)
Alchemy Docs	✅ Ready	🔗 Visit Preview	Aug 21, 2026, 9:20 PM

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2bb65012ca

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Describe trade participants as maker and taker

The native trades payload orders users as maker then taker, not buyer then seller. For a buy-side taker, the maker is the seller, so consumers following this description will reverse the two addresses and misattribute trades. Document the tuple as [maker, taker] and use side when buyer/seller attribution is needed.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Remove purpose-built composites from the /info enum

Because InfoTypeRequest is the request schema for POST /{apiKey}/info, these enum members advertise portfolioState and extraAgents as valid /info discriminators. The same change documents them as purpose-built reads at /portfolio-state and /extra-agents, and they are not native /info types, so generated clients and the API explorer can construct requests that the endpoint rejects. Remove these values from this enum or expose actual /info aliases.

Useful? React with 👍 / 👎.