feat(perp): Hyperliquid perpetual trading and bridge commands

[kome12]

Adds two command families to the CLI: nansen perp for Hyperliquid perpetual trading, and nansen bridge for moving funds between EVM chains and Hyperliquid.

Large diff (~4k lines across 27 files), so the reviewer guide below groups it by concern.

What you can do with it

nansen perp order --coin BTC --side buy --size 0.001 --price 50000 --type limit
nansen perp close --coin BTC --size 0.001 --side sell
nansen perp leverage --coin BTC --leverage 10 --margin-type cross
nansen perp transfer --direction spot-to-perp --amount 25
nansen perp positions | orders | account | meta

nansen bridge quote --from-chain base --to-chain hyperliquid --from-token USDC --amount 1000000
nansen bridge execute --quote <quoteId>
nansen bridge status --request-id <id>

How orders are submitted

Orders are built, signed and submitted from the user's own machine straight to api.hyperliquid.xyz/exchange — they are not relayed through the Nansen backend. Reads and market data still go through the API.

That has two consequences worth reviewing carefully:

1. The signing path is ours now. src/hl-action.js builds the L1 action (msgpack + action_hash + EIP-712) and src/hl-client.js submits it. A mistake here signs the wrong payload, so both have dedicated round-trip tests.
2. Compliance checks happen before signing, and fail closed. Every mutating command screens the wallet against the sanctions list first and refuses to sign if that check cannot complete. The builder-fee approval is fetched from the API on the same path and also fails closed.

Reviewer guide

Area	Files
Action building + hashing	src/hl-action.js, src/__tests__/hl-action.test.js
Direct submission	src/hl-client.js, src/__tests__/hl-client.test.js
Perp commands + screening/fee gate	src/perp.js, src/__tests__/perp.test.js
Bridge commands	src/bridge.js
Wiring, help text, schema	src/cli.js, src/schema.json
Input validation shared with trade	src/trading.js, src/limit-order.js, src/keychain.js

Merge with main

Main moved a long way while this branch sat (Node 18 dropped, vitest 4.1, x402 BSC support, new perp screener filters), so main is merged in — 35a9f1e — rather than rebased, to keep the tested history intact. Two collisions needed resolving:

• src/rpc-urls.js — main added a bsc RPC entry for the x402 payment path; this branch added bnb for bridge/perp. Same chain (56) under two spellings, each read by different code (x402.js reads CHAIN_RPCS.bsc; chain-ids.js/bridge.js use 'bnb'), so both keys are kept with the default each side shipped. Worth unifying later — deliberately not done here, since collapsing them changes which RPC the payment path uses.
• src/cli.js — this branch re-pointed bare perp at the trading dispatcher, which silently shadowed the existing perp analytics command that main had just extended. git merged the file clean; the breakage was semantic — nansen perp screener and nansen research perp screener both threw Unknown perp subcommand (research dispatches through cmds[category], so both forms broke). Fixed by falling through to the analytics handler for screener/leaderboard. This is the part of the diff most worth a second pair of eyes.

Known nit, matching main's existing split: perp help lists the analytics subcommands, perp --help (schema-driven) does not, because main documents them under research perp in schema.json. Left as-is.

Release notes

Four changesets ship with this PR; .changeset/error-envelope-unification.md is the one that matters to existing consumers:

Changeset	Bump	Covers
error-envelope-unification.md	minor	Output shape change — every failure now serializes as {success, error, code, status, details}. Previously a CommandError printed its payload at the top level, so trade, limit-order and the API-key flows differed from everything else. Nothing is lost (payload preserved under details), but anything parsing those errors positionally must read details.
bridge-execute-screening.md	patch	Pre-sign fail-closed sanctions screening on bridge execute, plus refusal when the signing wallet isn't the quote's wallet.
hl-direct-submit.md	patch	Direct-to-Hyperliquid submission path.
hl-action-builder.md	patch	Client-side action builder.
perp-bridge-input-safety.md	patch	Client-side input validation for perp/bridge.

Verification

• Full suite green: 1652 passed, 2 skipped at 0627a12. (7 were failing on the merge before the perp screener fall-through fix; the later counts include 14 tests added for the review fixes.)
• eslint clean — it caught a real gap while fixing the replay marking: the Privy signature path had the callback threaded through but never invoked, which would have left that path unmarked.
• Ran against the real CLI: perp --help, perp help, bridge --help, perp screener and research perp screener (both return live data), and an unknown subcommand still errors with the combined list.
• The end-to-end trade and bridge paths were last exercised against mainnet with real funds before this merge; they need an unlocked wallet and funds, so they were not re-run as part of it. Worth one live order + one bridge leg before release.

Review fixes since the merge

