> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/normative-design/api-strategy.md).

# Perpetual venue API strategy

## Robinhood Chain provider plane

The server owns all Robinhood Chain endpoints. Every allowed JSON-RPC read first uses the primary transport and fails over once to the configured fallback after the primary's bounded retry/circuit policy is exhausted. Network probes independently query both providers, require chain ID 4663, compare block height against `RHC_MAX_BLOCK_DIVERGENCE`, and fail closed on divergence. HTTP outcomes feed a bounded rolling error/latency window. `GET /api/rhc/providers` emits only provider class/role, aggregate transport telemetry, block evidence and readiness state; credential-bearing URLs are never serialized.

The official public RPC remains a diagnostic default. Per Robinhood Chain's current connection documentation, production readiness requires reviewed managed HTTP and WSS providers plus archive access for historical reads. NIGHTSHIFT requires each WSS endpoint to match its HTTP provider family, opens it server-side, verifies `eth_chainId`, subscribes to `newHeads`, requires a real head, compares that head with the corresponding HTTP view, detects message staleness, reconnects with bounded exponential jitter and resets readiness after any incident. Two distinct live providers, redundant archive attestations, fresh in-range WSS heads and the configured stabilization window must all pass before the data plane reports production-ready.

Public-wallet activity reads the 27 reviewed token contracts through canonical `Transfer` logs in bounded descending chunks, checkpointing only after both incoming and outgoing filters succeed. A separately checkpointed native rail is enabled only when the primary server-side endpoint is Alchemy, the provider Robinhood currently recommends for its indexed Data API. It calls `alchemy_getAssetTransfers` for exact `external` inbound/outbound value transfers, reads raw wei, caps pages at 100 rows and fails a chunk closed on malformed data, pagination pressure or provider loss. Internal contract transfers are explicitly excluded because Alchemy does not provide that category on this L2. Both rails rewind the recent tail and expose independent gaps; the public/default RPC keeps native ETH unavailable. A safe block tag is preferred, a confirmation-buffer fallback is partial, and deep `before` pagination requires redundant archive access. Historical ERC-8056 share-equivalent amounts are not inferred.

## Arcus Robinhood Chain rail

Arcus mainnet public REST and WebSocket APIs provide live market discovery, marks/oracles, candles, books, recent public trades, funding, open interest, volume, public account state, compliance and transfer updates. NIGHTSHIFT exposes only markets whose live metadata status is `ONLINE`; unsupported or malformed symbols fail closed at the BFF. The configured base URL is pinned to the official HTTPS origin to prevent arbitrary server-side fetches. The trade tape bootstraps from `GET /v1/trades`, then merges the `trades` stream by venue trade ID; counterparty addresses are discarded at normalization.

Arcus and Hyperliquid REST reads share a bounded server runtime: exact official-origin pinning, streamed response-byte limits, concurrency caps, typed error codes, cooldown circuit breaking and one half-open recovery probe. Upstream error bodies are cancelled rather than read. Public account fan-outs use a SHA-256 opaque venue/account key and a bounded local request window; `/api/market/health` returns aggregate counters and state only. These controls protect NIGHTSHIFT but do not replace either venue's own limits.

Protected orders require a user-generated Ed25519 API key registered by the owner EVM wallet. A future isolated signer must bind idempotency, exact price/size quantums, compliance, confirmation and WebSocket order/fill reconciliation. It must not share the Hyperliquid signer or accept a key in browser storage. See [`arcus.md`](/nytshift-docs/normative-design/arcus.md) for the implemented endpoint matrix and release gates.

## Hyperliquid rail

## Real-time subscriptions

Use WebSockets for the live path. Pool subscriptions, monitor message age, send a heartbeat on quiet connections, reconnect with bounded jitter and mark state stale while gaps are unresolved.

The browser supervisor owns exactly one public socket per venue. Market overview, selected-market trades and candles are ref-counted onto that transport; reconnect replays the active set and the final consumer sends an exact unsubscribe before idle shutdown. Incoming frames are byte bounded, malformed frames cannot replace verified state, Hyperliquid receives one pooled heartbeat, and conservative local ceilings hold subscriptions, outbound messages and new connection attempts below the documented venue envelope. Health snapshots contain counts/reason codes only—never endpoints, symbols, account identifiers or payloads.

