nansen-cli 1.44.2 → 1.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/schema.json CHANGED
@@ -410,7 +410,7 @@
410
410
  }
411
411
  },
412
412
  "research": {
413
- "description": "Research and analytics commands",
413
+ "description": "Research and analytics commands. Explicitly blank chain, timeframe, and days options are rejected instead of selecting defaults. Profiler batch rejects blank --delay; trace rejects blank --delay, --depth, and --width.",
414
414
  "subcommands": {
415
415
  "portfolio": {
416
416
  "subcommands": {
@@ -481,7 +481,8 @@
481
481
  "description": "Chain to query"
482
482
  },
483
483
  "days": {
484
- "type": "number",
484
+ "type": "integer",
485
+ "minimum": 0,
485
486
  "default": 30,
486
487
  "description": "Lookback window in days"
487
488
  }
@@ -507,7 +508,8 @@
507
508
  "description": "Chain to profile the address on"
508
509
  },
509
510
  "days": {
510
- "type": "number",
511
+ "type": "integer",
512
+ "minimum": 0,
511
513
  "default": 30,
512
514
  "description": "Lookback window in days"
513
515
  }
@@ -528,7 +530,8 @@
528
530
  "description": "Chain to profile the address on"
529
531
  },
530
532
  "days": {
531
- "type": "number",
533
+ "type": "integer",
534
+ "minimum": 0,
532
535
  "default": 30,
533
536
  "description": "Lookback window in days"
534
537
  }
@@ -565,12 +568,38 @@
565
568
  "description": "Chain to profile the address on"
566
569
  },
567
570
  "days": {
568
- "type": "number",
571
+ "type": "integer",
572
+ "minimum": 0,
569
573
  "default": 30,
570
574
  "description": "Lookback window in days"
571
575
  }
572
576
  }
573
577
  },
578
+ "counterparties-batch": {
579
+ "endpoint": "/api/v1/profiler/address/counterparties/batch",
580
+ "description": "Top counterparties by volume for up to 10 wallets in one request. Results are not aggregated: every row carries the wallet_address it belongs to, returned as contiguous per-wallet blocks ordered by wallet address — raise --limit and page with --page N to reach later wallets",
581
+ "options": {
582
+ "addresses": {
583
+ "type": "string",
584
+ "description": "Comma-separated list (or JSON array) of up to 10 distinct wallet addresses; required unless --file <path> is provided"
585
+ },
586
+ "file": {
587
+ "type": "string",
588
+ "description": "Read addresses from this file instead of --addresses: a JSON array of addresses, or one address per line"
589
+ },
590
+ "chain": {
591
+ "type": "string",
592
+ "default": "all",
593
+ "description": "Chain to profile every address on: all, arbitrum, arc, avalanche, base, bitcoin, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, robinhood, sei, solana, sonic, starknet, sui, ton, tron ('bsc' is accepted and sent as 'bnb'). One ecosystem per request: EVM and Solana addresses cannot be mixed. The default 'all' auto-detects the ecosystem across EVM chains, or Solana for a Solana-only batch"
594
+ },
595
+ "days": {
596
+ "type": "integer",
597
+ "minimum": 0,
598
+ "default": 30,
599
+ "description": "Lookback window in days (max 90 for this command)"
600
+ }
601
+ }
602
+ },
574
603
  "historical-balances": {
575
604
  "endpoint": "/api/v1/profiler/address/historical-balances",
576
605
  "description": "Historical balances over time",
@@ -586,7 +615,8 @@
586
615
  "description": "Chain to profile the address on"
587
616
  },
588
617
  "days": {
589
- "type": "number",
618
+ "type": "integer",
619
+ "minimum": 0,
590
620
  "default": 30,
591
621
  "description": "Lookback window in days"
592
622
  }
@@ -634,7 +664,8 @@
634
664
  "description": "Chain to profile the address on"
635
665
  },
636
666
  "days": {
637
- "type": "number",
667
+ "type": "integer",
668
+ "minimum": 0,
638
669
  "default": 30,
639
670
  "description": "Lookback window in days"
640
671
  }
