Skip to content

Connection security

Hyperliquid Nonces: Signer State vs Timestamps

Check signer identity, retained nonce state and block-time validity separately with a worked Hyperliquid ledger and client validation fixtures.

Ivory circular tray of blank tabs with one lime tab beside an ivory hourglass on a dark background
Illustration for connection security; examples in this article are educational.

Hyperliquid nonces are replay identifiers tracked per signer. A nonce must be unused, exceed the smallest value in the signer's retained set of 100 highest nonces, and fall inside the documented block-time window. Millisecond timestamps are a convenient starting point, but concurrent requests still need coordinated allocation; changing the target subaccount does not create a separate nonce tracker.

The official nonce rules, checked on 29 October 2026, describe a set that tolerates some out-of-order arrival. A timestamp can satisfy the clock check while failing the set check. The following ledger separates those decisions so an operator can explain a rejection without guessing that every smaller number is stale.

Identify the signer before inspecting the nonce

Record the address whose key signed the action separately from the account being operated. An approved API wallet, also called an agent, can sign for a master account and its subaccounts. Account reads use the actual master or subaccount address. The API-wallet and master-address comparison develops that identity boundary.

Suppose agent A signs one order for subaccount S1 and another for S2. Giving each subaccount an independent counter can allocate the same number twice under A. Different balances and position records do not separate the replay state of their common signer. Querying S1 correctly also does not establish that S1 owns a nonce tracker.

An incident record therefore needs both identities: signer A, target S1 or S2, environment, action identity and allocated nonce. Avoid shortening this to an ambiguous “wallet” column. Two services can appear to operate different accounts while sharing the key that matters for this check.

This guide concerns signed Hyperliquid /exchange actions. HyperEVM transactions require their own EVM nonce model. The strict transaction sequence described in the EVM nonce guide is a different mechanism. Importing its gap-filling or same-nonce replacement assumptions would give the wrong recovery plan here.

Check an out-of-order sequence against a full retained set

Consider a hypothetical signer A at a fixed illustrative block time of 1,800,000,000,000 milliseconds. Call that base value B. Initially, A's retained set contains exactly 100 values: B plus every even offset from 2 through 200. There are 200 / 2 = 100 such offsets. Its smallest retained value, or floor, is B + 2. Assume those values were used and all other illustrated offsets are unused.

The table shows only offsets to keep the numbers readable. Every row uses signer A. Assume signatures, authority and action contents otherwise pass; “eligible” means passing the modeled nonce conditions, not obtaining an order fill. All five arrivals fall inside the time window. Successful modeled admissions retain the highest 100 values; the illustrated nonce rejections leave the model unchanged.

Arrival offsetSmallest offset beforeNonce decisionSmallest offset after
2042Eligible: unused and above the floor4
2034Eligible despite arriving after 2046
203 again6Reject: already used6
56Reject: unused, but below the floor6
2026Eligible: unused and still above the floor8

After the first arrival, offset 2 drops out of the highest 100. After the second, offset 4 drops out. Offset 203 can follow 204 because the comparison uses the retained minimum, rather than demanding a value above the maximum.

Offset 5 exposes the less obvious failure. It would have cleared the starting floor of 2. By its actual arrival, the floor is 6. Its numerical age is only a few milliseconds relative to B, yet it fails because other accepted work has advanced the retained set. Waiting less than the protocol's time allowance cannot guarantee admission.

Offset 202 then shows that a missing number does not hold up the sequence. Its arrival remains admissible in this construction. The count stays 100 after each successful update. These results were checked with integer arithmetic and explicit set updates; the example does not claim access to Hyperliquid's engine implementation or its ordering of validation checks.

Calculate the time window independently

The documented interval is strictly inside two days before and one day after the transaction block's Unix millisecond time T. Its endpoints are excluded. For the same hypothetical T, two days equal 172,800,000 milliseconds and one day equals 86,400,000 milliseconds.

The lower boundary is 1,799,827,200,000.

The upper boundary is 1,800,086,400,000.

Candidate nonceTime check alone
Lower boundary exactlyFails
Lower boundary plus 1 msPasses
Upper boundary minus 1 msPasses
Upper boundary exactlyFails
1,800,000,000, mistakenly expressed in secondsFails

Each row is an independent time-predicate check. A passing row still needs an unused nonce above that signer's retained minimum. In particular, the lower-boundary-plus-one candidate would fail the retained-set check in the earlier ledger. Combining the two tables without that distinction would produce a false acceptance result.

