nansen-cli 2.2.0 → 2.4.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.
Files changed (78) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +109 -33
  3. package/docs/auth.md +56 -0
  4. package/docs/browser-login.md +101 -7
  5. package/docs/error-codes.md +249 -0
  6. package/package.json +10 -4
  7. package/skills/nansen-agent-guide/SKILL.md +54 -1
  8. package/skills/nansen-alerts-webhook-listener/SKILL.md +1 -1
  9. package/skills/nansen-dca-tracker/SKILL.md +1 -1
  10. package/skills/nansen-defi-positions/SKILL.md +1 -1
  11. package/skills/nansen-exit-signals/SKILL.md +2 -2
  12. package/skills/nansen-fund-tracker/SKILL.md +1 -1
  13. package/skills/nansen-general-search/SKILL.md +1 -1
  14. package/skills/nansen-holder-analysis/SKILL.md +2 -2
  15. package/skills/nansen-limit-orders/SKILL.md +1 -1
  16. package/skills/nansen-mpp-payment/SKILL.md +2 -2
  17. package/skills/nansen-perp-screener/SKILL.md +1 -1
  18. package/skills/nansen-perp-trader-profile/SKILL.md +1 -1
  19. package/skills/nansen-polymarket-deep-dive/SKILL.md +1 -1
  20. package/skills/nansen-polymarket-insider-scan/SKILL.md +1 -1
  21. package/skills/nansen-polymarket-trader-profile/SKILL.md +1 -1
  22. package/skills/nansen-portfolio-tracker/SKILL.md +1 -1
  23. package/skills/nansen-prediction-markets/SKILL.md +1 -1
  24. package/skills/nansen-sm-cross-chain-flows/SKILL.md +1 -1
  25. package/skills/nansen-smart-alerts/SKILL.md +2 -1
  26. package/skills/nansen-smart-money-alpha/SKILL.md +1 -1
  27. package/skills/nansen-smart-money-tracker/SKILL.md +8 -7
  28. package/skills/nansen-smart-money-trend/SKILL.md +1 -1
  29. package/skills/nansen-token-research/SKILL.md +1 -1
  30. package/skills/nansen-token-screener/SKILL.md +1 -1
  31. package/skills/nansen-token-transfer-analysis/SKILL.md +1 -1
  32. package/skills/nansen-trading/SKILL.md +1 -1
  33. package/skills/nansen-wallet-batch/SKILL.md +1 -1
  34. package/skills/nansen-wallet-clustering/SKILL.md +1 -1
  35. package/skills/nansen-wallet-deep-dive/SKILL.md +1 -1
  36. package/skills/nansen-wallet-keychain-migration/SKILL.md +1 -1
  37. package/skills/nansen-wallet-manager/SKILL.md +1 -1
  38. package/skills/nansen-wallet-profiler/SKILL.md +1 -1
  39. package/skills/nansen-web-fetcher/SKILL.md +1 -1
  40. package/skills/nansen-web-searcher/SKILL.md +1 -1
  41. package/src/api-endpoints.json +1605 -0
  42. package/src/api.js +336 -121
  43. package/src/auth-credentials.js +1 -0
  44. package/src/auth-state.js +2 -2
  45. package/src/auth-store-native.js +6 -1
  46. package/src/auth-store-worker.js +1 -1
  47. package/src/auth-store.js +9 -4
  48. package/src/bridge.js +19 -10
  49. package/src/cli.js +258 -107
  50. package/src/commands/agent.js +2 -3
  51. package/src/commands/alerts.js +277 -9
  52. package/src/commands/completion.js +6 -1
  53. package/src/commands/feedback.js +413 -0
  54. package/src/commands/mcp.js +1 -1
  55. package/src/commands/research.js +14 -37
  56. package/src/cost-cache.js +33 -7
  57. package/src/doctor.js +14 -5
  58. package/src/error-codes.js +226 -0
  59. package/src/feedback-journal.js +86 -0
  60. package/src/input-validation.js +551 -0
  61. package/src/limit-order.js +12 -3
  62. package/src/perp.js +2 -1
  63. package/src/privy.js +144 -48
  64. package/src/query-options.js +30 -7
  65. package/src/rpc-urls.js +3 -1
  66. package/src/schema.json +1254 -150
  67. package/src/solana-tx.js +4 -0
  68. package/src/telemetry.js +5 -1
  69. package/src/trade-validation.js +190 -21
  70. package/src/trading.js +229 -129
  71. package/src/transfer.js +7 -1
  72. package/src/update-check.js +32 -5
  73. package/src/wallet.js +220 -57
  74. package/src/walletconnect-x402.js +152 -52
  75. package/src/x402-audit.js +191 -0
  76. package/src/x402-payment-balance.js +90 -0
  77. package/src/x402-policy.js +151 -4
  78. package/src/x402.js +51 -22
package/src/trading.js CHANGED
@@ -16,7 +16,7 @@ import { buildMessageV0, fetchAddressLookupTables, fetchRecentBlockhash } from '
16
16
  import { keccak256, signSecp256k1, rlpEncode } from './crypto.js';
17
17
  import { getWalletConnectAddress, sendTransactionViaWalletConnect, sendSolanaTransactionViaWalletConnect, sendApprovalViaWalletConnect } from './walletconnect-trading.js';
18
18
  import { retrievePassword } from './keychain.js';