• 54386c0 — consume the bridge quote on the first broadcast, not the last (partial-failure retry could re-send an already-broadcast step).
• 8ab8bb4 — fail-closed sanctions screening before signing on bridge execute, and mark at each individual broadcast before receipt polling. Worth knowing for the compliance story: the EVM deposit leg broadcasts via eth_sendRawTransaction straight to a public RPC, so it never transits the Nansen API at execute time — only the HL-signature leg is proxied. This client-side screen is what covers deposits between quote and broadcast.
• 0627a12 — screen the wallet that actually signs, and refuse a quote/wallet mismatch.

🤖 Generated with Claude Code

[gulshngill]

Code Review — feat/hl-perp-trading

Reviewed at 0627a12. All findings below were verified live against the prod API and CLI (not inferred from static analysis alone). Unit tests: 1650 pass / 2 fail — both failures are in package.test.js and reproduce on main, not caused by this PR.

---

🔴 Critical (blocks merge)

C1 — bridge execute crashes on 4 of 5 advertised EVM origin chains

BRIDGE_CHAINS (src/bridge.js:41) lists ethereum, base, arbitrum, polygon, bnb, hyperliquid. src/rpc-urls.js adds RPC endpoints for arbitrum/polygon/bnb. USDC token addresses are defined for all four in src/bridge.js:32-36. But signEvmTransaction (src/trading.js:517) resolves the chain through CHAIN_MAP (src/trading.js:25-28), which only contains solana and base.

Verified live:

• bridge quote --from-chain arbitrum → succeeds, quote file written
• bridge execute on that quote → Unsupported EVM chain: arbitrum
• Same for polygon, bnb. Ethereum gets further (RPC auth error) but hits the same wall.

No funds at risk — throws before broadcast. But the feature is non-functional on 4 of 6 advertised chains.

Fix: add ethereum (1), arbitrum (42161), polygon (137), bnb (56) to CHAIN_MAP in trading.js, or trim BRIDGE_CHAINS to ['base', 'hyperliquid'] and update help/README.

---

🟠 Major

M1 — Usage banners regressed to escaped JSON blobs across the whole CLI

The unified error envelope (src/cli.js:1995-2002) now routes MISSING_PARAM/MISSING_ARGS through formatOutput, which serialises \n as literals. Hits pre-existing commands, not just the new ones.

Verified live — nansen trade quote (no args):

{"success":false,"error":"\nUsage: nansen trade quote --chain <chain>...","code":"MISSING_ARGS","status":null}

Same for nansen perp order --coin ETH (missing side/size/price).

Fix: when stdout is a TTY and no --json/--pretty/--csv, print error.message raw for usage codes instead of serialising.

---

M2 — bridge is absent from schema.json; perp endpoints are stale

Verified:

node src/index.js schema | jq '.commands | has("bridge")'  # → false

bridge is a new top-level command group and is completely missing from schema — breaks any agent consuming nansen schema.