Use the block-time comparison when reasoning about eligibility. A local timestamp records what the signing machine believed; it does not establish the eventual block time or the delay before evaluation. Track local request duration separately, as the wall-clock and monotonic-clock guide explains.

Clock repair also cannot undo a collision. If two workers already allocated an identical number, making their clocks more accurate afterward does not change their signed attempts. Diagnose units, clock state and signer allocation as separate evidence.

Know what the pinned Python SDK actually supplies

In the official Python SDK at commit 2fdb18f951767, get_timestamp_ms() returns int(time.time() * 1000). That helper contains no incrementing counter. The inspected bulk_orders path calls it once and uses the result for both signing and the outer request nonce. See the full immutable links to the timestamp helper and order submission path.

If two calls observe the hypothetical millisecond 1,800,000,000,300, raw timestamp allocation gives both that nonce. Nothing about converting seconds to integer milliseconds makes those observations unique. An application wrapper may coordinate allocation, and another SDK may implement a counter; inspect the client actually deployed before diagnosing its behavior.

The same pinned signing implementation binds the nonce, target-address encoding and optional expiry into the L1 action hash. Altering the nonce or target after signing changes the signing input. A recovery that needs different fields must reconstruct the appropriate signed request, rather than edit an authenticated envelope in transit.

Nonce correctness is only one part of preparing that request. The Hyperliquid size and price decimal guide handles instrument constraints; passing a replay check cannot establish that a quantity or price is valid.

Coordinate allocation across every writer using the key

A proposed client policy can allocate the greater of synchronized wall-clock milliseconds and the last-issued nonce plus one. The read, comparison and update must form one atomic operation. Assume the last-issued nonce is 1,800,000,000,299. At the fixed millisecond above, two coordinated allocations then produce 1,800,000,000,300 and 1,800,000,000,301.

That arithmetic is an application design example. Its correctness depends on who shares the allocator. A lock in one process cannot coordinate another process with its own memory. Include manual tools, retry workers and replacement instances in the ownership design. A restart that forgets issued values can recreate a collision while every running host reports correct time.

For each signer, retain enough durable allocation and attempt records to investigate a restart or missing response. Record which attempts may have left the process, and bound unresolved work so delayed requests do not silently fall behind a moving retained floor. A separate signer per process or subaccount can reduce shared-state collisions, subject to the actual approval arrangement.

Also monitor how far an incrementing counter leads synchronized time. A counter can advance faster than milliseconds during a burst. It still has to satisfy the future-time boundary. “Always increase” solves neither clock validity nor the lifecycle of already signed work by itself.

Keep expiry, retries and agent rotation explicit

For supported actions, expiresAfter supplies a separate millisecond rejection deadline. The exchange endpoint documentation excludes user-signed actions such as Core USDC transfer from that field's support. Configure it for the particular action; the nonce interval alone is too broad to express many trading decisions' useful lifetime.

A request can therefore pass both nonce tests and still be past its chosen action deadline. Conversely, a timely deadline cannot rescue a duplicate nonce. Keep the nonce, deadline and trading intent in separate fields when explaining a result.

After a missing response, allocating a fresh nonce creates another signed attempt. It does not prove the original order failed. Reconcile the original identified action before creating more exposure; the order timeout recovery guide provides that business-outcome discipline.

Agent lifecycle changes need their own review. Hyperliquid warns that pruning an API wallet's nonce state can make old signatures replayable and advises against reusing agent addresses. Replays remain subject to the action's other applicable checks. An archived “used” label is insufficient evidence after such a transition. Generate a fresh agent address for future use under the documented approval process, and keep old signing material out of routine operational logs.

Validate the boundary with controlled fixtures

Run these cases in a local model or an appropriate controlled test environment before relying on an allocator. They are proposed checks, not claims about KLINEO test coverage.

FixtureEvidence to retain
Two workers observe the same millisecondSigner, both allocated values and atomic ownership
Arrival 204 followed by 203 in the exampleRetained minimum before and after each admission
Delayed unused offset 5The advanced floor, independently of clock age
Each exact time boundaryMillisecond inputs and strict inequality result
One signer targets two subaccountsShared allocation scope and distinct target identities
Restart or agent rotationPrior attempts, new signer identity and nonce-state assumptions

For every disputed attempt, establish who signed, which account was targeted, whether the number was allocated before, and which accepted requests could have advanced the retained minimum while it waited. Then check time and action expiry separately. Resume work when those records explain the decision and the original order outcome is resolved.

Keep the context with the example.

Each worked example is illustrative, with its sources and assumptions in the article. Read our editorial standards for authorship, verification and corrections.