19
- import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance, encodeApproveCalldata, assertValidApprovalSpender, assertQuoteMatchesRequest, assertSwapCalldataNotBareTransfer, assertSwapOutcome, assertSolanaInstructionsSafe, assertSolanaSwapOutcome, approvalAmountForSwap, needsAllowanceRevoke, OVERSIZED_ALLOWANCE_MULTIPLIER, EVM_BRIDGE_NATIVE_FEE_SLACK, isBridgeRequest } from './trade-validation.js';
19
+ import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance, encodeApproveCalldata, assertValidApprovalSpender, assertQuoteMatchesRequest, assertSwapCalldataNotBareTransfer, assertSwapOutcome, assertSolanaInstructionsSafe, checkSolanaFeeBalance, assertSolanaSwapOutcome, approvalAmountForSwap, needsAllowanceRevoke, OVERSIZED_ALLOWANCE_MULTIPLIER, EVM_BRIDGE_NATIVE_FEE_SLACK, isBridgeRequest } from './trade-validation.js';
20
20
  import { readCompactU16 } from './solana-tx.js';
21
21
  import { formatPlan, guardExecution, resolveExecuteGuard } from './execute-guard.js';
22
22
  export { readCompactU16 };
@@ -128,7 +128,9 @@ export function resolveTokenAddress(symbolOrAddress, chainName) {
128
128
  // - RPC_NETWORK_ERROR — request left but no response (reset/timeout): ambiguous
129
129
  // - RPC_HTTP_ERROR — non-JSON HTTP response (e.g. a 502 gateway page): ambiguous
130
130
  // - RPC_JSON_ERROR — a JSON-RPC { error }: the node definitively rejected it
131
- export async function evmRpcCall(chain, method, params = []) {
131
+ // `timeoutMs` (optional) aborts a request that has not completed in time; it
132
+ // surfaces as RPC_NETWORK_ERROR. Without it a request has no time limit.
133
+ export async function evmRpcCall(chain, method, params = [], { timeoutMs } = {}) {
132
134
  const rpcUrl = CHAIN_RPCS[chain];
133
135
  if (!rpcUrl) throw Object.assign(new Error(`No RPC URL configured for chain: ${chain}`), { code: 'RPC_UNCONFIGURED' });
134
136
  let res;
@@ -137,6 +139,7 @@ export async function evmRpcCall(chain, method, params = []) {
137
139
  method: 'POST',
138
140
  headers: { 'Content-Type': 'application/json' },
139
141
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
142
+ ...(timeoutMs ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
140
143
  });
141
144
  } catch (netErr) {
142
145
  // The request left this process but no response came back. A reset or
@@ -357,8 +360,8 @@ function assertUsableTxId(body, chainType) {
357
360
  const check = (field, label, isValid) => {
358
361
  const value = body[field];
359
362
  // Absent is not malformed. Whether an identifier is REQUIRED depends on the
360
- // execution mode (gasless EVM and Solana have no locally derived hash), so
361
- // that call stays at the call site.
363
+ // execution mode (Solana has no locally derived hash), so that call stays
364
+ // at the call site.
362
365
  if (value === undefined || value === null || value === '') return;
363
366
  if (typeof value !== 'string' || !isValid(value)) {
364
367
  throw ambiguousBroadcast(
@@ -1477,6 +1480,68 @@ export async function waitForReceipt(chain, txHash, timeoutMs = 180000, pollMs =
1477
1480
  throw timeoutErr;
1478
1481
  }
1479
1482
 
1483
+ // A Solana transaction can only land while its recent blockhash is valid
1484
+ // (150 slots, roughly 60 to 90 seconds). 90s covers that window, so a timeout
1485
+ // usually means the transaction was dropped. It is still reported as
1486
+ // unconfirmed, never as failed: the CLI has not proven it cannot land.
1487
+ export const SOLANA_CONFIRM_TIMEOUT_MS = 90000;
1488
+ // Upper bound on a single status request inside that window.
1489
+ const SOLANA_RPC_REQUEST_TIMEOUT_MS = 10000;
1490
+
1491
+ /**
1492
+ * Wait for a Solana signature to reach `confirmed` commitment. The Solana
1493
+ * counterpart of waitForReceipt. It throws the same two codes, so the swap path
1494
+ * and isFatalBroadcastError treat both chain types alike:
1495
+ * - TX_REVERTED the transaction landed and failed (status `err` is set)
1496
+ * - RECEIPT_TIMEOUT no confirmed status in the window; it may still land
1497
+ *
1498
+ * An `err` seen at `processed` is not trusted: that slot can still be rolled
1499
+ * back, so the poll keeps going until the status is at least `confirmed`.
1500
+ * RPC and network errors are retried until the deadline, like waitForReceipt.
1501
+ *
1502
+ * @param {string} chain - chain key in CHAIN_RPCS (normally 'solana')
1503
+ * @param {string} signature - base58 transaction signature
1504
+ * @param {number} [timeoutMs]
1505
+ * @param {number} [pollMs]
1506
+ * @returns {Promise<object>} the signature status
1507
+ */
1508
+ export async function waitForSolanaSignature(chain, signature, timeoutMs = SOLANA_CONFIRM_TIMEOUT_MS, pollMs = 2000) {
1509
+ const start = Date.now();
1510
+ while (Date.now() - start < timeoutMs) {
1511
+ let status = null;
1512
+ try {
1513
+ // evmRpcCall is a plain JSON-RPC POST to CHAIN_RPCS[chain]; nothing in it
1514
+ // is EVM-specific. Each request is bounded by the time left, so a hung
1515
+ // request cannot outlive the deadline; an abort is a transient failure.
1516
+ const remainingMs = Math.max(1, timeoutMs - (Date.now() - start));
1517
+ const result = await evmRpcCall(chain, 'getSignatureStatuses', [[signature]], {
1518
+ timeoutMs: Math.min(SOLANA_RPC_REQUEST_TIMEOUT_MS, remainingMs),
1519
+ });
1520
+ status = result?.value?.[0] ?? null;
1521
+ } catch {
1522
+ // Transient RPC failure: keep polling until the deadline.
1523
+ }
1524
+ if (status) {
1525
+ // Older nodes omit confirmationStatus and report `confirmations: null`
1526
+ // for a rooted (finalized) transaction.
1527
+ const level = status.confirmationStatus
1528
+ ?? (status.confirmations === null ? 'finalized' : 'processed');
1529
+ if (level === 'confirmed' || level === 'finalized') {
1530
+ if (status.err) {
1531
+ const failErr = new Error(`Transaction failed on-chain: ${JSON.stringify(status.err)}. Signature: ${signature}`);
1532
+ failErr.code = 'TX_REVERTED';
1533
+ throw failErr;
1534
+ }
1535
+ return status;
1536
+ }
1537
+ }
1538
+ await new Promise(r => setTimeout(r, pollMs));
1539
+ }
1540
+ const timeoutErr = new Error(`Transaction not confirmed after ${timeoutMs}ms. Signature: ${signature}`);
1541
+ timeoutErr.code = 'RECEIPT_TIMEOUT';
1542
+ throw timeoutErr;
1543
+ }
1544
+
1480
1545
  /**
1481
1546
  * Post-broadcast outcomes that must abort the whole `execute` rather than fall
1482
1547
  * through to the next quote. Ambiguous failures may conceal a live transaction;
@@ -1567,6 +1632,46 @@ function assertTxHashMatch(signedTxHex, broadcasterTxHash, label = '') {
1567
1632
  return localHash;
1568
1633
  }
1569
1634
 
1635
+ /**
1636
+ * The Solana counterpart of assertTxHashMatch. A Solana transaction id is its
1637
+ * first signature (the fee payer's), so it is read straight out of the signed
1638
+ * bytes: [signatures_count (compact-u16)] [signatures (64 bytes each)...] ...
1639
+ *
1640
+ * Fails closed (TXHASH_MISMATCH) when the execute API reported a different
1641
+ * signature, and with INVALID_SIGNED_TX when none can be read from our bytes.
1642
+ *
1643
+ * @param {string} signedTxBase64 - the signed transaction we sent to /execute
1644
+ * @param {string} broadcasterSignature - the signature /execute returned (may be empty)
1645
+ * @returns {string} our locally-derived base58 signature
1646
+ */
1647
+ function assertSolanaSignatureMatch(signedTxBase64, broadcasterSignature) {
1648
+ let localSignature;
1649
+ try {
1650
+ const txBytes = Buffer.from(signedTxBase64 || '', 'base64');
1651
+ const { value: sigCount, size: sigCountSize } = readCompactU16(txBytes, 0);
1652
+ if (sigCount < 1) throw new Error('transaction has no signature slots');
1653
+ if (txBytes.length < sigCountSize + 64) throw new Error('transaction is too short to hold a signature');
1654
+ localSignature = base58Encode(txBytes.subarray(sigCountSize, sigCountSize + 64));
1655
+ } catch (sigErr) {
1656
+ throw new CommandError(
1657
+ `Aborting: cannot derive a local signature for the transaction this CLI signed: ${sigErr.message}. `
1658
+ + `The transaction may already have been broadcast, so nothing further will run — `
1659
+ + `check your wallet before retrying.`,
1660
+ 'INVALID_SIGNED_TX',
1661
+ );
1662
+ }
1663
+ if (broadcasterSignature && broadcasterSignature !== localSignature) {
1664
+ throw new CommandError(
1665
+ `Aborting: the broadcaster reported transaction ${broadcasterSignature}, but the transaction this CLI signed `
1666
+ + `has signature ${localSignature}. These must match — a mismatch means the confirmation would be for `
1667
+ + `a transaction you did not sign, so nothing has been verified and no further steps will `
1668
+ + `run. Check both signatures on a block explorer to see what was actually broadcast before retrying.`,
1669
+ 'TXHASH_MISMATCH',
1670
+ );
1671
+ }
1672
+ return localSignature;
1673
+ }
1674
+
1570
1675
  /**
1571
1676
  * Confirm a broadcast EVM transaction against the hash we derived locally from
1572
1677
  * the signed bytes — not the hash the broadcaster reported. See
@@ -1652,7 +1757,7 @@ function toRpcHexValue(value) {
1652
1757
  * guards: the cheap eth_call sim answers "will it revert", this answers "does the
1653
1758
  * outcome match intent" (see assertSwapOutcome in trade-validation.js).
1654
1759
  *
1655
- * EVM-only, and on its own gate independent of --no-simulate/gasless. Runs for
1760
+ * EVM-only, and on its own gate independent of --no-simulate. Runs for
1656
1761
  * cross-chain bridges too — assertSwapOutcome skips only the output-arrival
1657
1762
  * assertion internally, since the output lands on the destination chain and a
1658
1763
  * source-chain simulation can't observe it; the input-outflow and no-sibling-
@@ -2601,7 +2706,6 @@ export async function buildTradeExecutionPlan({
2601
2706
  quoteIndex = 0,
2602
2707
  quoteCount = 1,
2603
2708
  walletAddress = null,
2604
- gasless = false,
2605
2709
  noSimulate = false,
2606
2710
  noVerifyOutcome = false,
2607
2711
  probe = false,
@@ -2646,8 +2750,6 @@ export async function buildTradeExecutionPlan({
2646
2750
  if (probe && chainConfig.type === 'evm') {
2647
2751
  if (noSimulate) {
2648
2752
  simulation = 'skipped (--no-simulate)';
2649
- } else if (gasless) {
2650
- simulation = 'skipped (--gasless routes through the solver)';
2651
2753
  } else if (approvalPending) {
2652
2754
  simulation = 'skipped — runs after the approval transaction lands';
2653
2755
  } else {
@@ -2681,7 +2783,6 @@ export async function buildTradeExecutionPlan({
2681
2783
  ['Trading fee', quote.tradingFeeInUsd ? `$${quote.tradingFeeInUsd}` : null],
2682
2784
  ['Network fee', quote.networkFeeInUsd ? `$${quote.networkFeeInUsd}` : null],
2683
2785
  ['Approval', approval],
2684
- ['Gas', gasless ? 'paid by the solver (--gasless)' : null],
2685
2786
  ['Simulation', simulation],
2686
2787
  ['Outcome check', noVerifyOutcome ? 'off (--no-verify-outcome)' : 'on, before broadcast'],
2687
2788
  ]);
@@ -2703,27 +2804,12 @@ async function preflightTradeExecutionCandidate({
2703
2804
  chain,
2704
2805
  chainConfig,
2705
2806
  walletAddress,
2706
- isWalletConnect,
2707
- gasless,
2708
2807
  noSimulate,
2709
2808
  noVerifyOutcome,
2710
2809
  api,
2711
2810
  verifiedTargets,
2712
2811
  log,
2713
2812
  }) {
2714
- if (gasless && quote.aggregator !== 'relay') {
2715
- throw new CommandError(
2716
- `--gasless is only supported for Relay quotes, not "${quote.aggregator}".`,
2717
- 'GASLESS_UNSUPPORTED_AGGREGATOR',
2718
- );
2719
- }
2720
- if (gasless && isWalletConnect) {
2721
- throw new CommandError(
2722
- 'Gasless swaps are not supported via WalletConnect. Use a local or Privy wallet.',
2723
- 'GASLESS_UNSUPPORTED_WALLET',
2724
- );
2725
- }
2726
-
2727
2813
  if (!walletAddress) {
2728
2814
  throw new CommandError(
2729
2815
  'The cached quote has no signer address, so it cannot be validated safely. Request a new quote.',
@@ -2743,7 +2829,11 @@ async function preflightTradeExecutionCandidate({
2743
2829
  CHAIN_RPCS.solana,
2744
2830
  async () => walletAddress,
2745
2831
  );
2746
- assertSolanaInstructionsSafe(txBase64, { walletAddress });
2832
+ const safeTx = assertSolanaInstructionsSafe(txBase64, { walletAddress });
2833
+ const feeCheck = await checkSolanaFeeBalance({ parsed: safeTx, walletAddress, log });
2834
+ if (!feeCheck.proceed) {
2835
+ throw new CommandError(`Insufficient SOL for this transaction: ${feeCheck.reason}`, 'INSUFFICIENT_GAS');
2836
+ }
2747
2837
  if (!noVerifyOutcome) {
2748
2838
  const outcome = await verifySolanaSwapOutcome({
2749
2839
  chain,
@@ -2825,7 +2915,7 @@ async function preflightTradeExecutionCandidate({
2825
2915
  // approval cannot reproduce that future state and reports the deferral in
2826
2916
  // its plan instead.
2827
2917
  if (!approvalPending) {
2828
- if (!noSimulate && !gasless) {
2918
+ if (!noSimulate) {
2829
2919
  const tx = quote.transaction;
2830
2920
  const sim = await simulateEvmCall(chain, {
2831
2921
  from: walletAddress,
@@ -3331,10 +3421,8 @@ CROSS-CHAIN NOTES (when using --to-chain):
3331
3421
  response.quotes.forEach((q, i) => log(formatQuote(q, i)));
3332
3422
 
3333
3423
  // Gas balance validation — check that the wallet has enough native token for gas.
3334
- // High-value trades (>= $10) can use gasless/solver-paid routes and bypass this check.
3335
3424
  try {
3336
- const tradeValueUsd = response.quotes[0]?.inUsdValue;
3337
- await validateGasBalance({ chain, walletAddress, tradeValueUsd });
3425
+ await validateGasBalance({ chain, walletAddress });
3338
3426
  } catch (gasErr) {
3339
3427
  throw new CommandError(`Error: ${gasErr.message}`, 'INSUFFICIENT_GAS');
3340
3428
  }
@@ -3397,7 +3485,18 @@ CROSS-CHAIN NOTES (when using --to-chain):
3397
3485
  const noSimulate = flags['no-simulate'];
3398
3486
  const noRevokeExcessiveAllowance = flags['no-revoke-excessive-allowance'];
3399
3487
  const noVerifyOutcome = flags['no-verify-outcome'];
3400
- const gasless = Boolean(flags.gasless);
3488
+ // --gasless is gone. The deprecated broadcast route it posted to validates
3489
+ // its body strictly and has never accepted `gasless` or `steps`, so every
3490
+ // gasless swap was rejected with "Unrecognized keys" before broadcast, on
3491
+ // every chain. Rejected loudly rather than ignored: a script that still
3492
+ // passes it asked the solver to pay, and silently paying its own gas
3493
+ // instead is not a substitution we should make for it.
3494
+ if (flags.gasless) {
3495
+ throw new CommandError(
3496
+ '--gasless has been removed: the backend never accepted gasless swaps from the CLI, so the flag failed before broadcast on every chain. Re-run without it — the wallet pays its own gas.',
3497
+ 'GASLESS_REMOVED',
3498
+ );
3499
+ }
3401
3500
  // Parsed before the quote is touched so a typo can't consume it. A bare
3402
3501
  // --max-tx-fee lands in flags, not options, so it would otherwise read as
3403
3502
  // "not given" and silently apply the default cap.
@@ -3421,7 +3520,6 @@ OPTIONS:
3421
3520
  --no-verify-outcome Skip swap-outcome verification (balance-delta check)
3422
3521
  --no-revoke-excessive-allowance
3423
3522
  Skip auto-revoking an oversized/legacy allowance before re-approving
3424
- --gasless Relay-only: have Relay's solver pay gas (no WalletConnect)
3425
3523
  --max-tx-fee <eth> Most one transaction may pay for gas (fee cap x gas limit).
3426
3524
  Default 1 ETH; 0 disables the check.
3427
3525
  --dry-run Validate and print what would be sent, then stop.
@@ -3475,13 +3573,10 @@ EXAMPLES:
3475
3573
  // Resolved once here, before any signing, so an unrecognised route value
3476
3574
  // aborts the command instead of surfacing mid-loop as a per-quote failure.
3477
3575
  const configuredRoute = executionRoute();
3478
- // Gasless stays on the legacy route: the standard route has no gasless
3479
- // envelope, so sending a signed Relay authorization there would drop the
3480
- // gasless framing and submit it as a plain swap. Only a non-gasless swap
3481
- // can opt into the standard route. Resolved here rather than at the
3482
- // broadcast call because the WalletConnect branch — which may never reach
3483
- // that call — also has to know which route is in force.
3484
- const swapRoute = gasless ? 'legacy' : configuredRoute;
3576
+ // Named apart from configuredRoute because the WalletConnect branch —
3577
+ // which may never reach the broadcast call — also has to know which route
3578
+ // is in force.
3579
+ const swapRoute = configuredRoute;
3485
3580
 
3486
3581
  // The standard route keys its per-quote single-flight lock on the backend
3487
3582
  // quote id, so a submission without one claims duplicate protection and
@@ -3507,7 +3602,9 @@ EXAMPLES:
3507
3602
  // --quote-index pins a specific quote (no fallback)
3508
3603
  let pinIndex = null;
3509
3604
  if (options['quote-index'] != null) {
3510
- pinIndex = parseInt(options['quote-index'], 10);
3605
+ // parseInt alone would read "1.9" or "1abc" as 1 and pin a quote the user did not pick.
3606
+ const rawIndex = String(options['quote-index']).trim();
3607
+ pinIndex = /^\d+$/.test(rawIndex) ? Number(rawIndex) : NaN;
3511
3608
  if (!Number.isInteger(pinIndex) || pinIndex < 0 || pinIndex >= allQuotes.length) {
3512
3609
  throw new CommandError(
3513
3610
  `❌ Invalid --quote-index "${options['quote-index']}". Must be an integer between 0 and ${allQuotes.length - 1}.`,
@@ -3537,8 +3634,6 @@ EXAMPLES:
3537
3634
  .map((quote, index) => ({ quote, index }))
3538
3635
  .filter(({ quote, index }) => index >= startIndex && index < endIndex && quote?.transaction);
3539
3636
  const shouldPreflightPlan = guard.dryRun || (guard.isTTY && !guard.assumeYes);
3540
- const planUsesWalletConnect = quoteData.signerType === 'walletconnect'
3541
- || walletName === 'walletconnect' || walletName === 'wc';
3542
3637
  if (guard.dryRun) {
3543
3638
  // The live signer is intentionally unavailable here: dry-run reaches
3544
3639
  // this gate before wallet material or a WalletConnect session is
@@ -3574,8 +3669,6 @@ EXAMPLES:
3574
3669
  chain,
3575
3670
  chainConfig,
3576
3671
  walletAddress: planWallet,
3577
- isWalletConnect: planUsesWalletConnect,
3578
- gasless,
3579
3672
  noSimulate,
3580
3673
  noVerifyOutcome,
3581
3674
  api: apiInstance,
@@ -3614,7 +3707,6 @@ EXAMPLES:
3614
3707
  quoteIndex: index,
3615
3708
  quoteCount: allQuotes.length,
3616
3709
  walletAddress: planWallet,
3617
- gasless,
3618
3710
  noSimulate,
3619
3711
  noVerifyOutcome,
3620
3712
  probe: true,
@@ -3770,20 +3862,6 @@ EXAMPLES:
3770
3862
  }
3771
3863
 
3772
3864
  const isRelay = currentQuote.aggregator === 'relay';
3773
- if (gasless) {
3774
- if (!isRelay) {
3775
- throw new CommandError(
3776
- `--gasless is only supported for Relay quotes. Selected quote ${quoteName} is from "${currentQuote.aggregator}". Re-run with --quote-index to pin a Relay quote, or omit --gasless.`,
3777
- 'GASLESS_UNSUPPORTED_AGGREGATOR'
3778
- );
3779
- }
3780
- if (isWalletConnect) {
3781
- throw new CommandError(
3782
- 'Gasless swaps are not supported via WalletConnect (mobile wallets typically auto-broadcast, breaking the gasless flow). Use a local or Privy wallet.',
3783
- 'GASLESS_UNSUPPORTED_WALLET'
3784
- );
3785
- }
3786
- }
3787
3865
 
3788
3866
  log(`\nExecuting trade on ${chainConfig.name}...`);
3789
3867
  if (endIndex - startIndex > 1) {
@@ -3832,7 +3910,19 @@ EXAMPLES:
3832
3910
  // alone wouldn't see. The residual sibling-transfer gap is closed by
3833
3911
  // verifySolanaSwapOutcome below (degrades gracefully when no sim RPC
3834
3912
  // is available, so this static check remains a guard when sim is off).
3835
- assertSolanaInstructionsSafe(txBase64, { walletAddress });
3913
+ const safeTx = assertSolanaInstructionsSafe(txBase64, { walletAddress });
3914
+
3915
+ // Check the wallet can pay this transaction's actual fee.
3916
+ // Runs regardless of --no-verify-outcome: simulation would also
3917
+ // catch an unpayable transaction, but not when it is skipped or
3918
+ // degraded. Warns and proceeds if the balance read fails.
3919
+ const feeCheck = await checkSolanaFeeBalance({ parsed: safeTx, walletAddress, log });
3920
+ if (!feeCheck.proceed) {
3921
+ log(` ❌ ${quoteName} cannot be paid for: ${feeCheck.reason}`);
3922
+ if (qi + 1 < endIndex) log(' Trying next quote...');
3923
+ lastQuoteError = `${quoteName} insufficient SOL: ${feeCheck.reason}`;
3924
+ continue;
3925
+ }
3836
3926
 
3837
3927
  // Verify the swap's simulated on-chain outcome matches intent.
3838
3928
  // Degrades with a warning if no simulation endpoint is available.
@@ -4060,7 +4150,7 @@ EXAMPLES:
4060
4150
  }
4061
4151
 
4062
4152
  // Pre-flight simulation
4063
- if (!noSimulate && !gasless) {
4153
+ if (!noSimulate) {
4064
4154
  const sim = await simulateEvmCall(chain, {
4065
4155
  from: walletAddress,
4066
4156
  to: currentQuote.transaction.to,
@@ -4076,8 +4166,8 @@ EXAMPLES:
4076
4166
  }
4077
4167
 
4078
4168
  // Verify the swap's simulated on-chain outcome matches intent.
4079
- // Its own gate (runs even when --no-simulate/gasless skip the
4080
- // cheap revert check above); degrades with a warning if no
4169
+ // Its own gate (runs even when --no-simulate skips the cheap
4170
+ // revert check above); degrades with a warning if no
4081
4171
  // simulation endpoint is available.
4082
4172
  if (!noVerifyOutcome) {
4083
4173
  const outcome = await verifySwapOutcome({ chain, from: walletAddress, quote: currentQuote, quoteData, api: apiInstance, log });
@@ -4158,7 +4248,19 @@ EXAMPLES:
4158
4248
  // alone wouldn't see. The residual sibling-transfer gap is closed by
4159
4249
  // verifySolanaSwapOutcome below (degrades gracefully when no sim RPC
4160
4250
  // is available, so this static check remains a guard when sim is off).
4161
- assertSolanaInstructionsSafe(txBase64, { walletAddress: solanaWalletAddress });
4251
+ const safeTx = assertSolanaInstructionsSafe(txBase64, { walletAddress: solanaWalletAddress });
4252
+
4253
+ // Check the wallet can pay this transaction's actual fee.
4254
+ // Runs regardless of --no-verify-outcome: simulation would also
4255
+ // catch an unpayable transaction, but not when it is skipped or
4256
+ // degraded. Warns and proceeds if the balance read fails.
4257
+ const feeCheck = await checkSolanaFeeBalance({ parsed: safeTx, walletAddress: solanaWalletAddress, log });
4258
+ if (!feeCheck.proceed) {
4259
+ log(` ❌ ${quoteName} cannot be paid for: ${feeCheck.reason}`);
4260
+ if (qi + 1 < endIndex) log(' Trying next quote...');
4261
+ lastQuoteError = `${quoteName} insufficient SOL: ${feeCheck.reason}`;
4262
+ continue;
4263
+ }
4162
4264
 
4163
4265
  // Verify the swap's simulated on-chain outcome matches intent.
4164
4266
  // Degrades with a warning if no simulation endpoint is available.
@@ -4469,7 +4571,7 @@ EXAMPLES:
4469
4571
  }
4470
4572
 
4471
4573
  // Pre-flight simulation
4472
- if (!noSimulate && !gasless) {
4574
+ if (!noSimulate) {
4473
4575
  const txData = currentQuote.transaction;
4474
4576
  const sim = await simulateEvmCall(chain, {
4475
4577
  from: wcAddress,
@@ -4486,8 +4588,8 @@ EXAMPLES:
4486
4588
  }
4487
4589
 
4488
4590
  // Verify the swap's simulated on-chain outcome matches intent. Its
4489
- // own gate: runs even when --no-simulate/gasless skip the cheap
4490
- // eth_call revert check above; degrades with a warning when no
4591
+ // own gate: runs even when --no-simulate skips the cheap eth_call
4592
+ // revert check above; degrades with a warning when no
4491
4593
  // simulation endpoint is set.
4492
4594
  if (!noVerifyOutcome) {
4493
4595
  const outcome = await verifySwapOutcome({ chain, from: wcAddress, quote: currentQuote, quoteData, api: apiInstance, log });
@@ -4831,7 +4933,7 @@ EXAMPLES:
4831
4933
  // Pre-flight simulation (EVM only) — catch logic reverts before spending gas
4832
4934
  // Runs AFTER approval so eth_call sees the current allowance state
4833
4935
  // Simulates WITHOUT gas limit to check swap logic; gas re-estimation is separate
4834
- if (!noSimulate && !gasless) {
4936
+ if (!noSimulate) {
4835
4937
  const txData = currentQuote.transaction;
4836
4938
  const sim = await simulateEvmCall(chain, {
4837
4939
  from: walletAddress,
@@ -4848,8 +4950,8 @@ EXAMPLES:
4848
4950
  }
4849
4951
 
4850
4952
  // Verify the swap's simulated on-chain outcome matches intent. Its
4851
- // own gate: runs even when --no-simulate/gasless skip the cheap
4852
- // eth_call revert check above; degrades with a warning when no
4953
+ // own gate: runs even when --no-simulate skips the cheap eth_call
4954
+ // revert check above; degrades with a warning when no
4853
4955
  // simulation endpoint is set.
4854
4956
  if (!noVerifyOutcome) {
4855
4957
  const outcome = await verifySwapOutcome({ chain, from: walletAddress, quote: currentQuote, quoteData, api: apiInstance, log });
@@ -4880,11 +4982,11 @@ EXAMPLES:
4880
4982
  );
4881
4983
  }
4882
4984
 
4883
- log(gasless ? ' Forwarding to Relay solver (gasless)...' : ' Broadcasting...');
4985
+ log(' Broadcasting...');
4884
4986
  const execParams = {
4885
4987
  signedTransaction,
4886
4988
  chain,
4887
- simulate: !noSimulate && !gasless,
4989
+ simulate: !noSimulate,
4888
4990
  };
4889
4991
 
4890
4992
  // The backend quote id, resolved with the route above. The per-quote
@@ -4900,8 +5002,8 @@ EXAMPLES:
4900
5002
  if (quoteIdForExecute) {
4901
5003
  execParams.quoteId = quoteIdForExecute;
4902
5004
  }
4903
- // The backend's /execute schema is strict; sending fields it doesn't expect
4904
- // for the (chain × aggregator × gasless) combination causes 502s or
5005
+ // The backend's /execute schema is strict; sending fields it doesn't
5006
+ // expect for the (chain × aggregator) combination causes 502s or
4905
5007
  // "Unrecognized keys" rejections. The matrix we've validated against the
4906
5008
  // live backend:
4907
5009
  // - EVM signed (any aggregator): no aggregator/requestId fields.
@@ -4910,29 +5012,14 @@ EXAMPLES:
4910
5012
  // intent resolution.
4911
5013
  // - Solana signed (Relay): omit requestId — backend tries to look it up
4912
5014
  // as a Jupiter intent and 502s.
4913
- // - Gasless (EVM): aggregator + gasless + steps + requestId.
4914
- // - Gasless (Solana): currently rejected by the backend ("Unrecognized
4915
- // keys"); we still send the gasless envelope and let the backend
4916
- // surface the error so users notice when support lands.
4917
- if (gasless) {
4918
- execParams.aggregator = 'relay';
4919
- execParams.gasless = true;
4920
- const gaslessRequestId = requestId || currentQuote.metadata?.requestId;
4921
- if (gaslessRequestId) execParams.requestId = gaslessRequestId;
4922
- if (currentQuote.metadata?.steps) execParams.steps = currentQuote.metadata.steps;
4923
- } else if (requestId && !isRelay) {
5015
+ if (requestId && !isRelay) {
4924
5016
  execParams.requestId = requestId; // Solana Jupiter Ultra
4925
5017
  }
4926
5018
 
4927
- // A retry re-POSTs the signed payload. For a normal swap that's a
4928
- // byte-identical replay the node dedupes, so retrying an ambiguous
4929
- // 5xx/network failure can't itself double-broadcast. But a --gasless
4930
- // Relay swap sends a signed AUTHORIZATION, and Relay's solver
4931
- // broadcasts its OWN wrapping tx from it (the returned txHash is not
4932
- // our bytes) — so a re-POST after the solver already picked it up
4933
- // can't be deduped at the node level and risks a second solve. For
4934
- // gasless we therefore don't retry: a single POST either succeeds or
4935
- // fails closed (BROADCAST_FAILED marks the quote spent and aborts).
5019
+ // A retry re-POSTs the signed payload. Every remaining execution mode
5020
+ // sends our own signed bytes, so that is a byte-identical replay the
5021
+ // node dedupes: retrying an ambiguous 5xx/network failure cannot itself
5022
+ // double-broadcast.
4936
5023
  if (swapRoute === 'standard') {
4937
5024
  // Attribution and cross-chain fields the standard route reads from
4938
5025
  // the body. Attached only here because the legacy schema rejects
@@ -4946,19 +5033,17 @@ EXAMPLES:
4946
5033
  }
4947
5034
 
4948
5035
  swapHandedOff = true;
4949
- const result = await executeTransaction(execParams, { retries: gasless ? 0 : undefined, route: swapRoute, attemptId });
5036
+ const result = await executeTransaction(execParams, { route: swapRoute, attemptId });
4950
5037
 
4951
5038
  if (result.status === 'Success') {
4952
- const gaslessEvm = gasless && chainType === 'evm';
4953
5039
  // `signature` is a Solana field. Reading it on EVM let a stray one
4954
5040
  // win over the real `txHash` and reach the explorer URL and the
4955
5041
  // persisted broadcast marker; executeTransaction has already
4956
5042
  // validated the shape of whichever field is used here.
4957
5043
  let txId = chainType === 'evm' ? result.txHash : (result.signature || result.txHash);
4958
- if ((chainType === 'solana' || gaslessEvm) && !txId) {
4959
- const executionType = gaslessEvm ? 'gasless EVM' : 'Solana';
5044
+ if (chainType === 'solana' && !txId) {
4960
5045
  throw ambiguousBroadcast(
4961
- `The execute API reported success for ${quoteName} without a ${executionType} transaction identifier. The broadcast cannot be verified, so no further quote will be tried. Check the wallet on the explorer before retrying.`,
5046
+ `The execute API reported success for ${quoteName} without a Solana transaction identifier. The broadcast cannot be verified, so no further quote will be tried. Check the wallet on the explorer before retrying.`,
4962
5047
  { details: result },
4963
5048
  );
4964
5049
  }
@@ -4968,9 +5053,9 @@ EXAMPLES:
4968
5053
  // Trading API accepts it — the quote is spent here, before the
4969
5054
  // on-chain verification below can throw RECEIPT_TIMEOUT (or
4970
5055
  // anything else) and abort this function. Covers local EVM,
4971
- // Privy EVM, Privy Solana, local/WalletConnect Solana, the
4972
- // WalletConnect sign-only fallback, and --gasless Relay — every
4973
- // path that reaches this shared broadcast call.
5056
+ // Privy EVM, Privy Solana, local/WalletConnect Solana and the
5057
+ // WalletConnect sign-only fallback — every path that reaches this
5058
+ // shared broadcast call.
4974
5059
  //
4975
5060
  // Deliberate: a broadcast that later reverts on-chain still
4976
5061
  // consumes the quote and ends this invocation. The user must
@@ -4997,12 +5082,11 @@ EXAMPLES:
4997
5082
  if (chainType === 'evm') {
4998
5083
  log(` Checking for a receipt anyway — this can take up to 3 minutes and may time out.`);
4999
5084
  } else {
5000
- // Solana has no receipt poll below to resolve this. The EVM
5001
- // branch either confirms the hash or fails closed on a timeout;
5002
- // Solana would fall straight through to "✓ Transaction
5003
- // successful!" and exit 0 for a broadcast the node refused, so
5004
- // an agent would record a swap that may never have propagated.
5005
- // Nothing here verified anything, so do not report success.
5085
+ // Solana fails closed here without waiting on the signature
5086
+ // poll below: a broadcast the node refused is the case most
5087
+ // likely to end in that poll's timeout, so stop now with the
5088
+ // more specific error. Nothing here verified anything, so do
5089
+ // not report success.
5006
5090
  //
5007
5091
  // The quote was marked spent above and no candidate fallback
5008
5092
  // runs from here, so this only changes what we REPORT: a
@@ -5020,30 +5104,20 @@ EXAMPLES:
5020
5104
  // For EVM: verify the tx actually succeeded on-chain
5021
5105
  if (chainType === 'evm') {
5022
5106
  log(' Verifying on-chain status...');
5023
- // Non-gasless: derive our local hash up front, OUTSIDE the receipt-poll
5024
- // try below. A hex-validation failure here means no poll ever ran, so it
5025
- // must surface as itself — not as the "REVERTED on-chain" diagnostic that
5026
- // catch is reserved for. (Gasless has no local hash to bind to: the Relay
5027
- // solver wraps and broadcasts its own tx, so result.txHash legitimately is
5028
- // not the hash of the bytes we signed.)
5029
- if (!gasless) {
5030
- try {
5031
- txId = evmTxHash(signedTransaction);
5032
- } catch (hashErr) {
5033
- throw new CommandError(`Cannot derive local tx hash for ${quoteName}: ${hashErr.message}`, 'INVALID_SIGNED_TX');
5034
- }
5035
- explorerUrl = chainConfig.explorer + txId;
5107
+ // Derive our local hash up front, OUTSIDE the receipt-poll try
5108
+ // below. A hex-validation failure here means no poll ever ran, so it
5109
+ // must surface as itself — not as the "REVERTED on-chain" diagnostic
5110
+ // that catch is reserved for.
5111
+ try {
5112
+ txId = evmTxHash(signedTransaction);
5113
+ } catch (hashErr) {
5114
+ throw new CommandError(`Cannot derive local tx hash for ${quoteName}: ${hashErr.message}`, 'INVALID_SIGNED_TX');
5036
5115
  }
5116
+ explorerUrl = chainConfig.explorer + txId;
5037
5117
  try {
5038
- if (gasless) {
5039
- // If the solver reported no hash there is nothing to poll — skip
5040
- // rather than block on eth_getTransactionReceipt(undefined).
5041
- if (result.txHash) await waitForReceipt(chain, result.txHash);
5042
- } else {
5043
- const { hash } = await confirmEvmBroadcast(chain, signedTransaction, result.txHash);
5044
- txId = hash;
5045
- explorerUrl = chainConfig.explorer + txId;
5046
- }
5118
+ const { hash } = await confirmEvmBroadcast(chain, signedTransaction, result.txHash);
5119
+ txId = hash;
5120
+ explorerUrl = chainConfig.explorer + txId;
5047
5121
  } catch (receiptErr) {
5048
5122
  // A receipt TIMEOUT is not a confirmed revert: the tx was
5049
5123
  // broadcast and may still be pending under our nonce. Retrying
@@ -5064,6 +5138,32 @@ EXAMPLES:
5064
5138
  }
5065
5139
  }
5066
5140
 
5141
+ // For Solana: the execute API's "Success" only says the transaction
5142
+ // was submitted. Solana drops transactions without a trace, and one
5143
+ // that lands can still fail, so ask the chain before reporting
5144
+ // success. Same outcomes and codes as the EVM branch above; both are
5145
+ // fatal (isFatalBroadcastError), so no further quote is tried and
5146
+ // the quote stays marked as spent.
5147
+ if (chainType === 'solana') {
5148
+ log(' Verifying on-chain status...');
5149
+ // Poll the signature of the transaction we signed, not the one
5150
+ // the API reported: a confirmed status for some other
5151
+ // transaction must not count as ours landing.
5152
+ txId = assertSolanaSignatureMatch(signedTransaction, txId);
5153
+ explorerUrl = chainConfig.explorer + txId;
5154
+ try {
5155
+ await waitForSolanaSignature(chain, txId);
5156
+ } catch (statusErr) {
5157
+ if (statusErr.code === 'RECEIPT_TIMEOUT') {
5158
+ throw new CommandError(`\n ⚠ Transaction was submitted but NOT confirmed within the wait window.\n Signature: ${txId}\n Explorer: ${explorerUrl}\n ${statusErr.message}\n\n The transaction may still land. Do NOT assume it failed: check the explorer\n before retrying, because retrying may execute a second swap.`, 'RECEIPT_TIMEOUT');
5159
+ }
5160
+ if (statusErr.code === 'TX_REVERTED') {
5161
+ throw new CommandError(`\n ⚠ Transaction landed but FAILED on-chain!\n Signature: ${txId}\n Explorer: ${explorerUrl}\n Error: ${statusErr.message}\n\n No further quote was attempted. Review the transaction, then request a new quote before retrying.`, 'TX_REVERTED');
5162
+ }
5163
+ throw statusErr;
5164
+ }
5165
+ }
5166
+
5067
5167
  log(`\n ✓ Transaction successful!`);
5068
5168
  log(` Status: ${result.status}`);
5069
5169
  log(` ${chainType === 'solana' ? 'Signature' : 'Tx Hash'}: ${txId}`);