@@ -677,7 +708,8 @@
677
708
  "description": "Hyperliquid trader address"
678
709
  },
679
710
  "days": {
680
- "type": "number",
711
+ "type": "integer",
712
+ "minimum": 0,
681
713
  "default": 30,
682
714
  "description": "Lookback window in days"
683
715
  }
@@ -698,7 +730,8 @@
698
730
  "description": "Chain to profile the address on"
699
731
  },
700
732
  "days": {
701
- "type": "number",
733
+ "type": "integer",
734
+ "minimum": 0,
702
735
  "default": 30,
703
736
  "description": "Lookback window in days"
704
737
  }
@@ -749,17 +782,19 @@
749
782
  "description": "Chain to profile the address on"
750
783
  },
751
784
  "depth": {
752
- "type": "number",
785
+ "type": "integer",
753
786
  "default": 2,
754
- "description": "Hops to follow from the starting address (1-5)"
787
+ "description": "Hops to follow from the starting address (1-5); valid integers outside the range are clamped"
755
788
  },
756
789
  "width": {
757
- "type": "number",
790
+ "type": "integer",
791
+ "minimum": 0,
758
792
  "default": 10,
759
793
  "description": "Counterparties to follow at each hop"
760
794
  },
761
795
  "days": {
762
- "type": "number",
796
+ "type": "integer",
797
+ "minimum": 0,
763
798
  "default": 30,
764
799
  "description": "Lookback window in days at each hop"
765
800
  },
@@ -784,7 +819,8 @@
784
819
  "description": "Chain to compare the wallets on"
785
820
  },
786
821
  "days": {
787
- "type": "number",
822
+ "type": "integer",
823
+ "minimum": 0,
788
824
  "default": 30,
789
825
  "description": "Lookback window in days"
790
826
  }
@@ -810,7 +846,8 @@
810
846
  "description": "Token contract address (mint address on Solana)"
811
847
  },
812
848
  "days": {
813
- "type": "number",
849
+ "type": "integer",
850
+ "minimum": 0,
814
851
  "default": 30,
815
852
  "description": "Lookback window in days"
816
853
  },
@@ -829,7 +866,7 @@
829
866
  },
830
867
  "who-bought-sold": {
831
868
  "endpoint": "/api/v1/tgm/who-bought-sold",
832
- "description": "Recent buyers and sellers",
869
+ "description": "Recent buyers and sellers. Explicitly blank --buy-or-sell values are rejected; omission keeps BUY.",
833
870
  "options": {
834
871
  "chain": {
835
872
  "type": "string",
@@ -842,7 +879,8 @@
842
879
  "description": "Token contract address (mint address on Solana)"
843
880
  },
844
881
  "days": {
845
- "type": "number",
882
+ "type": "integer",
883
+ "minimum": 0,
846
884
  "default": 30,
847
885
  "description": "Lookback window in days"
848
886
  },
@@ -871,7 +909,8 @@
871
909
  "description": "Token contract address (mint address on Solana)"
872
910
  },
873
911
  "days": {
874
- "type": "number",
912
+ "type": "integer",
913
+ "minimum": 0,
875
914
  "default": 30,
876
915
  "description": "Lookback window in days"
877
916
  }
@@ -892,7 +931,8 @@
892
931
  "description": "Token contract address (mint address on Solana)"
893
932
  },
894
933
  "days": {
895
- "type": "number",
934
+ "type": "integer",
935
+ "minimum": 0,
896
936
  "default": 30,
897
937
  "description": "Lookback window in days"
898
938
  }
@@ -933,7 +973,8 @@
933
973
  "description": "Token contract address (mint address on Solana)"
934
974
  },
935
975
  "days": {
936
- "type": "number",
976
+ "type": "integer",
977
+ "minimum": 0,
937
978
  "default": 30,
938
979
  "description": "Lookback window in days"
939
980
  },
@@ -953,7 +994,8 @@
953
994
  "description": "Perp symbol, e.g. BTC"
954
995
  },
