nansen-cli 1.34.0 → 1.36.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## 1.36.0
+
+### Minor Changes
+
+- [#467](https://github.com/nansen-ai/nansen-cli/pull/467) [`54386c0`](https://github.com/nansen-ai/nansen-cli/commit/54386c0f3280fcc06c8bb7a5d18956d45b2d3d63) Thanks [@kome12](https://github.com/kome12)! - **Output shape change:** every command failure now serializes through the same error envelope — `{success: false, error, code, status, details}`. Previously a `CommandError` printed its structured payload at the top level instead, so errors from `trade`, `limit-order` and the API-key flows (`NOT_A_TTY`, `API_KEY_REQUIRED`, `INVALID_API_KEY`, `VERIFICATION_FAILED`) came back in a different shape from everything else.
+
+  Nothing is lost — the previous top-level payload is preserved verbatim under `details` — but anything parsing those errors positionally needs to read `details` instead of the root object. The new `perp` and `bridge` commands raise `CommandError` throughout, so without this they would have been the third distinct error shape in the CLI.
+
+  One deliberate exception: a missing-argument usage banner (`MISSING_PARAM`, `MISSING_ARGS`) prints as plain text when stdout is an interactive terminal and no output format was requested, because those messages are multi-line help written to be read and serializing them renders every newline as a literal `\n`. Piped output, and any run with `--pretty`, `--table`, `--format csv` or `--stream`, still gets the envelope — so nothing consuming the CLI programmatically sees a different shape.
+
+### Patch Changes
+
+- [#467](https://github.com/nansen-ai/nansen-cli/pull/467) [`8ab8bb4`](https://github.com/nansen-ai/nansen-cli/commit/8ab8bb41a1fc89b7dfa804f5c2d601e6ae38c89b) Thanks [@kome12](https://github.com/kome12)! - `bridge execute` now re-screens the wallet against the compliance blocklist immediately before signing, and fails closed if the check can't be completed — matching what the perp commands already did. Bridge quotes stay valid for an hour and the EVM deposit leg broadcasts straight to a public RPC, so previously nothing re-checked the wallet between the quote and the transaction that moves funds.
+
+  It also refuses to execute a quote with a wallet other than the one the quote was created for. Previously the signing wallet was resolved from `--wallet` or the current default independently of the quote, so a changed default (or an explicit `--wallet`) could sign with a different wallet than the one screened.
+
+- [#467](https://github.com/nansen-ai/nansen-cli/pull/467) [`44805e2`](https://github.com/nansen-ai/nansen-cli/commit/44805e2cd0a002b38b32bd2818da89548c4974f0) Thanks [@kome12](https://github.com/kome12)! - `nansen schema` now describes the `bridge` command group — its three subcommands, their options, and the supported routes — so agents driving the CLI off the schema can discover it.
+
+  The mutating `perp` subcommands (`order`, `cancel`, `close`, `leverage`, `transfer`, `approve-builder-fee`) now declare `submitsTo: "https://api.hyperliquid.xyz/exchange"` in place of an `endpoint`, which is where they actually send a signed action, alongside an `apiEndpoints` list of the Nansen routes each one reads for compliance screening, market metadata and builder-fee status. Read-only subcommands keep their `endpoint` unchanged.
+
+- [#467](https://github.com/nansen-ai/nansen-cli/pull/467) [`7185359`](https://github.com/nansen-ai/nansen-cli/commit/7185359d3ce657df849c371b34f6d045a4dac653) Thanks [@kome12](https://github.com/kome12)! - `nansen bridge` supports `base -> hyperliquid` for deposits, and `hyperliquid -> base`, `hyperliquid -> ethereum`, `hyperliquid -> arbitrum` for withdrawals. Any other combination is rejected at quote time with the supported routes listed.
+
+  The route set is asymmetric because the two directions need different things from the client: a deposit broadcasts an EVM transaction and so needs a locally signable origin chain, while a withdrawal signs a Hyperliquid action and never touches the destination chain.
+
+- [#467](https://github.com/nansen-ai/nansen-cli/pull/467) [`19738dd`](https://github.com/nansen-ai/nansen-cli/commit/19738dd252dca12ce0e41d40fe4023ac96ff0213) Thanks [@kome12](https://github.com/kome12)! - EVM transactions are now signed as EIP-1559 (type 2) when the quote supplies fee caps, instead of being flattened into a legacy (type 0) transaction with a single gas price.
+
+  A legacy transaction pays exactly its `gasPrice`, so once the base fee rises above that value it is not merely slow — it can never be included at that nonce. A type-2 transaction pays base fee plus priority up to its cap, so it tolerates the fee moving between signing and inclusion. This affects `trade execute` and `bridge execute`, which share the signer.
+
+  `bridge execute` also stops discarding the fee fields the bridge quote provides. It previously overwrote them with a bare `eth_gasPrice` reading, producing a transaction priced at roughly the current base fee with almost no priority fee — which is what it takes to sit unmined on Base. Quoted fees are now kept, with the priority fee raised to a floor that Base will actually schedule and the cap lifted to cover both that and base-fee movement.
+
+  Two related robustness changes: signing now refuses outright when a quote carries no gas information at all, rather than falling back to a 1 wei gas price that produces a permanently unmineable transaction; and the receipt wait is longer, because by the time it runs the transaction is already broadcast, so giving up early reports a failure without undoing anything.
+
+- [#467](https://github.com/nansen-ai/nansen-cli/pull/467) [`f649eea`](https://github.com/nansen-ai/nansen-cli/commit/f649eeaf90b5666d51bc623aafdeaf4087bfe9f8) Thanks [@kome12](https://github.com/kome12)! - Add a client-side Hyperliquid action builder (`src/hl-action.js`), the groundwork for submitting perp trades straight to Hyperliquid instead of round-tripping through the Nansen backend to build them.
+
+  - msgpack encoder that reproduces the reference `msgpack.packb` output byte-for-byte (insertion-ordered maps, smallest-width ints, utf-8 strings), so an action's `connectionId` hash matches the known-good path.
+  - `actionHash` + `l1Eip712` reproduce the phantom-agent EIP-712 payload (Exchange domain, mainnet `source: "a"`) that the existing signer already knows how to sign.
+  - Order-wire assembly for market/limit orders, cancels, closes and leverage updates, including TP/SL (`normalTpsl`) grouping and the builder-code attachment.
+  - Price/size rounding (`roundPrice`/`roundSize`) ported with Python-parity banker's rounding, so over-precise values that Hyperliquid would reject are rounded identically to the server path.
+  - `approveBuilderFee` and `usdClassTransfer` user-signed payload builders.
+
+  Pinned against the live prepare endpoints with golden-vector tests that assert both the built action and its `connectionId` match byte-for-byte.
+
+- [#467](https://github.com/nansen-ai/nansen-cli/pull/467) [`3bd3909`](https://github.com/nansen-ai/nansen-cli/commit/3bd3909155d89b926ceabd506aaea44858d905f6) Thanks [@kome12](https://github.com/kome12)! - Add `src/hl-client.js`, the single direct-to-Hyperliquid submission path: `submitExchange()` POSTs a signed action straight to `api.hyperliquid.xyz/exchange` from the user's machine instead of routing it through the Nansen backend. Reads and market-data stay on the proxy.
+
+  It reproduces the backend proxy's failure handling that it replaces — throwing on a top-level `status: "err"` and on a per-action error nested in `response.data.statuses[].error` (a rejected order that Hyperliquid otherwise reports under a top-level `"ok"`) — so a rejected order can never be mistaken for a fill. The submit is deliberately not retried, since each carries a unique nonce and is not idempotent. The HL base URL is overridable via `NANSEN_HL_API_URL` (for testnet / tests).
+
+- [#467](https://github.com/nansen-ai/nansen-cli/pull/467) [`b5d6946`](https://github.com/nansen-ai/nansen-cli/commit/b5d6946b0380b30d5dc1a4bcc33dcbc18ad0f8ad) Thanks [@kome12](https://github.com/kome12)! - Harden perp, swap, and bridge command safety:
+
+  - `perp order`/`close` now reject an invalid `--side` instead of silently opening the opposite direction, and `perp leverage` rejects an invalid `--margin-type` instead of silently switching to isolated.
+  - Perp numeric args (`--size`, `--price`, `--leverage`, `--oid`) are validated as positive numbers, with specific error messages instead of a generic usage banner.
+  - Perp commands now require an EVM wallet, with a clear error instead of querying for an `"undefined"` address.
+  - `trade quote` validates `--quote-index`, `--slippage`, and `--max-auto-slippage`, rejecting out-of-range values (e.g. a percent-vs-decimal slippage mix-up).
+  - `bridge quote` now validates `--slippage` client-side (whole basis points in `[0, 10000]`), rejecting non-numeric or out-of-range values with a clear message instead of forwarding them to an opaque backend 422 (matching how `perp` validates `--slippage`).
+  - `perp order`/`close` warn before signing when `--size` (or `--price` for `order`) is finer than the asset's Hyperliquid precision, which the exchange silently rounds.
+  - `perp order`/`close` now report the size and price the order actually executes at (post-rounding, slippage-adjusted for market orders) instead of echoing the raw input, so the printed values match the fill.
+  - `limit-order list` no longer aborts the whole render when one order has a non-integer amount.
+  - Quote loaders reject a cross-type quote (a bridge quote sent to `trade execute`, or a swap quote sent to `bridge execute`).
+  - `bridge execute` now refuses a quote that has already been executed, preventing an accidental double-bridge on retry.
+  - `bridge quote` accepts human amounts via `--amount-unit token|usd` (default stays base units), resolving token decimals per chain so the same `5` isn't 100x off between chains (USDC is 6 decimals on EVM, 8 on Hyperliquid). Hyperliquid USDC is floored to the bridge's 6-decimal precision to avoid a round-up-past-balance rejection.
+  - `perp meta` supports `--all` and `--filter <text>` so assets past the first 20 (e.g. HYPE) are listable.
+  - Deprecated top-level aliases now print a deprecation notice on stderr when run, not only in `--help`.
+  - `limit-order` rejects a zero-duration or past expiry instead of creating an order that expires immediately.
+  - A password with leading/trailing whitespace is no longer mangled when read back from the OS keychain.
+  - Nested backend error messages containing an apostrophe are no longer truncated.
+
+- [#467](https://github.com/nansen-ai/nansen-cli/pull/467) [`b577954`](https://github.com/nansen-ai/nansen-cli/commit/b5779543c5a5bb714a3428bb80e3d8f5e3eb865e) Thanks [@kome12](https://github.com/kome12)! - `perp` and `bridge` no longer serve any API response from the `--cache` store, and `bridge execute` no longer retries its submission.
+
+  - **Compliance screening** is always a live check. Every mutating command re-screens the signing wallet immediately before signing; with `--cache` that verdict could previously come from a cache written up to five minutes earlier, which is exactly the window the check exists to close.
+  - **`bridge execute`** sets `retry: false`. It proxies to Relay's `/authorize` and Hyperliquid's `/exchange`, neither of which is idempotent, so an automatic re-send on a 500 or 502 could submit the same signed action twice.
+  - **Bridge status polling** now observes progress under `--cache`. The cache key is endpoint plus body, so every poll for a given request id hit the same key and the loop would re-read one stale verdict for the whole TTL.
+  - **Perp reads** (`positions`, `orders`, `account`, `meta`) and **bridge quotes** bypass the cache too: they either report live balances to the user or feed a signing decision — `close` sizes its order from the positions read, and asset ids come from `meta`.
+
+  `bridge execute` also refuses to sign a step whose EIP-712 type definition is missing or whose `primaryType` matches no entry in it. With an empty field list the digest is still well-formed but commits to none of the action's contents, so it would have produced a valid-looking signature over nothing.
+
+- [#467](https://github.com/nansen-ai/nansen-cli/pull/467) [`4c1d3aa`](https://github.com/nansen-ai/nansen-cli/commit/4c1d3aa16874b2d994ba0e57f52131fdc2dd0748) Thanks [@kome12](https://github.com/kome12)! - Close three residual safety gaps on the perp/bridge signing paths:
+
+  - `perp order` now rejects a take-profit or stop-loss price that rounds to zero at the asset's precision, instead of encoding a `triggerPx` of `0` and resting a dead protective order while the parent position opens unprotected. This extends the existing zero-price/size guard (which only covered the parent leg) to the TP/SL trigger legs.
+  - The Privy bridge signing path now refuses to sign an EIP-712 action whose primary type has no field definitions, matching the guard the local signing path already had. An empty type list produces a valid-looking signature that commits to none of the action's contents.
+  - The EVM bridge deposit leg resolves its nonce from the signing wallet's own address rather than the server-returned `txData.from`. The transaction is signed with the local key regardless of `from`, so the nonce must come from that account — and this stays correct even if a quote omits `from`.
+
+## 1.35.0
+
+### Minor Changes
+
+- [#469](https://github.com/nansen-ai/nansen-cli/pull/469) [`85b1934`](https://github.com/nansen-ai/nansen-cli/commit/85b1934ae25ed02d1726de8ebe92ea41a98f4454) Thanks [@gulshngill](https://github.com/gulshngill)! - Surface the API's credit and rate-limit response headers.
+
+  Failed calls now report quota state in their error details: an out-of-credits error carries your actual remaining balance, and a rate-limited error carries the limit, what is left, and how long the window needs to drain. Previously the only credit figure the CLI could show was the static per-endpoint estimate published in the API reference — a quote, not what you were charged.
+
+  A warning goes to stderr when your balance will not cover another call of the size just made, so it never interferes with the JSON on stdout.
+
+  Successful responses carry the same numbers under an exported `RESPONSE_META` symbol, and the client exposes `lastResponseMeta`. Both are additive: the JSON each command prints is unchanged.
+
+- [#470](https://github.com/nansen-ai/nansen-cli/pull/470) [`8159300`](https://github.com/nansen-ai/nansen-cli/commit/81593008f829cc83f1d4a6ee9e5c1a10237a9553) Thanks [@gulshngill](https://github.com/gulshngill)! - Surface the API's request id.
+
+  Failed calls now carry `details.requestId` — the value that identifies the call end to end. Quote it when reporting a problem; previously nothing identifying a failed request ever reached the user, which made server errors effectively unreportable. Successful responses expose it alongside the credit and rate-limit figures under the `RESPONSE_META` symbol.
+
+  Absent on deployments that do not send the header yet, in which case the field is simply omitted.
+
 ## 1.34.0
 
 ### Minor Changes

package/README.md

@@ -93,6 +93,38 @@ nansen trade limit-order update --order <orderId> --trigger-price 85
 
 For EVM chains, there's no native limit-order surface — pair an external venue's resting order with a `common-token-transfer` smart alert on the settlement wallet as a best-effort fill signal. See the `nansen-limit-orders` skill for details.
 
+## Perpetuals
+
+Hyperliquid perpetual trading via `nansen perp`. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as DEX trading (requires an EVM wallet). Select the asset with `--coin` (`--symbol` is accepted as an alias).
+
+```bash
+nansen perp meta --filter ETH                                  # list assets + max leverage
+nansen perp order --coin ETH --side buy --size 0.1 --price 1600 --type limit
+nansen perp order --coin BTC --side sell --size 0.001 --price 95000 --type market \
+  --take-profit 90000 --stop-loss 98000
+nansen perp close --coin ETH --size 0.1 --price 1600 --side sell   # sell closes a long
+nansen perp cancel --coin ETH --oid <orderId>
+nansen perp leverage --coin ETH --leverage 5 --margin-type cross   # or isolated
+nansen perp transfer --direction spot-to-perp --amount 25          # Spot<->Perps (or perp-to-spot)
+nansen perp positions
+nansen perp account                                            # value, unrealized PnL, margin, spot USDC
+```
+
+`--side` is `buy`/`long` or `sell`/`short` to open (`buy`/`sell` to close); `--tif` is `Gtc`/`Ioc`/`Alo`; `--slippage` is a decimal in `[0,1]`; `--leverage` is a whole integer capped at the asset max. Perp orders are irreversible once signed. USDC sent to a wallet via Hyperliquid's **Send** lands in the **Spot** balance (shown as `Spot USDC`); move it to Perps with `perp transfer` before trading. See the `nansen-trading` skill for details.
+
+## Bridge
+
+Move USDC between EVM chains and Hyperliquid via `nansen bridge`. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as perps and DEX trading. Quotes are written to a local file and executed by id; execution signs and broadcasts.
+
+```bash
+nansen bridge quote --from-chain base --to-chain hyperliquid --from-token USDC --amount 1000000
+nansen bridge execute --quote <quoteId>
+nansen bridge execute --quote <quoteId> --nonce 20 --priority-fee 5   # replace a stuck EVM deposit
+nansen bridge status --request-id <id>
+```
+
+Supported routes: `base → hyperliquid` (deposit), and `hyperliquid → base`/`ethereum`/`arbitrum` (withdraw). Deposits broadcast an EVM transaction locally, so only Base is offered on the deposit side; run `nansen bridge help` for the current list. `--amount` is a base-unit integer by default; pass `--amount-unit token` for a human amount. `--recipient` defaults to the wallet's own EVM address. `--priority-fee`/`--max-fee` (gwei) and `--nonce` apply only to EVM deposit legs and let a stuck transaction be replaced. Bridge transfers are irreversible once signed.
+
 ## Wallet
 
 ```bash
@@ -177,17 +209,28 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
 
 ```json
 { "success": true,  "data": <api_response> }
-{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401 }
+{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "details": { ... } }
 ```
 
 **Critical error codes:**
 
 | Code | Action |
 |------|--------|
-| `CREDITS_EXHAUSTED` | Stop all API calls immediately. Check [app.nansen.ai](https://app.nansen.ai). |
+| `CREDITS_EXHAUSTED` | Stop all API calls immediately. `details.credits.remaining` is your actual balance. Top up at [app.nansen.ai/api](https://app.nansen.ai/api). |
 | `UNAUTHORIZED` | Wrong or missing key. Re-auth. |
-| `RATE_LIMITED` | Auto-retried by CLI. |
+| `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
 | `UNSUPPORTED_FILTER` | Remove the filter and retry. |
+| `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
+
+**Error metadata.** When the API reports them, `details` carries:
+
+| Field | Meaning |
+|-------|---------|
+| `requestId` | Identifies this call end to end. Quote it in any support report. Opaque — do not parse it. |
+| `credits` | `used`, `remaining` |
+| `rateLimit` | `limit`, `remaining`, `resetSeconds` |
+
+Any field may be absent or `null`, meaning unknown — never assume zero. A low-balance warning goes to **stderr**, so stdout stays pure JSON.
 
 ## Troubleshooting
 
@@ -195,7 +238,8 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
 |---------|-----|
 | `command not found` | `npm install -g nansen-cli` |
 | `UNAUTHORIZED` after login | `cat ~/.nansen/config.json` or set `NANSEN_API_KEY` |
-| Empty perp results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
+| Empty perp _research_ results | Use `--symbol BTC`, not `--token`. Perps are Hyperliquid-only. |
+| `perp` _trading_ prints the usage banner | Trading needs `--coin BTC` (`--symbol` also works); see the Perpetuals section. |
 | `UNSUPPORTED_FILTER` on token holders | Remove `--smart-money` — not all tokens have that data. |
 | Huge JSON response | Use `--fields` to select columns. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",

package/scripts/postinstall.js

@@ -41,9 +41,19 @@ function hasTTY() {
   return process.stdin.isTTY && process.stderr.isTTY;
 }
 
+// npx is a .cmd shim on Windows, and Node refuses to spawn .cmd/.bat without a
+// shell (CVE-2024-27980). Go through cmd.exe explicitly rather than enabling
+// `shell: true`, which would hand the whole command line to the shell parser.
+const IS_WIN = process.platform === "win32";
+
+function npxInvocation(args) {
+  return IS_WIN ? ["cmd.exe", ["/c", "npx", ...args]] : ["npx", args];
+}
+
 function hasNpx() {
   try {
-    execFileSync("npx", ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
+    const [cmd, cmdArgs] = npxInvocation(["--version"]);
+    execFileSync(cmd, cmdArgs, { stdio: "ignore", shell: false });
     return true;
   } catch {
     return false;
@@ -86,7 +96,7 @@ function prompt(question) {
 
 function runCommand(cmd, args) {
   return new Promise((resolve) => {
-    const child = spawn(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
+    const child = spawn(cmd, args, { stdio: "inherit", shell: false });
     child.on("close", (code) => resolve(code === 0));
     child.on("error", () => resolve(false));
   });
@@ -113,7 +123,7 @@ async function installSkill() {
   }
 
   log(`Installing Nansen skill...`);
-  const ok = await runCommand("npx", ["-y", "skills", "add", SKILL_REPO]);
+  const ok = await runCommand(...npxInvocation(["-y", "skills", "add", SKILL_REPO]));
   if (!ok) {
     log(`${YELLOW}Skill installation failed. You can retry with: npx skills add ${SKILL_REPO}${RESET}`);
   }

package/skills/nansen-trading/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nansen-trading
-description: Execute DEX swaps on Solana or Base, including cross-chain bridges. Use when buying or selling a token, getting a swap quote, or executing a trade.
+description: Execute DEX swaps on Solana or Base (including cross-chain bridges) and Hyperliquid perpetual trades. Use when buying or selling a token, getting a swap quote, executing a trade, or opening/closing/managing a perp position.
 metadata:
   openclaw:
     requires:
@@ -191,6 +191,54 @@ If the user says "$20 worth of X", use `--amount-unit usd` directly — no manua
 - A wallet is required even for quotes (the API builds sender-specific transactions).
 - ERC-20 swaps may require an approval step — execute handles this automatically.
 
+# Perp Trading
+
+Use `nansen perp` for Hyperliquid perpetual trading. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as DEX trading; requires an **EVM** wallet. **Perp orders are irreversible once signed.**
+
+Subcommands: `order`, `cancel`, `close`, `leverage`, `positions`, `orders`, `account`, `meta`.
+
+The asset is selected with `--coin` (e.g. `BTC`, `ETH`); `--symbol` is accepted as an alias. List tradable assets and their max leverage with `nansen perp meta` (use `--filter <text>` or `--all` to see beyond the first 20).
+
+## Open a position
+
+```bash
+# Limit long: 0.1 ETH at $1600
+nansen perp order --coin ETH --side buy --size 0.1 --price 1600 --type limit
+
+# Market short with optional take-profit / stop-loss
+nansen perp order --coin BTC --side sell --size 0.001 --price 95000 --type market \
+  --take-profit 90000 --stop-loss 98000
+```
+
+- `--side`: `buy`/`long` to open a long, `sell`/`short` to open a short.
+- `--size`: position size in base asset units (positive number).
+- `--price`: limit price (or mark price for market orders).
+- `--type`: `limit` (default) or `market`. `--tif`: `Gtc` (default), `Ioc`, `Alo`.
+- `--slippage`: decimal in `[0,1]` for market orders (default `0.03` = 3%).
+
+## Close / cancel
+
+```bash
+# Close: sell to close a long, buy to close a short (validated against your open position)
+nansen perp close --coin ETH --size 0.1 --price 1600 --side sell
+
+# Cancel a resting order by id
+nansen perp cancel --coin ETH --oid 123456
+```
+
+## Leverage, transfers & account
+
+```bash
+nansen perp leverage --coin ETH --leverage 5 --margin-type cross   # or isolated
+nansen perp transfer --direction spot-to-perp --amount 25          # or perp-to-spot
+nansen perp positions
+nansen perp account     # account value, unrealized PnL, margin used, withdrawable, spot USDC
+```
+
+`--leverage` must be a whole integer and is capped at the asset's maximum (see `perp meta`).
+
+**Spot vs Perps:** perp trading draws from the **Perps** balance, but USDC sent to a wallet via Hyperliquid's **Send** lands in **Spot** (and shows as `Spot USDC` in `perp account`). Move it across with `perp transfer --direction spot-to-perp --amount <usdc>` before trading. (Deposits via the bridge land in Perps directly.)
+
 ## Source
 
 - npm: https://www.npmjs.com/package/nansen-cli

package/src/api.js

@@ -8,6 +8,16 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { EVM_CHAINS } from './chain-ids.js';
 import { getAnonymousId, TELEMETRY_DISABLED } from './telemetry.js';
+import { readResponseMeta } from './response-meta.js';
+
+/**
+ * Key for the credit/rate-limit metadata attached to a successful response.
+ *
+ * A symbol on purpose: JSON.stringify and Object.keys both skip it, so the JSON
+ * every command prints is byte-for-byte unchanged while callers that want the
+ * numbers can still read them off the returned object.
+ */
+export const RESPONSE_META = Symbol('nansenResponseMeta');
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -465,6 +475,15 @@ export class NansenAPI {
       ttl: options.cache?.ttl ?? DEFAULT_CACHE_TTL
     };
     this.defaultHeaders = options.defaultHeaders || {};
+    /**
+     * Credit/rate-limit metadata from the most recent response, or null.
+     *
+     * Survives any reshaping a command handler does to the response body, which
+     * the RESPONSE_META symbol on the returned object does not. Last write wins
+     * when a handler makes several calls — the freshest balance, which is what a
+     * low-credit warning wants.
+     */
+    this.lastResponseMeta = null;
   }
 
   static cleanBody(body) {
@@ -520,7 +539,11 @@ export class NansenAPI {
         }
       } catch { /* balance check is best-effort */ }
     }
-    return await paidResponse.json();
+    const data = await paidResponse.json();
+    const meta = readResponseMeta(paidResponse);
+    this.lastResponseMeta = meta;
+    if (meta && data !== null && typeof data === 'object') data[RESPONSE_META] = meta;
+    return data;
   }
 
   async request(endpoint, body = {}, options = {}) {
@@ -581,11 +604,17 @@ export class NansenAPI {
         data = await response.json();
       } catch (_err) {
         // Non-JSON response (rare, usually server errors)
+        const meta = readResponseMeta(response);
+        this.lastResponseMeta = meta;
         const error = new NansenError(
           `Invalid response from API (status ${response.status})`,
           response.status >= 500 ? ErrorCode.SERVER_ERROR : ErrorCode.UNKNOWN,
           response.status,
-          { body: await response.text().catch(() => null), attempt: attempt + 1 }
+          {
+            body: await response.text().catch(() => null),
+            attempt: attempt + 1,
+            ...(meta?.requestId && { requestId: meta.requestId })
+          }
         );
         
         if (shouldRetry && attempt < maxRetries && response.status >= 500) {
@@ -603,7 +632,9 @@ export class NansenAPI {
           || `API error: ${response.status}`;
         // nansen-api proxy stringifies nested error dicts via Python str(), producing
         // "{'message': 'actual error', ...}". Extract the inner message if present.
-        const nestedMatch = typeof message === 'string' && message.match(/['"]message['"]\s*:\s*['"](.*?)['"]/);
+        // Require the closing quote to be followed by a comma or closing brace so
+        // an apostrophe inside the message (e.g. "can't") doesn't truncate it.
+        const nestedMatch = typeof message === 'string' && message.match(/['"]message['"]\s*:\s*['"](.*?)['"]\s*[,}]/s);
         if (nestedMatch) message = nestedMatch[1];
         const code = statusToErrorCode(response.status, data);
         const retryAfterMs = parseRetryAfter(response.headers.get('retry-after'));
@@ -702,10 +733,23 @@ export class NansenAPI {
           }
         }
 
+        // Quota state and the request id belong on the error above all: an
+        // out-of-credits or rate-limited failure is exactly when the caller
+        // needs the numbers, and a 5xx is worthless to support without the id.
+        // formatError() surfaces details, so this needs no plumbing.
+        //
+        // On a retried call this is the LAST attempt's id — each attempt gets
+        // its own server-side id, and the last one is the failure worth
+        // reporting.
+        const meta = readResponseMeta(response);
+        this.lastResponseMeta = meta;
         lastError = new NansenError(message, code, response.status, {
           ...data,
           attempt: attempt + 1,
-          retryAfterMs
+          retryAfterMs,
+          ...(meta?.requestId && { requestId: meta.requestId }),
+          ...(meta?.credits && { credits: meta.credits }),
+          ...(meta?.rateLimit && { rateLimit: meta.rateLimit })
         });
         
         // Retry on specific status codes
@@ -722,12 +766,21 @@ export class NansenAPI {
       if (attempt > 0) {
         data._meta = { ...(data._meta || {}), retriedAttempts: attempt };
       }
-      
+
       // Cache successful response
       if (useCache) {
         setCachedResponse(endpoint, body, data);
       }
-      
+
+      // Attach after caching so the cache stores the payload alone — quota
+      // numbers are per-response and would be stale on a cache hit.
+      // Guarded: a response body can be a primitive, which cannot take a property.
+      const meta = readResponseMeta(response);
+      this.lastResponseMeta = meta;
+      if (meta) {
+        if (data !== null && typeof data === 'object') data[RESPONSE_META] = meta;
+      }
+
       return data;
     }