Also: every mutating perp subcommand (order/cancel/close/leverage/transfer) still lists /api/v1/perp/* as endpoint. After the direct-to-HL refactor, signing goes to api.hyperliquid.xyz — the schema is wrong.

---

M3 — Compliance screening and postBridgeExecute are cacheable/retryable

postBridgeExecute (src/bridge.js:114-116) passes no options to request(), inheriting the default 3× retry on [429, 500, 502, 503, 504]. Relay's /authorize is not idempotent — a 500 retry can double-submit.

Same issue with screenOrThrow under --cache: a cached SDN verdict from within the 5-minute TTL is returned instead of a live check, undermining the "every action re-screens the signing wallet" guarantee.

hl-client.js:59-62 already documents why submitExchange must not retry — postBridgeExecute should follow the same pattern.

Fix: pass { cache: false } on every call in perp.js/bridge.js, and { cache: false, retry: false } on postBridgeExecute.

---

M4 — Builder fee is auto-signed from an unbounded server-supplied value

ensureBuilderApproved (src/perp.js:294-305) fires silently on first trade — no fee displayed, no confirmation, no ceiling. required_fee: 10000 → signs "10%" with no user awareness. Only validation is Number.isInteger(required_fee).

The only threat model here is a compromised API (we trust our own API over TLS), so this is defence-in-depth rather than an active exploit. Suggest a MAX_BUILDER_FEE_TENTHS_BP constant and logging the approved rate before signing.

---

M5 — Bridge EIP-712 signing produces a degenerate digest when API omits types

processSignatureStepLocal (src/bridge.js) does (types[primaryType] || []).map(...). With types = {}, fields is empty and hashStruct (src/x402-evm.js:111-124) hashes keccak256(typeHash("HyperliquidTransaction()")) — a valid-looking signature over none of the action's actual contents.

Verified live: called hashTypedData with fields=[] — it returned a hash instead of throwing.

Fix:

if (!signData.eip712Types?.[primaryType]?.length) {
  throw new Error(`Bridge step ${step.id} is missing EIP-712 types; refusing to sign.`);
}

---

M6 — bridge.js didn't receive the wallet hardening that perp.js got

Three divergences:

1. Misleading password error — resolveWalletCredentials calls exportWallet(name, null) when no password is found, producing "Incorrect password" even though nothing was entered. perp.js:158-170 fixes this exact issue with PASSWORD_REQUIRED + resolution steps. Lift that into a shared helper.
2. No EVM address validation — bridge.js:429 returns wallet.evm unchecked. perp.js:137-141 rejects wallets with no valid 0x…40 EVM address. A Solana-only wallet sends address: null to the quote endpoint.
3. Double wallet resolution — execute resolves signer at :612 then resolveWalletCredentials(walletName) independently at :630. Agree today, subtle divergence risk later.

---

M7 — --recipient and base-unit --amount unvalidated client-side on bridge quote

Verified: both --recipient not-an-address and --amount abc reach the API and get a 422 back — so no fund-loss risk, the API is the backstop. But there's no client-side guard. validateAddress is already exported from api.js.

---

M8 — NANSEN_HL_API_URL testnet support is broken

source: 'a' (src/hl-action.js:400) and hyperliquidChain: 'Mainnet' (:449, :467) are hardcoded. Pointing the env var at testnet still produces mainnet signatures that testnet rejects.

Fix: derive source/hyperliquidChain from the resolved base URL, or narrow the doc comment to "for tests only, not testnet".

---

🟡 Minor (selected)

• Dead code: effectiveOrderValues (src/perp.js:182) is exported but nothing outside tests imports it — made redundant by the direct-submit refactor.
• nansen research perp help now shows the trading command help instead of the analytics help (screener/leaderboard). The screener/leaderboard passthrough still routes correctly — just help is wrong.
• pollBridgeCompletion swallows all errors (src/bridge.js:405-408) — any non-BRIDGE_FAILED error logs "poll error — retrying..." for up to 10 minutes with no detail.
• request_id may be undefined at src/bridge.js:695 — timeout message reads nansen bridge status --request-id undefined.
• buildUsdClassTransferAction uses .toFixed(8) (src/hl-action.js:463) which returns exponential notation for values ≥ 1e21 — parsePositiveNumber has no upper bound so an absurd --amount produces a malformed wire string.
• Full minor list (13 items) in the detailed review file at /home/node/repos/nansen-cli/.worktrees/pr467-review/PR467-code-review.md.

---

✅ What passed in live testing

Check	Result
perp account / positions / orders / meta	✅
perp order (ETH limit, resting) + perp cancel	✅
perp leverage	✅
bridge quote (HL → Base)	✅
bridge execute (HL → Base specifically)	✅
bridge execute (Base → HL)	✅
All unit tests (1650)	✅
Prod API endpoints (/perp/meta, /perp/account, /perp/positions)	✅

---

Suggested merge path

1. Fix C1 (CHAIN_MAP + test) + M1 (usage banners) — highest blast radius
2. Fix M2 (schema) — required by CLAUDE.md
3. Fix M3 (cache: false, retry: false) + M5 (throw on missing EIP-712 types) — both are a few lines
4. M4, M6, M7, M8 can follow in a fast-follow if time-boxed, but M6.1 (misleading password error on bridge execute) will generate support noise immediately

[kome12]

All of C1 and M1–M8 are done, plus the five minors you listed — pushed as 57efabf and 0a182d3. 1783 tests passing, eslint clean.

Two things need you:

1. M4 — I set the ceiling equal to the published rate rather than a loose multiple. Strongest version of what you asked for, but it couples the fee to a release: raise the rate and every installed CLI refuses to trade until upgraded. Happy to widen it if you'd rather have headroom.
2. The other 8 minors — your comment lists 5 and points at a detailed review file in your own environment, which I can't read. Could you paste them here?

While finishing the Base → HL leg I found why it never landed: getEvmNonce returns a decimal number and bridge.js decoded it as hex a second time, so parseInt(20, 16) === 32 — a wallet at nonce 20 signed at 32. It's been there since the bridge commands were added and is invisible below nonce 10, where the two coincide, so it only bites once a wallet passes 9. Fixed with a regression test; getEvmNonce now also reconciles pending against latest. Separately, bridge execute takes --priority-fee/--max-fee/--nonce so a stuck transaction can actually be replaced — previously the fees were recomputed identically and every retry returned replacement transaction underpriced.

Base → HL, 5 USDC, first attempt, nonces 20/21 in blocks 49250636/49250637 — the deposit leg is now verified with real funds, as the withdrawal leg was. The recovery flags are unit-tested only; nothing was stuck to try them against.