| Need     | Subscriptions                                                                         | Snapshot/recovery                                    |
| -------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Market   | `allDexsAssetCtxs`, `l2Book`, `trades`, `candle`                                      | subscription snapshot where supplied; Info backfill  |
| Account  | `clearinghouseState`, `openOrders`, `orderUpdates`, `userFills`                       | Info reconciliation on boot, reconnect and interval  |
| Orders   | signed action through `/exchange`                                                     | `orderUpdates`, `userFills`, query by `cloid`/status |
| Metadata | Info `perpDexs`, `allPerpMetas`, `metaAndAssetCtxs`, `spotMeta`, borrow/lend reserves | refresh on boot and schema/version mismatch          |

Always query account data with the master/subaccount address, not the agent-wallet signing address. Resolve asset IDs and tick/lot constraints from metadata; do not hard-code indices.

Public Hyperliquid streaming keeps midpoint and mark authority separate. `allMids` is midpoint evidence only and cannot update a terminal mark. The bounded `allDexsAssetCtxs` parser binds primary and HIP-3 contexts by exact DEX plus reviewed metadata index, then feeds the same temporal mark transition used by REST recovery. A mark move larger than 25% requires a close same-frame oracle; otherwise the prior accepted mark/time are retained and feed state degrades until a corroborated observation arrives. The terminal then projects `markState` independently for each consumer: a held value produces no alert observation, paper mark, chart-risk mark, order shortcut or unlabeled watchlist/search/brief/book price. Only an evidence view can show it, explicitly named `LAST ACCEPTED ... HELD`.

The protected Hyperliquid control plane also reconciles the exact configured signer account before any review or policy-bound attempt. It discovers the full perp DEX set, binds sparse DEX slots to `allPerpMetas.collateralToken`, reads each DEX's timestamped clearinghouse/open orders, resolves locally missing active orders through exact `orderStatus`, pages unaggregated `userFillsByTime` and `userFunding` under documented bounds, and persists only an opaque account digest. Strict `spotMeta` identity plus borrow/lend reserve oracles convert Standard, Unified and Portfolio Margin capital and HIP-3 lifecycle values into the common USD model. Debt reduces Portfolio Margin equity; NIGHTSHIFT does not reconstruct LTV borrowing or asset caps. Fresh review reads `activeAssetData` and requires its active leverage, side-size limits and available-to-trade capacity before AEGIS evaluation. A mismatch can only enter a separate leverage-only operator review that preserves current cross/isolated mode, calls the official SDK at most once, proves application from a new `activeAssetData` read and requires a new order review. Policy-bound automation has no access to that action.

## Capacity envelope

External limits are configuration and alert thresholds, not constants embedded in business logic. At the July 2026 documentation baseline, Hyperliquid documents an aggregate 1,200 REST weight per minute per IP, endpoint-specific weights, WebSocket connection/subscription/message limits and address-based action limits. Batch carefully: an order batch may be one IP-weighted request while still counting as multiple address actions. Arcus does not publish a numeric unauthenticated budget in the accessible public reference, so NIGHTSHIFT keeps its local ceiling conservative and configurable without labeling it an Arcus limit.

For the public browser transport NIGHTSHIFT permits one concurrent connection per venue, at most 64 active subscriptions, 600 sent frames per rolling minute and 20 new connection attempts per rolling minute. Hyperliquid currently documents 10 connections, 30 new connections/minute, 1,000 subscriptions and 2,000 sent messages/minute per IP; NIGHTSHIFT's lower ceilings preserve headroom for operator tooling and future authenticated reconciliation. The Arcus ceilings are NIGHTSHIFT safeguards, not claimed Arcus limits.

## Idempotency and ambiguity

* Create a 16-byte `cloid` before submission and persist it with the intent.
* The execution service deduplicates by `intent_id`; production uses a unique transactional database constraint.
* Never automatically resend a timeout. Reconcile by `cloid`, order status, open orders and fills.
* Use `expiresAfter` for supported actions, but note that stale-expiry cancellation consumes additional address rate budget.
* Separate IOC/GTC and ALO batches if batching is introduced.

## Schema drift

External JSON is validated at the adapter edge. Capital-moving metadata uses reviewed known-field sets: additive fields raise schema drift until their meaning is reviewed. Missing/invalid required fields generate a typed adapter error and mark affected state stale. Raw account/provider payloads are not persisted in NIGHTSHIFT telemetry or checkpoints.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nytshift.gitbook.io/nytshift-docs/normative-design/api-strategy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.