955
996
  "days": {
956
- "type": "number",
997
+ "type": "integer",
998
+ "minimum": 0,
957
999
  "default": 30,
958
1000
  "description": "Lookback window in days"
959
1001
  },
@@ -984,7 +1026,8 @@
984
1026
  "description": "Perp symbol, e.g. BTC"
985
1027
  },
986
1028
  "days": {
987
- "type": "number",
1029
+ "type": "integer",
1030
+ "minimum": 0,
988
1031
  "default": 30,
989
1032
  "description": "Lookback window in days"
990
1033
  }
@@ -1151,7 +1194,8 @@
1151
1194
  "description": "Screen perpetual futures contracts",
1152
1195
  "options": {
1153
1196
  "days": {
1154
- "type": "number",
1197
+ "type": "integer",
1198
+ "minimum": 0,
1155
1199
  "default": 30,
1156
1200
  "description": "Lookback window in days"
1157
1201
  },
@@ -1181,7 +1225,8 @@
1181
1225
  "description": "Perpetual futures PnL leaderboard",
1182
1226
  "options": {
1183
1227
  "days": {
1184
- "type": "number",
1228
+ "type": "integer",
1229
+ "minimum": 0,
1185
1230
  "default": 30,
1186
1231
  "description": "Lookback window in days"
1187
1232
  },
@@ -1440,7 +1485,7 @@
1440
1485
  "description": "Nansen Points analytics",
1441
1486
  "subcommands": {
1442
1487
  "leaderboard": {
1443
- "description": "Points leaderboard"
1488
+ "description": "Points leaderboard (unavailable)"
1444
1489
  }
1445
1490
  }
1446
1491
  },
@@ -1834,6 +1879,7 @@
1834
1879
  "description": "Smart alert management — create, update, toggle, delete alerts",
1835
1880
  "subcommands": {
1836
1881
  "list": {
1882
+ "endpoint": "/api/v1/smart-alert/list",
1837
1883
  "description": "List all alerts",
1838
1884
  "returns": [
1839
1885
  "id",
@@ -1847,7 +1893,9 @@
1847
1893
  ]
1848
1894
  },
1849
1895
  "create": {
1896
+ "endpoint": "/api/v1/smart-alert",
1850
1897
  "description": "Create a new alert",
1898
+ "notes": "Sent as POST /api/v1/smart-alert. alerts update PATCHes the same path; the schema declares routes by path only, so the two subcommands intentionally share one endpoint entry and one credit cost.",
1851
1899
  "options": {
1852
1900
  "name": {
1853
1901
  "type": "string",
@@ -1898,7 +1946,9 @@
1898
1946
  }
1899
1947
  },
1900
1948
  "update": {
1949
+ "endpoint": "/api/v1/smart-alert",
1901
1950
  "description": "Update an existing alert. Usage: nansen alerts update <id> [options]",
1951
+ "notes": "Sent as PATCH /api/v1/smart-alert. alerts create POSTs the same path; the schema declares routes by path only, so the two subcommands intentionally share one endpoint entry and one credit cost.",
1902
1952
  "options": {
1903
1953
  "name": {
1904
1954
  "type": "string",
@@ -1951,6 +2001,7 @@
1951
2001
  }
1952
2002
  },
1953
2003
  "toggle": {
2004
+ "endpoint": "/api/v1/smart-alert/toggle",
1954
2005
  "description": "Enable or disable an alert. Usage: nansen alerts toggle <id> --enabled|--disabled",
1955
2006
  "options": {
1956
2007
  "enabled": {
@@ -1964,6 +2015,7 @@
1964
2015
  }
1965
2016
  },
1966
2017
  "delete": {
2018
+ "endpoint": "/api/v1/smart-alert/{alertId}",
1967
2019
  "description": "Delete an alert. Usage: nansen alerts delete <id>",
1968
2020
  "options": {}
1969
2021
  }
@@ -1973,7 +2025,7 @@
1973
2025
  "description": "DEX trading commands",
1974
2026
  "subcommands": {
1975
2027
  "quote": {
1976
- "description": "Get a DEX swap quote (same-chain or cross-chain)",
2028
+ "description": "Get a DEX swap quote (same-chain or cross-chain). Explicitly blank --swap-mode, --wallet, --to-chain, --aggregator, and --amount-unit values are rejected.",
1977
2029
  "options": {
1978
2030
  "chain": {
1979
2031
  "type": "string",
@@ -2043,7 +2095,7 @@
2043
2095
  ]
2044
2096
  },
2045
2097
  "execute": {
2046
- "description": "Sign and broadcast a quoted trade",
2098
+ "description": "Sign and broadcast a quoted trade. Explicitly blank --wallet values are rejected.",
2047
2099
  "options": {
2048
2100
  "quote": {
2049
2101
  "type": "string",
@@ -2109,7 +2161,7 @@
2109
2161
  "description": "Limit order management (Solana only)",
2110
2162
  "subcommands": {
2111
2163
  "create": {
2112
- "description": "Place a new limit order",
2164
+ "description": "Place a new limit order. Explicitly blank --expires values are rejected; omission keeps the 30d default. Explicitly blank --wallet values are rejected.",
2113
2165
  "options": {
2114
2166
  "from": {
2115
2167
  "type": "string",
@@ -2163,7 +2215,7 @@
2163
2215
  ]
2164
2216
  },
2165
2217
  "list": {
2166
- "description": "List your limit orders",
2218
+ "description": "List your limit orders. Explicitly blank --wallet, --limit, --offset, --dir, and --mint values are rejected.",
2167
2219
  "options": {
2168
2220
  "state": {
2169
2221
  "type": "string",
@@ -2202,7 +2254,7 @@
2202
2254
  ]
2203
2255
  },
2204
2256
  "cancel": {
2205
- "description": "Cancel an open limit order",
2257
+ "description": "Cancel an open limit order. Explicitly blank --wallet values are rejected.",
2206
2258
  "options": {
2207
2259
  "order": {
2208
2260
  "type": "string",
@@ -2219,7 +2271,7 @@
2219
2271
  ]
2220
2272
  },
2221
2273
  "update": {
2222
- "description": "Update trigger price or slippage on an existing order",
2274
+ "description": "Update trigger price or slippage on an existing order. Explicitly blank --wallet values are rejected.",
2223
2275
  "options": {
2224
2276
  "order": {
2225
2277
  "type": "string",
@@ -2251,7 +2303,13 @@
2251
2303
  "description": "Wallet management. x402 auto-payments are guarded by a client-side policy: per-payment USD cap via NANSEN_X402_MAX_AMOUNT (default 1.00; 'unlimited' to disable) and an optional recipient allowlist via NANSEN_X402_ALLOWED_PAYTO (comma-separated addresses).",
2252
2304
  "subcommands": {
2253
2305
  "create": {
2254
- "description": "Create a new wallet"
2306
+ "description": "Create a new wallet. Explicitly blank --name values are rejected for local and Privy wallets.",
2307
+ "options": {
2308
+ "unsafe-no-password": {
2309
+ "type": "boolean",
2310
+ "description": "Skip encryption; private keys are stored unencrypted on disk (local only)"
2311
+ }
2312
+ }
2255
2313
  },
2256
2314
  "list": {
2257
2315
  "description": "List all wallets"
@@ -2265,7 +2323,7 @@
2265
2323
  }
2266
2324
  },
2267
2325
  "send": {
2268
- "description": "Send tokens or native currency",
2326
+ "description": "Send tokens or native currency. Explicitly blank --token and --wallet values are rejected; omit them for native currency and the default wallet.",
2269
2327
  "options": {
2270
2328
  "to": {
2271
2329
  "type": "string",
@@ -2280,8 +2338,11 @@
2280
2338
  },
2281
2339
  "amount": {
2282
2340
  "type": "string",
2283
- "required": true,
2284
- "description": "Amount to send in human-readable units, e.g. 1.5"
2341
+ "description": "Amount to send in human-readable units, e.g. 1.5. Required unless --max is set"
2342
+ },
2343
+ "max": {
2344
+ "type": "boolean",
2345
+ "description": "Send the entire spendable balance instead of --amount"
2285
2346
  }
2286
2347
  }
2287
2348
  },
@@ -2297,6 +2358,7 @@
2297
2358
  }
2298
2359
  },
2299
2360
  "account": {
2361
+ "endpoint": "/api/v1/account",
2300
2362
  "description": "Show API key status, plan, and remaining credits. Does not consume credits."
2301
2363
  },
2302
2364
  "auth": {
@@ -2353,6 +2415,7 @@
2353
2415
  "description": "Web search and fetch commands",
2354
2416
  "subcommands": {
2355
2417
  "search": {
2418
+ "endpoint": "/api/v1/search/web-search",
2356
2419
  "description": "Search the web for one or more queries in parallel",
2357
2420
  "options": {
2358
2421
  "query": {
@@ -2371,6 +2434,7 @@
2371
2434
  ]
2372
2435
  },
2373
2436
  "fetch": {
2437
+ "endpoint": "/api/v1/search/web-fetch",
2374
2438
  "description": "Fetch and analyze content from one or more URLs using AI",
2375
2439
  "options": {
2376
2440
  "url": {
@@ -2390,6 +2454,10 @@
2390
2454
  }
2391
2455
  },
2392
2456
  "agent": {
2457
+ "apiEndpoints": [
2458
+ "/api/v1/agent/fast",
2459
+ "/api/v1/agent/expert"
2460
+ ],
2393
2461
  "description": "Nansen AI research agent — ask questions about wallets, tokens, and on-chain activity",
2394
2462
  "options": {
2395
2463
  "expert": {
@@ -174,6 +174,14 @@ const NATIVE_TOKEN_ADDRESSES = {
174
174
  // legitimately needs more.
175
175
  export const EVM_BRIDGE_NATIVE_FEE_SLACK = 2_000_000_000_000_000n; // 0.002 ETH
176
176
 
177
+ // Tolerance for a native-ETH refund on an exact-in bridge: some routers receive
178
+ // msg.value = request.amount and return a small unused remainder, so the sim's net
179
+ // outflow can be slightly below the requested input on a correctly funded bridge.
180
+ // Same numeric cap as EVM_BRIDGE_NATIVE_FEE_SLACK (conservative, gas-independent);
181
+ // kept separate so sibling-fee and input-refund tolerances protect distinct
182
+ // assertions and remain distinguishable in reviews.
183
+ export const EVM_BRIDGE_NATIVE_INPUT_REFUND_SLACK = 2_000_000_000_000_000n; // 0.002 ETH
184
+
177
185
  // Native SOL has two on-chain spellings that denote the same asset: the
178
186
  // canonical wrapped-SOL mint (what the CLI resolves `SOL` to and persists as
179
187
  // the request intent) and the System Program address that aggregators and
@@ -966,7 +974,9 @@ export function isBridgeRequest(request) {
966
974
  * Four assertions, all derived from the persisted request intent + the quote:
967
975
  * 1. the input token leaves the wallet by no MORE than maxInputAmount. Native
968
976
  * input excludes gas: the sim deltas are log-based, so gas (not a transfer
969
- * log) is never counted.
977
+ * log) is never counted. For exact-in cross-chain bridges with native ETH
978
+ * input, the lower outflow floor is relaxed by EVM_BRIDGE_NATIVE_INPUT_REFUND_SLACK
979
+ * to tolerate routers that refund a small unused remainder of msg.value.
970
980
  * 2. the output token arrives by AT LEAST minOut — exactOut: >= the requested
971
981
  * output; exactIn: the quoted output reduced by the slippage in effect.
972
982
  * SKIPPED for a cross-chain bridge: the output settles on the destination
@@ -1033,6 +1043,7 @@ export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpend
1033
1043
 
1034
1044
  // Bridges skip only assertion 2 (output arrival) below — see isBridgeRequest.
1035
1045
  const isBridge = isBridgeRequest(request);
1046
+ const inputIsNative = inputToken === EVM_NATIVE_SENTINEL;
1036
1047
 
1037
1048
  // --- Assertion 1: input outflow within the spend ceiling ---
1038
1049
  // This bounds the outflow by maxInputAmount (the slippage-buffered ceiling),
@@ -1073,8 +1084,9 @@ export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpend
1073
1084
  // fee-only or 1-unit no-op would still verify a bridge that never funded its
1074
1085
  // input. For exactIn the outflow must be ~the requested input (assertion 1
1075
1086
  // already caps it above); for exactOut the input is variable up to the cap, so
1076
- // only a positive-outflow floor is meaningful. EVM native input delta is the
1077
- // transferred value with gas excluded, so the outflow is exact — no fee slack.
1087
+ // only a positive-outflow floor is meaningful. For native ETH input the floor
1088
+ // is relaxed by EVM_BRIDGE_NATIVE_INPUT_REFUND_SLACK to tolerate routers that
1089
+ // refund a small unused portion of msg.value; token input floors remain exact.
1078
1090
  if (isBridge) {
1079
1091
  if (swapMode === 'exactIn') {
1080
1092
  if (request.amount == null) throw fail('bridge exactIn request is missing the requested input amount.');
@@ -1085,8 +1097,19 @@ export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpend
1085
1097
  throw fail(`requested input amount (${request.amount}) is not an integer.`);
1086
1098
  }
1087
1099
  if (requested <= 0n) throw fail(`bridge exactIn request has a non-positive input amount (${requested}).`);
1088
- if (outflow < requested) {
1089
- throw fail(`the bridge moved only ${outflow} of the input token (${inputToken}) out of the wallet, below the requested input (${requested}); a bridge must spend its full input on the source chain.`);
1100
+ const floorSlack = inputIsNative ? EVM_BRIDGE_NATIVE_INPUT_REFUND_SLACK : 0n;
1101
+ // Cap at requested / 2n: for bridges below 2 × EVM_BRIDGE_NATIVE_INPUT_REFUND_SLACK
1102
+ // (~0.004 ETH), the applied slack shrinks proportionally so the floor stays ≥ 50 %
1103
+ // of the requested amount rather than collapsing toward zero.
1104
+ const appliedSlack = floorSlack < requested / 2n ? floorSlack : requested / 2n;
1105
+ const minOutflow = requested - appliedSlack;
1106
+ if (outflow < minOutflow) {
1107
+ throw fail(
1108
+ `the bridge moved only ${outflow} of the input token (${inputToken}) out of the wallet, ` +
1109
+ `below the minimum required outflow (${minOutflow})` +
1110
+ `${inputIsNative ? ` (requested ${requested} minus native refund slack ${appliedSlack})` : ''}` +
1111
+ `; a bridge must spend its input on the source chain.`
1112
+ );
1090
1113
  }
1091
1114
  } else if (outflow <= 0n) {
1092
1115
  throw fail(`the bridge moved no input token (${inputToken}) out of the wallet; a bridge must spend its input on the source chain.`);
@@ -1164,6 +1187,17 @@ export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpend
1164
1187
  // threshold the caller passes (gas is already excluded from the native delta).
1165
1188
  // ERC-20 siblings and every same-chain swap keep strict-zero. This mirrors the
1166
1189
  // native-only carve-out assertSolanaSwapOutcome already applies for SOL.
1190
+ //
1191
+ // Empirically (survey of the shipping quote path, Sept 2026) no reachable Base
1192
+ // token-input bridge route charges such a native fee: the live aggregator for
1193
+ // Base bridges returns tx.value 0 on token inputs, and the other aggregator
1194
+ // returns no Base route at all. So this carve-out is latent defense-in-depth
1195
+ // today, kept because backend routing can change (a new route, or a fee added).
1196
+ //
1197
+ // Wallet-owned intermediate-token bridge routes are intentionally unsupported
1198
+ // here unless a future quote format identifies the intermediate token and a
1199
+ // safe maximum outflow. Treat every ERC-20 sibling as strict-zero so a route
1200
+ // cannot drain unrelated wallet holdings under the label of "intermediate".
1167
1201
  const nativeDust = isBridge && siblingDustThreshold > 0n ? siblingDustThreshold : 0n;
1168
1202
  for (const [token, delta] of Object.entries(deltas)) {
1169
1203
  if (token === inputToken) continue; // its outflow is bounded by assertion 1
package/src/trading.js CHANGED
@@ -5,6 +5,7 @@
5
5
  * Zero external dependencies — uses Node.js built-in crypto only.
6
6
  */
7
7
 
8
+ import { rejectBlankOption } from './query-options.js';
8
9
  import crypto from 'crypto';
9
10
  import fs from 'fs';
10
11
  import path from 'path';
@@ -635,8 +636,22 @@ export function signSolanaTransaction(transactionBase64, privateKeyHex) {
635
636
  // blockhash fetch (no wasted RPC round trip on a request we're going to reject).
636
637
  const SIZE_CHECK_BLOCKHASH = '11111111111111111111111111111111';
637
638
 
639
+ function formatInstructionDataForError(value) {
640
+ try {
641
+ const s = JSON.stringify(value);
642
+ return s.length > 200 ? s.slice(0, 200) + '…' : s;
643
+ } catch {
644
+ return String(value);
645
+ }
646
+ }
647
+
638
648
  function decodeInstructionData(hex) {
639
649
  if (hex == null || hex === '') return Buffer.alloc(0); // some instructions legitimately carry no data
650
+ if (typeof hex !== 'string') {
651
+ throw new Error(
652
+ `Cannot compile Solana transaction: instruction data is not valid hex (${formatInstructionDataForError(hex)})`
653
+ );
654
+ }
640
655
  const body = hex.startsWith('0x') ? hex.slice(2) : hex;
641
656
  // Buffer.from(str, 'hex') silently drops a trailing odd nibble and stops at
642
657
  // the first non-hex character, so it would decode malformed data into a
@@ -2014,6 +2029,12 @@ export function buildTradingCommands(deps = {}) {
2014
2029
 
2015
2030
  return {
2016
2031
  'quote': async (args, apiInstance, flags, options) => {
2032
+ for (const [name, example] of [
2033
+ ['swap-mode', 'exactIn'], ['wallet', '<name>'], ['to-chain', 'solana'],
2034
+ ['aggregator', 'relay'], ['amount-unit', 'base'],
2035
+ ]) {
2036
+ rejectBlankOption(options[name], name, example);
2037
+ }
2017
2038
  const chain = options.chain || args[0];
2018
2039
  const toChainRaw = options['to-chain'];
2019
2040
  const fromRaw = options.from || options['from-token'] || args[1];
@@ -2047,6 +2068,15 @@ export function buildTradingCommands(deps = {}) {
2047
2068
  // can't become a 300% slippage tolerance.
2048
2069
  for (const [optName, optVal] of [['slippage', slippage], ['max-auto-slippage', maxAutoSlippage]]) {
2049
2070
  if (optVal == null) continue;
2071
+ // A blank value must not read as "not supplied": `Number('')` is 0, which
2072
+ // would pass the range check below and satisfy the exactOut cap
2073
+ // requirement even though the caller supplied no number.
2074
+ if (typeof optVal === 'string' && optVal.trim() === '') {
2075
+ throw new CommandError(
2076
+ `Invalid --${optName} "". Use a decimal between 0 and 1 (e.g. 0.03 for 3%).`,
2077
+ 'INVALID_SLIPPAGE'
2078
+ );
2079
+ }
2050
2080
  const n = Number(optVal);
2051
2081
  if (!Number.isFinite(n) || n < 0 || n > 1) {
2052
2082
  throw new CommandError(
@@ -2335,9 +2365,9 @@ CROSS-CHAIN NOTES (when using --to-chain):
2335
2365
  }
2336
2366
  }
2337
2367
  }
2338
- if (slippage) params.slippagePercent = slippage;
2368
+ if (slippage != null) params.slippagePercent = slippage;
2339
2369
  if (autoSlippage) params.autoSlippage = true;
2340
- if (maxAutoSlippage) params.maxAutoSlippagePercent = maxAutoSlippage;
2370
+ if (maxAutoSlippage != null) params.maxAutoSlippagePercent = maxAutoSlippage;
2341
2371
  if (swapMode !== 'exactIn') params.swapMode = swapMode;
2342
2372
 
2343
2373
  const response = await getQuote(params);
@@ -2470,6 +2500,7 @@ CROSS-CHAIN NOTES (when using --to-chain):
2470
2500
  },
2471
2501
 
2472
2502
  'execute': async (args, apiInstance, flags, options) => {
2503
+ rejectBlankOption(options.wallet, 'wallet', '<name>');
2473
2504
  const quoteId = options.quote || options['quote-id'] || args[0];
2474
2505
  const walletName = options.wallet;
2475
2506
  const noSimulate = flags['no-simulate'];
@@ -101,10 +101,10 @@ const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
101
101
  * POSIX, so a concurrent `nansen` reader always sees either the old file or the
102
102
  * fully-written new one — never a truncated/empty file.
103
103
  *
104
- * The registry URL is overridable via NANSEN_REGISTRY_URL purely as a test seam
105
- * (lets a test point the child at a local server); it defaults to npm.
104
+ * The URL is injectable as the third argument, which is how the tests point the
105
+ * child at a local server. It defaults to the npm registry.
106
106
  */
107
- export function buildCheckScript(dir, file, url = process.env.NANSEN_REGISTRY_URL || REGISTRY_URL) {
107
+ export function buildCheckScript(dir, file, url = REGISTRY_URL) {
108
108
  return `
109
109
  const url = ${JSON.stringify(url)};
110
110
  const http = require(url.startsWith('https:') ? 'https' : 'http');
@@ -112,11 +112,17 @@ export function buildCheckScript(dir, file, url = process.env.NANSEN_REGISTRY_UR
112
112
  const dir = ${JSON.stringify(dir)};
113
113
  const file = ${JSON.stringify(file)};
114
114
  const req = http.get(url, { timeout: 5000 }, (res) => {
115
+ if (res.statusCode < 200 || res.statusCode >= 300) {
116
+ res.resume();
117
+ return;
118
+ }
119
+
115
120
  let body = '';
116
121
  res.on('data', c => body += c);
117
122
  res.on('end', () => {
118
123
  try {
119
124
  const { version } = JSON.parse(body);
125
+ if (typeof version !== 'string' || version.trim() === '') return;
120
126
  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { mode: 0o700, recursive: true });
121
127
  const tmp = file + '.' + process.pid + '.tmp';
122
128
  try {
package/src/wallet.js CHANGED
@@ -3,6 +3,7 @@
3
3
  * Local key generation and storage for EVM and Solana chains.
4
4
  */
5
5
 
6
+ import { rejectBlankOption } from './query-options.js';
6
7
  import crypto from 'crypto';
7
8
  import fs from 'fs';
8
9
  import path from 'path';
@@ -588,6 +589,7 @@ export function buildWalletCommands(deps = {}) {
588
589
  return {
589
590
  'wallet': async (args, apiInstance, flags, options) => {
590
591
  const subcommand = args[0] || 'help';
592
+ if (subcommand === 'create') rejectBlankOption(options.name, 'name', '<name>');
591
593
 
592
594
  // Privy-specific: only 'create' and policy commands need --provider privy
593
595
  if (options.provider === 'privy' || process.env.NANSEN_WALLET_PROVIDER === 'privy') {
@@ -837,6 +839,8 @@ export function buildWalletCommands(deps = {}) {
837
839
  },
838
840
 
839
841
  'send': async () => {
842
+ rejectBlankOption(options.token, 'token', '<token-address>');
843
+ rejectBlankOption(options.wallet, 'wallet', '<name>');
840
844
  const { sendTokens } = await import('./transfer.js');
841
845
 
842
846
  if (!options.to) {