nansen-cli 1.8.0 → 1.9.1

package/src/wallet.js

@@ -629,45 +629,47 @@ export function buildWalletCommands(deps = {}) {
 
         'send': async () => {
           const { sendTokens } = await import('./transfer.js');
-          
+
           if (!options.to) {
             log('❌ --to <address> is required');
             exit(1);
             return;
           }
-          
+
           const isMax = flags.max || options.amount === 'max';
           if (!options.amount && !isMax) {
             log('❌ --amount <number> or --max is required');
             exit(1);
             return;
           }
-          
+
           if (!options.chain) {
             log('❌ --chain <evm|solana> is required');
             exit(1);
             return;
           }
-          
+
           if (!['evm', 'solana', 'ethereum', 'base'].includes(options.chain)) {
             log('❌ --chain must be one of: evm, solana, ethereum, base');
             exit(1);
             return;
           }
-          
-          const password = process.env.NANSEN_WALLET_PASSWORD || await promptPassword('Enter wallet password: ', deps);
+
+          const isWalletConnect = options.wallet === 'walletconnect' || options.wallet === 'wc';
+          const password = isWalletConnect ? null : (process.env.NANSEN_WALLET_PASSWORD || await promptPassword('Enter wallet password: ', deps));
           const dryRun = flags['dry-run'] || flags.dryRun;
-          
+
           try {
             const sendOpts = {
               to: options.to,
               amount: isMax ? '0' : String(options.amount),
               chain: options.chain,
               token: options.token || null,
-              wallet: options.wallet || null,
+              wallet: isWalletConnect ? null : (options.wallet || null),
               max: isMax,
               password,
               dryRun,
+              walletconnect: isWalletConnect,
             };
 
             if (dryRun) {
@@ -731,7 +733,7 @@ OPTIONS:
   --amount <number>          Amount to send in human-readable format (required unless --max)
   --chain <evm|solana>       Blockchain to use (required for send)
   --token <address>          Token contract/mint address (optional, sends native if omitted)
-  --wallet <name>            Wallet to use (optional, uses default if omitted)
+  --wallet <name>            Wallet to use (optional, uses default if omitted; use "walletconnect" or "wc" for WalletConnect, EVM only)
   --max                      Send entire balance (deducts gas for native transfers)
 
 ENVIRONMENT:

package/src/walletconnect-exec.js

@@ -0,0 +1,22 @@
+/**
+ * Shared subprocess helper for WalletConnect CLI calls.
+ *
+ * Used by walletconnect-x402.js and walletconnect-trading.js.
+ */
+
+import { execFile } from 'child_process';
+
+/**
+ * Execute a walletconnect CLI command and return stdout.
+ */
+export function wcExec(cmd, args, timeoutMs = 10000) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: timeoutMs }, (err, stdout, stderr) => {
+      if (err) {
+        reject(new Error(err.message));
+        return;
+      }
+      resolve(stdout.trim());
+    });
+  });
+}

package/src/walletconnect-trading.js

@@ -0,0 +1,91 @@
+/**
+ * WalletConnect Trading & Transfer Support
+ *
+ * Allows signing and broadcasting transactions via a WalletConnect-connected wallet
+ * (hardware wallets, mobile wallets) instead of local key storage.
+ * Uses the walletconnect CLI binary (subprocess-based, same as x402).
+ *
+ * EVM only — Solana via WalletConnect is not supported.
+ */
+
+import { wcExec } from './walletconnect-exec.js';
+
+/**
+ * Get the address of the connected WalletConnect wallet.
+ * Returns the first account address, or null if not connected / binary missing.
+ */
+export async function getWalletConnectAddress() {
+  try {
+    const output = await wcExec('walletconnect', ['whoami', '--json'], 3000);
+    const data = JSON.parse(output);
+    if (data.connected === false) return null;
+    return data.accounts?.[0]?.address || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Send a transaction via WalletConnect.
+ *
+ * The connected wallet signs and may broadcast the transaction.
+ * Returns either { txHash } (wallet broadcast) or { signedTransaction } (we broadcast).
+ *
+ * @param {object} txData - Transaction data: { to, data, value, gas, chainId }
+ * @param {number} [timeoutMs=120000] - Timeout for user approval
+ * @returns {{ txHash?: string, signedTransaction?: string }}
+ */
+export async function sendTransactionViaWalletConnect(txData, timeoutMs = 120000) {
+  // The walletconnect CLI expects chainId as "eip155:<id>" string format
+  const chainId = txData.chainId
+    ? (String(txData.chainId).startsWith('eip155:') ? txData.chainId : `eip155:${txData.chainId}`)
+    : undefined;
+
+  const payload = {
+    to: txData.to,
+    data: txData.data || '0x',
+    value: txData.value ? '0x' + BigInt(txData.value).toString(16) : '0x0',
+    gas: txData.gas ? '0x' + BigInt(txData.gas).toString(16) : undefined,
+    chainId,
+  };
+
+  const output = await wcExec('walletconnect', ['send-transaction', JSON.stringify(payload)], timeoutMs);
+
+  // walletconnect may print status messages before the JSON line — extract JSON only
+  const jsonLine = output.split('\n').find(line => line.startsWith('{'));
+  if (!jsonLine) throw new Error('No JSON output from walletconnect send-transaction');
+  const result = JSON.parse(jsonLine);
+
+  // The CLI returns { transactionHash: "0x..." }
+  if (result.transactionHash) return { txHash: result.transactionHash };
+  if (result.txHash) return { txHash: result.txHash };
+  if (result.signedTransaction) return { signedTransaction: result.signedTransaction };
+
+  throw new Error('Unexpected response from walletconnect send-transaction');
+}
+
+/**
+ * Send an ERC-20 approval via WalletConnect.
+ *
+ * Builds approve(spender, MAX_UINT256) calldata and delegates to sendTransactionViaWalletConnect.
+ *
+ * @param {string} tokenAddress - ERC-20 token contract
+ * @param {string} spenderAddress - Approval target (e.g. DEX router)
+ * @param {number} chainId - EIP-155 chain ID
+ * @returns {{ txHash?: string, signedTransaction?: string }}
+ */
+export async function sendApprovalViaWalletConnect(tokenAddress, spenderAddress, chainId) {
+  // ERC-20 approve(address spender, uint256 amount) selector = 0x095ea7b3
+  const MAX_UINT256_HEX = 'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff';
+  const data = '0x095ea7b3'
+    + spenderAddress.slice(2).toLowerCase().padStart(64, '0')
+    + MAX_UINT256_HEX;
+
+  return sendTransactionViaWalletConnect({
+    to: tokenAddress,
+    data,
+    value: '0',
+    gas: '100000',
+    chainId,
+  });
+}

package/src/walletconnect-x402.js

@@ -0,0 +1,215 @@
+/**
+ * x402 Auto-Payment via WalletConnect
+ *
+ * Handles automatic payment signing when the API returns HTTP 402.
+ * Uses the walletconnect CLI to check wallet connection and sign EIP-712 typed data.
+ */
+
+import crypto from 'crypto';
+import { NansenError, ErrorCode } from './api.js';
+import { wcExec } from './walletconnect-exec.js';
+import { EVM_CHAIN_IDS } from './chain-ids.js';
+
+/**
+ * Check if a WalletConnect wallet session is active.
+ * Returns { wallet, accounts, expires } or null.
+ */
+export async function checkWalletConnection() {
+  try {
+    const output = await wcExec('walletconnect', ['whoami', '--json'], 3000);
+    const data = JSON.parse(output);
+    if (data.connected === false) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Select a compatible payment requirement from the accepts array.
+ * Requires scheme=exact and EIP-3009 TransferWithAuthorization support (extra.name + extra.version).
+ */
+export function selectPaymentRequirement(accepts) {
+  if (!Array.isArray(accepts) || accepts.length === 0) return null;
+
+  return accepts.find(req =>
+    req.scheme === 'exact' &&
+    req.extra?.name &&
+    req.extra?.version
+  ) || null;
+}
+
+/**
+ * Parse chain ID from network string (e.g., "eip155:8453" → 8453)
+ */
+function parseChainId(network) {
+  if (!network) return null;
+  const match = network.match(/^eip155:(\d+)$/);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Build EIP-712 typed data for TransferWithAuthorization (EIP-3009).
+ */
+export function buildEIP712TypedData({ fromAddress, requirement }) {
+  const { asset, payTo, extra, maxTimeoutSeconds } = requirement;
+  // x402 uses "amount", fall back to "maxAmountRequired" for compatibility
+  const amount = requirement.amount || requirement.maxAmountRequired;
+
+  // Determine chain ID: extra.chainId > parsed from network > fallback map > base
+  const chainId = extra.chainId || parseChainId(requirement.network) || EVM_CHAIN_IDS[requirement.chain] || EVM_CHAIN_IDS.base;
+
+  const now = Math.floor(Date.now() / 1000);
+  const nonce = '0x' + crypto.randomBytes(32).toString('hex');
+
+  const typedData = {
+    types: {
+      EIP712Domain: [
+        { name: 'name', type: 'string' },
+        { name: 'version', type: 'string' },
+        { name: 'chainId', type: 'uint256' },
+        { name: 'verifyingContract', type: 'address' },
+      ],
+      TransferWithAuthorization: [
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'validAfter', type: 'uint256' },
+        { name: 'validBefore', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+      ],
+    },
+    primaryType: 'TransferWithAuthorization',
+    domain: {
+      name: extra.name,
+      version: extra.version,
+      chainId,
+      verifyingContract: asset,
+    },
+    message: {
+      from: fromAddress,
+      to: payTo,
+      value: amount,
+      validAfter: now - 600, // 10 min in the past to tolerate clock skew between client and verifier
+      validBefore: now + (maxTimeoutSeconds || 120),
+      nonce,
+    },
+  };
+
+  return typedData;
+}
+
+/**
+ * Build the base64-encoded Payment-Signature header value.
+ * Follows x402 v2 spec: { x402Version, resource, accepted, payload }
+ */
+export function buildPaymentSignatureHeader({ signature, authorization, resource, accepted }) {
+  const paymentPayload = {
+    x402Version: 2,
+    resource: resource || { url: '', description: '', mimeType: '' },
+    accepted: accepted || {},
+    payload: {
+      signature,
+      authorization,
+    },
+  };
+  return btoa(JSON.stringify(paymentPayload));
+}
+
+/**
+ * Format amount for human-readable display (e.g., "0.01 USDC")
+ */
+function formatPaymentAmount(requirement) {
+  const { extra } = requirement;
+  const rawAmount = requirement.amount || requirement.maxAmountRequired;
+  const symbol = extra.symbol || extra.name || 'tokens';
+  const decimals = extra.decimals || 6;
+  const amount = Number(rawAmount) / Math.pow(10, decimals);
+  const chain = requirement.network || requirement.chain || 'unknown';
+  return `${amount} ${symbol} on ${chain}`;
+}
+
+/**
+ * Handle x402 payment: check wallet, sign, return Payment-Signature header.
+ *
+ * @param {Object} paymentRequirements - Decoded payment requirements from 402 response
+ * @param {string} requestUrl - The original request URL (for context in errors)
+ * @returns {string} Base64-encoded Payment-Signature header value
+ * @throws {NansenError} On failure
+ */
+export async function handleX402Payment(paymentRequirements) {
+  // 1. Check wallet connection
+  const wallet = await checkWalletConnection();
+  if (!wallet) {
+    throw new NansenError(
+      'x402 payment required but no wallet connected. Run `walletconnect connect` first.',
+      ErrorCode.PAYMENT_REQUIRED,
+      402
+    );
+  }
+
+  const fromAddress = wallet.accounts[0]?.address;
+  if (!fromAddress) {
+    throw new NansenError(
+      'x402 payment required but wallet has no accounts.',
+      ErrorCode.PAYMENT_REQUIRED,
+      402
+    );
+  }
+
+  // 2. Select compatible payment requirement
+  const accepts = paymentRequirements.accepts || paymentRequirements;
+  const requirement = selectPaymentRequirement(Array.isArray(accepts) ? accepts : [accepts]);
+  if (!requirement) {
+    const available = (Array.isArray(accepts) ? accepts : []).map(r => r.scheme).join(', ');
+    throw new NansenError(
+      `x402 payment required but no compatible payment method found. Available: ${available || 'none'}. Need scheme=exact with EIP-3009 support.`,
+      ErrorCode.PAYMENT_REQUIRED,
+      402
+    );
+  }
+
+  // 3. Build EIP-712 typed data
+  const typedData = buildEIP712TypedData({ fromAddress, requirement });
+  const typedDataJson = JSON.stringify(typedData);
+
+  // 4. Log payment info to stderr (stdout is for JSON output)
+  const amountStr = formatPaymentAmount(requirement);
+  process.stderr.write(`x402: Requesting payment approval (${amountStr})...\n`);
+
+  // 5. Sign via walletconnect CLI (120s timeout for user approval)
+  let signResult;
+  try {
+    const output = await wcExec('walletconnect', ['sign-typed-data', typedDataJson], 120000);
+    // walletconnect may print status messages before the JSON line — extract JSON only
+    const jsonLine = output.split('\n').find(line => line.startsWith('{'));
+    if (!jsonLine) throw new Error('No JSON output from walletconnect sign-typed-data');
+    signResult = JSON.parse(jsonLine);
+  } catch (err) {
+    throw new NansenError(
+      `x402 payment signing failed: ${err.message}`,
+      ErrorCode.PAYMENT_REQUIRED,
+      402
+    );
+  }
+
+  // 6. Build Payment-Signature header (authorization values must be strings per x402 spec)
+  const authorization = {
+    from: fromAddress,
+    to: requirement.payTo,
+    value: (requirement.amount || requirement.maxAmountRequired).toString(),
+    validAfter: typedData.message.validAfter.toString(),
+    validBefore: typedData.message.validBefore.toString(),
+    nonce: typedData.message.nonce,
+  };
+
+  const headerValue = buildPaymentSignatureHeader({
+    signature: signResult.signature,
+    authorization,
+    resource: paymentRequirements.resource || { url: '', description: '', mimeType: '' },
+    accepted: requirement,
+  });
+
+  process.stderr.write(`x402: Payment signed successfully.\n`);
+  return headerValue;
+}

package/.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in the repository](https://github.com/changesets/changesets)
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/AGENTS.md

@@ -1,176 +0,0 @@
-# AGENTS.md — Contributor Guide
-
-Guidance for AI coding agents (Claude Code, Codex, Copilot, etc.) working on this repository. If you're an agent **using** the CLI, see [README.md](README.md).
-
-## Architecture
-
-```
-src/
-├── index.js          # Entry point (shebang, calls runCLI)
-├── cli.js            # Command router, arg parsing, schema, help text
-├── api.js            # NansenAPI client (REST, retry, cache, x402 auto-pay)
-├── wallet.js         # Wallet CRUD (create/list/show/export/delete/send)
-├── trading.js        # Quote + execute swaps (OKX router via API)
-├── transfer.js       # Token/native transfers (EVM + Solana)
-├── x402.js           # x402 payment orchestration (picks network, signs)
-├── x402-evm.js       # EVM payment signing (EIP-3009 transferWithAuthorization)
-├── x402-svm.js       # Solana payment signing (SPL transfer)
-├── crypto.js         # Key encryption/decryption (AES-256-GCM or plaintext)
-└── update-check.js   # Version upgrade notice
-```
-
-### Command routing
-
-`src/index.js` → `runCLI()` in `src/cli.js`
-
-Commands are built by three functions, merged in `runCLI()`:
-- `buildCommands()` in cli.js — analytics commands (smart-money, profiler, token, etc.)
-- `buildWalletCommands()` in wallet.js — wallet subcommands
-- `buildTradingCommands()` in trading.js — quote/execute
-
-Commands listed in `NO_AUTH_COMMANDS` skip API initialization. Everything else instantiates `NansenAPI` with retry, cache, and x402 config.
-
-### Data flow: trade
-
-```
-CLI args → api.js GET /defi/quote → quote response
-         → wallet.js decrypt key → trading.js sign tx → api.js POST /defi/execute → broadcast
-```
-
-### Data flow: x402 auto-pay
-
-```
-api.js (any call) → 402 response with payment requirements
-→ x402.js rankRequirements() → picks cheapest network (EVM first)
-→ x402-evm.js or x402-svm.js → sign USDC payment
-→ api.js retries original request with Payment-Signature header
-```
-
-If EVM payment fails (insufficient funds), the async generator yields a Solana signature as fallback.
-
-### Output convention
-
-Core functions return data objects. The CLI layer formats via `formatOutput()`. Never `console.log` in core functions — use the `log` dependency injection for CLI output.
-
-## Development
-
-```bash
-npm install           # Install dependencies
-npm test              # Run tests (vitest)
-npm run test:watch    # Watch mode
-npm run test:coverage # With coverage
-```
-
-### Running locally
-
-```bash
-node src/index.js <command> [options]
-
-# Examples
-node src/index.js wallet create my-wallet
-node src/index.js smart-money --chain solana --limit 5
-```
-
-## Testing
-
-- **Framework:** Vitest
-- **Test files:** `src/__tests__/*.test.js`
-- **Current:** 577 tests across 13 test files
-- **All new code must have tests**
-- **Mock all RPC/API calls** — never hit real networks in tests
-
-### Test structure
-
-```js
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-global.fetch = vi.fn();
-
-describe('featureName', () => {
-  beforeEach(() => {
-    fetch.mockReset();
-  });
-
-  it('should do the thing', async () => {
-    fetch.mockResolvedValueOnce({
-      ok: true,
-      json: async () => ({ jsonrpc: '2.0', result: '0x...', id: 1 })
-    });
-    // test logic
-  });
-});
-```
-
-### Required RPC mocks by code path
-
-**EVM transfers:** `eth_getBalance`, `eth_gasPrice`, `eth_maxPriorityFeePerGas`, `eth_getTransactionCount`, `eth_estimateGas`, `eth_getCode`, `eth_sendRawTransaction`, `eth_getTransactionReceipt`
-
-**Solana transfers:** `getBalance`, `getLatestBlockhash`, `sendTransaction`, `getSignatureStatuses`
-
-**SPL token transfers** (additionally): `getTokenAccountsByOwner`, `getAccountInfo`
-
-**Wallet operations:** No RPC mocks needed (file I/O only). Mock `fs` if testing file paths.
-
-**API calls:** Mock `fetch` to return `{ ok: true, json: () => ({...}) }` or `{ ok: false, status: 402, headers: new Headers({...}) }` for x402 paths.
-
-## Style Guide
-
-- **ESM only** (`import`/`export`). No TypeScript, no transpilation.
-- **No interactive prompts in core functions.** Use env vars: `NANSEN_WALLET_PASSWORD`, `NANSEN_API_KEY`.
-- **Error handling:** `throw new Error('descriptive message')` in core. CLI catches and formats.
-- **Actionable error messages** — tell the user what to do:
-  - ❌ `"Authentication failed"`
-  - ✅ `"Not logged in. Run: nansen login"`
-- **BigInt for token amounts.** Never use floating point. Parse to BigInt with decimals.
-- **Chain branching:** Use `chain === 'solana'` checks, not inheritance/polymorphism.
-- **Minimal dependencies.** Prefer Node.js built-in APIs (crypto, fs, path, http).
-
-## PR Checklist
-
-- [ ] `npm test` passes (all tests)
-- [ ] New code paths have test coverage
-- [ ] No hardcoded secrets, API keys, or private keys
-- [ ] No `console.log` in core functions (use `log` dep injection)
-- [ ] Error messages are actionable (tell user what to do)
-- [ ] CLI help text updated if adding/changing commands
-- [ ] RPC mocks cover all methods in the code path
-- [ ] Wallet flows work both with and without `NANSEN_WALLET_PASSWORD`
-- [ ] Changeset added if changing user-facing behavior (add a `.changeset/<name>.md` file — `npm test` will warn if missing)
-
-## Chains & Networks
-
-**EVM:** Ethereum (chain ID 1), Base (8453). `CHAIN_IDS` in transfer.js only maps these two — other EVM chains will fail for transfers.
-
-**Solana:** mainnet-beta. Supports native SOL, standard SPL tokens, and Token-2022 (Token Extensions).
-
-**RPC endpoints:** Hardcoded in `CHAIN_RPCS` (transfer.js). Nansen API handles RPC for trading.
-
-## Key Constants
-
-| Constant | Value |
-|----------|-------|
-| USDC (Base) | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
-| USDC (Solana) | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
-| x402 payment | $0.05 USDC per API call |
-| Gas buffer | API provides `quote.gas` with 1.5x multiplier — use directly |
-
-## Endpoint Quirks
-
-These are internal details agents should know when writing or debugging tests:
-
-- **`token holders --smart-money`** — Returns `UNSUPPORTED_FILTER` for tokens without smart money tracking. Not all tokens have this data.
-- **`token flow-intelligence`** — May return all-zero flows for illiquid tokens. Normal, not an error.
-- **`token screener --search`** — Client-side filtering. The CLI fetches up to 500 results, then filters locally.
-- **`--fields`** — Applies to the entire response tree, including the `success`/`data` wrapper.
-- **Profiler beta endpoints** use `recordsPerPage` instead of `per_page`. The CLI handles this automatically.
-- **`profiler perp-positions`** — No pagination support; the API ignores the pagination parameter.
-
-## Known Gotchas
-
-1. **EIP-7702 delegated accounts** on Base have contract code. Always use `eth_estimateGas`, never hardcode 21000 gas.
-2. **Solana SPL account ordering:** Writable accounts (destATA) must precede readonly (mint) in the transaction message.
-3. **`getSignatureStatuses`** over `confirmTransaction` — the latter is deprecated and unreliable on public RPCs.
-4. **`--max` native SOL:** Reserve 5000 lamports for fee. On EVM L2s, reserve 3x estimated gas for L1 data posting fees.
-5. **Token-2022:** Use `TOKEN_2022_PROGRAM_ID` and `TransferCheckedInstruction` (not plain `Transfer`).
-6. **CreateATA path:** When recipient doesn't have a token account, the sender creates it. This path in transfer.js has limited test coverage — add tests if modifying.
-7. **`CHAIN_IDS` is incomplete:** Only ethereum and base are mapped. Adding new EVM chain support requires updating this map.