nansen-cli 1.32.0 → 1.33.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.33.0
+
+### Minor Changes
+
+- [#457](https://github.com/nansen-ai/nansen-cli/pull/457) [`8149564`](https://github.com/nansen-ai/nansen-cli/commit/8149564f181dc7bfc9c66488ba2373df6f1aab5d) Thanks [@gulshngill](https://github.com/gulshngill)! - x402 on BNB Smart Chain: support all four stablecoins the API now advertises (U, USD1, USDT, USDC) and add Permit2 payment signing. Payments route on the 402's `extra.assetTransferMethod` — `eip3009` keeps the existing gasless flow (U, USD1), while `permit2-exact` (USDT, USDC on BSC) signs a Permit2 `PermitWitnessTransferFrom` against the spender contract advertised in the 402. Permit2 entries are skipped with an actionable message when the wallet hasn't made the one-time `approve(Permit2, …)` for the token. Post-payment balance warnings now check the exact token paid with (per-token decimals) instead of one hardcoded token per network.
+
+## 1.32.1
+
+### Patch Changes
+
+- [#455](https://github.com/nansen-ai/nansen-cli/pull/455) [`875fabb`](https://github.com/nansen-ai/nansen-cli/commit/875fabb3f86736b03c874904e27a898315ef4bfa) Thanks [@gulshngill](https://github.com/gulshngill)! - Support x402 payments with USDT on BNB Smart Chain (`eip155:56`), which the Nansen API now advertises as a payment option. Payment signing already handled any EVM network generically; this adds BSC to the post-payment balance check with the correct token contract and 18-decimal precision (Base USDC and X Layer USDT0 use 6), plus a `bsc` entry in the shared RPC registry with a `NANSEN_BSC_RPC` override.
+
 ## 1.32.0
 
 ### Minor Changes

package/package.json

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

package/src/api.js

@@ -493,7 +493,7 @@ export class NansenAPI {
    * an attemptX402Payment() method so adding a new payment provider only requires
    * touching that one method, not hunting inside the retry loop.
    */
-  async _x402Retry(signature, walletLabel, network, url, body, options = {}) {
+  async _x402Retry(signature, walletLabel, network, url, body, options = {}, asset = null) {
     const paidResponse = await fetch(url, {
       method: 'POST',
       headers: {
@@ -514,7 +514,7 @@ export class NansenAPI {
     if (network) {
       try {
         const { checkX402Balance } = await import('./x402.js');
-        const result = await checkX402Balance(network);
+        const result = await checkX402Balance(network, asset);
         if (result !== null && result.balance < 0.25) {
           console.error(`[x402] Warning: ${result.symbol} balance low ($${result.balance.toFixed(2)}). Fund your wallet to avoid interruptions.`);
         }
@@ -651,8 +651,8 @@ export class NansenAPI {
               // 1. Try local wallet with fallback across payment networks
               try {
                 const { createPaymentSignatures } = await import('./x402.js');
-                for await (const { signature, network } of createPaymentSignatures(response, url)) {
-                  const result = await this._x402Retry(signature, `local wallet ${defaultWalletName}`, network, url, body, options);
+                for await (const { signature, network, asset } of createPaymentSignatures(response, url)) {
+                  const result = await this._x402Retry(signature, `local wallet ${defaultWalletName}`, network, url, body, options, asset);
                   if (result !== null) return result;
                   // This payment option was rejected, try next
                 }

package/src/rpc-urls.js

@@ -8,6 +8,7 @@
  * Override env vars:
  *   NANSEN_EVM_RPC        Custom Ethereum RPC (also used as generic EVM fallback)
  *   NANSEN_BASE_RPC       Custom Base RPC
+ *   NANSEN_BSC_RPC        Custom BNB Smart Chain RPC
  *   NANSEN_XLAYER_RPC     Custom X Layer RPC
  *   NANSEN_SOLANA_RPC     Custom Solana RPC
  *
@@ -20,6 +21,7 @@
 
 const DEFAULT_EVM_RPC    = 'https://eth.public-rpc.com';
 const DEFAULT_BASE_RPC   = 'https://mainnet.base.org';
+const DEFAULT_BSC_RPC    = 'https://bsc-dataseed.binance.org';
 const DEFAULT_XLAYER_RPC = 'https://rpc.xlayer.tech';
 const DEFAULT_SOLANA_RPC = 'https://api.mainnet-beta.solana.com';
 
@@ -27,6 +29,7 @@ export const CHAIN_RPCS = {
   ethereum: process.env.NANSEN_EVM_RPC    || DEFAULT_EVM_RPC,
   evm:      process.env.NANSEN_EVM_RPC    || DEFAULT_EVM_RPC,   // generic EVM fallback
   base:     process.env.NANSEN_BASE_RPC   || process.env.NANSEN_RPC_BASE || DEFAULT_BASE_RPC,
+  bsc:      process.env.NANSEN_BSC_RPC    || DEFAULT_BSC_RPC,
   xlayer:   process.env.NANSEN_XLAYER_RPC || DEFAULT_XLAYER_RPC,
   solana:   process.env.NANSEN_SOLANA_RPC || DEFAULT_SOLANA_RPC,
 };

package/src/x402-evm.js

@@ -25,6 +25,39 @@ const AUTHORIZATION_TYPES = [
   { name: 'nonce', type: 'bytes32' },
 ];
 
+// ============= Permit2 (permit2-exact transfer method) =============
+// Some tokens (e.g. USDT/USDC on BNB Smart Chain) predate EIP-3009, so
+// facilitators settle them through Uniswap's canonical Permit2 contract
+// instead: the payer signs a PermitWitnessTransferFrom and the facilitator's
+// proxy (requirements.extra.spenderAddress) executes the transfer. Requires a
+// one-time on-chain `token.approve(PERMIT2_ADDRESS, ...)` from the payer.
+
+export const PERMIT2_ADDRESS = '0x000000000022D473030F116dDEE9F6B43aC78BA3';
+
+// Permit2's EIP-712 domain has no version field.
+const PERMIT2_DOMAIN_TYPES = [
+  { name: 'name', type: 'string' },
+  { name: 'chainId', type: 'uint256' },
+  { name: 'verifyingContract', type: 'address' },
+];
+
+const TOKEN_PERMISSIONS_TYPES = [
+  { name: 'token', type: 'address' },
+  { name: 'amount', type: 'uint256' },
+];
+
+const WITNESS_TYPES = [
+  { name: 'to', type: 'address' },
+  { name: 'validAfter', type: 'uint256' },
+];
+
+// encodeType for a nested primary type: referenced struct types are appended
+// in alphabetical order per EIP-712 (TokenPermissions before Witness).
+const PERMIT_WITNESS_TYPE_STRING =
+  'PermitWitnessTransferFrom(TokenPermissions permitted,address spender,uint256 nonce,uint256 deadline,Witness witness)' +
+  'TokenPermissions(address token,uint256 amount)' +
+  'Witness(address to,uint256 validAfter)';
+
 /**
  * Encode a type string for EIP-712 typeHash.
  * e.g. "TransferWithAuthorization(address from,address to,uint256 value,...)"
@@ -110,6 +143,38 @@ export function hashTypedData(domain, primaryType, fields, message) {
   ]));
 }
 
+/**
+ * Compute the EIP-712 digest for a Permit2 PermitWitnessTransferFrom.
+ *
+ * Hand-rolled because the generic helpers above only support flat structs:
+ * the primary typeHash must cover the full type string including referenced
+ * structs, and struct-typed fields encode as their structHash.
+ *
+ * @param {number} chainId - EVM chain id (Permit2 domain field)
+ * @param {object} message - { permitted: {token, amount}, spender, nonce, deadline, witness: {to, validAfter} }
+ * @returns {Buffer} 32-byte digest to sign
+ */
+export function hashPermit2WitnessTransfer(chainId, message) {
+  const domainSeparator = hashStruct('EIP712Domain', PERMIT2_DOMAIN_TYPES, {
+    name: 'Permit2',
+    chainId,
+    verifyingContract: PERMIT2_ADDRESS,
+  });
+  const structHash = keccak256(Buffer.concat([
+    keccak256(Buffer.from(PERMIT_WITNESS_TYPE_STRING, 'utf8')),
+    hashStruct('TokenPermissions', TOKEN_PERMISSIONS_TYPES, message.permitted),
+    encodeValue('address', message.spender),
+    encodeValue('uint256', message.nonce),
+    encodeValue('uint256', message.deadline),
+    hashStruct('Witness', WITNESS_TYPES, message.witness),
+  ]));
+  return keccak256(Buffer.concat([
+    Buffer.from([0x19, 0x01]),
+    domainSeparator,
+    structHash,
+  ]));
+}
+
 // ============= x402 EVM Payment =============
 
 /**
@@ -123,7 +188,13 @@ function getChainId(network) {
 }
 
 /**
- * Create an x402 payment payload for EVM (EIP-3009 TransferWithAuthorization).
+ * Create an x402 payment payload for EVM.
+ *
+ * Routes on requirements.extra.assetTransferMethod: absent or "eip3009" signs
+ * an EIP-3009 TransferWithAuthorization (gasless); "permit2-exact" signs a
+ * Permit2 PermitWitnessTransferFrom (requires a prior one-time
+ * token.approve(PERMIT2_ADDRESS, ...)). Other methods throw so the fallback
+ * loop tries the next accepts entry.
  *
  * @param {object} requirements - Parsed PaymentRequirements from 402 response
  * @param {string} privateKeyHex - 32-byte EVM private key as hex
@@ -135,6 +206,14 @@ export function createEvmPaymentPayload(requirements, privateKeyHex, walletAddre
   const chainId = getChainId(requirements.network);
   const extra = requirements.extra || {};
 
+  const method = extra.assetTransferMethod;
+  if (method === 'permit2-exact') {
+    return createPermit2ExactPayload(requirements, privateKeyHex, walletAddress, resource);
+  }
+  if (method && method !== 'eip3009') {
+    throw new Error(`Unsupported assetTransferMethod: ${method}`);
+  }
+
   // Token name and version from requirements.extra (set by server/facilitator)
   const tokenName = extra.name;
   const tokenVersion = extra.version || '1';
@@ -199,6 +278,71 @@ export function createEvmPaymentPayload(requirements, privateKeyHex, walletAddre
   return Buffer.from(JSON.stringify(payload)).toString('base64');
 }
 
+/**
+ * Create an x402 payment payload via Permit2 PermitWitnessTransferFrom
+ * (assetTransferMethod "permit2-exact").
+ *
+ * The spender is the facilitator's Permit2 proxy advertised in
+ * requirements.extra.spenderAddress; the witness binds the transfer to the
+ * merchant wallet (requirements.payTo). Wire-format numeric fields are
+ * decimal strings.
+ *
+ * @param {object} requirements - Parsed PaymentRequirements from 402 response
+ * @param {string} privateKeyHex - 32-byte EVM private key as hex
+ * @param {string} walletAddress - Signer's EVM address
+ * @param {string} resource - Original request URL
+ * @returns {string} Base64-encoded PaymentPayload for Payment-Signature header
+ */
+export function createPermit2ExactPayload(requirements, privateKeyHex, walletAddress, resource) {
+  const chainId = getChainId(requirements.network);
+  const extra = requirements.extra || {};
+  const spender = extra.spenderAddress;
+  if (!spender) {
+    throw new Error('spenderAddress missing from requirements.extra (required for permit2-exact)');
+  }
+
+  const payTo = requirements.pay_to || requirements.payTo;
+  const now = Math.floor(Date.now() / 1000);
+  // 256-bit random nonce — Permit2 uses an unordered nonce bitmap.
+  const nonce = BigInt('0x' + crypto.randomBytes(32).toString('hex')).toString();
+  const deadline = String(now + 3600);
+  const validAfter = String(now - 60); // allow clock skew
+
+  const message = {
+    permitted: { token: requirements.asset, amount: BigInt(requirements.amount) },
+    spender,
+    nonce: BigInt(nonce),
+    deadline: BigInt(deadline),
+    witness: { to: payTo, validAfter: BigInt(validAfter) },
+  };
+
+  const msgHash = hashPermit2WitnessTransfer(chainId, message);
+  const { r, s, v } = signSecp256k1(msgHash, Buffer.from(privateKeyHex, 'hex'));
+  const signature = '0x' + r.toString('hex') + s.toString('hex') + (27 + v).toString(16);
+
+  const payload = {
+    x402Version: 2,
+    payload: {
+      permit2Authorization: {
+        permitted: { token: requirements.asset, amount: String(requirements.amount) },
+        from: walletAddress,
+        spender,
+        nonce,
+        deadline,
+        witness: { to: payTo, validAfter },
+      },
+      signature,
+    },
+    accepted: requirements,
+  };
+
+  if (resource) {
+    payload.resource = { url: resource };
+  }
+
+  return Buffer.from(JSON.stringify(payload)).toString('base64');
+}
+
 /**
  * Check if a network string is an EVM network.
  */

package/src/x402.js

@@ -4,7 +4,7 @@
  * Supports EVM (EIP-3009 on Base) and Solana (SPL TransferChecked).
  */
 
-import { createEvmPaymentPayload, isEvmNetwork } from './x402-evm.js';
+import { createEvmPaymentPayload, isEvmNetwork, PERMIT2_ADDRESS } from './x402-evm.js';
 import {
   createSvmPaymentPayload,
   isSvmNetwork,
@@ -55,12 +55,63 @@ function rankRequirements(requirements) {
   return ranked;
 }
 
+// ERC-20 allowance(owner, spender) selector for the Permit2 preflight.
+const ALLOWANCE_SELECTOR = '0xdd62ed3e';
+
+/**
+ * Check whether `owner` has approved Permit2 to spend at least `amount` of
+ * `token`. Permit2-based payments are doomed without sufficient allowance
+ * (never approved, or a finite approval now below the payment amount), so
+ * skip those entries early instead of burning a failed verify round-trip.
+ * Returns true when the allowance is unknown (RPC failure) — let the server
+ * decide rather than block a possibly-valid payment.
+ */
+async function hasPermit2Allowance(network, token, owner, amount) {
+  const rpc = getEvmRpcUrl(network);
+  if (!rpc) return true;
+  try {
+    const ownerArg = owner.replace(/^0x/, '').toLowerCase().padStart(64, '0');
+    const spenderArg = PERMIT2_ADDRESS.replace(/^0x/, '').toLowerCase().padStart(64, '0');
+    const resp = await fetch(rpc, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0', id: 1,
+        method: 'eth_call',
+        params: [{ to: token, data: `${ALLOWANCE_SELECTOR}${ownerArg}${spenderArg}` }, 'latest'],
+      }),
+    });
+    const data = await resp.json();
+    if (typeof data.result !== 'string') return true;
+    return BigInt(data.result) >= BigInt(amount);
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Build a payment signature for a single requirement.
  * @returns {string|null} Base64 payment signature, or null on failure
  */
 async function buildPaymentForRequirement(requirement, exported, url) {
   if (isEvmNetwork(requirement.network)) {
+    if ((requirement.extra || {}).assetTransferMethod === 'permit2-exact') {
+      const approved = await hasPermit2Allowance(
+        requirement.network,
+        requirement.asset,
+        exported.evm.address,
+        requirement.amount,
+      );
+      if (!approved) {
+        console.error(
+          `[x402] Skipping ${requirement.network} permit2 option: Permit2 ` +
+          `(${PERMIT2_ADDRESS}) allowance for token ${requirement.asset} is ` +
+          `missing or below the payment amount (${requirement.amount}). ` +
+          `Send approve(${PERMIT2_ADDRESS}, <amount>) from the wallet to enable it.`,
+        );
+        return null;
+      }
+    }
     return createEvmPaymentPayload(
       requirement,
       exported.evm.privateKey,
@@ -132,7 +183,7 @@ export async function* createPaymentSignatures(response, url, options = {}) {
   for (const req of ranked) {
     try {
       const sig = await buildPaymentForRequirement(req, exported, url);
-      if (sig) yield { signature: sig, network: req.network };
+      if (sig) yield { signature: sig, network: req.network, asset: req.asset };
     } catch {
       // This payment option failed to build, try next
       continue;
@@ -156,11 +207,48 @@ export async function createPaymentSignature(response, url, options = {}) {
   return null;
 }
 
+/**
+ * x402 payment tokens per EVM network, matching the stablecoins the API
+ * advertises in 402 `accepts` entries. `decimals` matters: USDT on BNB Smart
+ * Chain uses 18 decimals, unlike the 6-decimal tokens on Base and X Layer.
+ */
+// RPC endpoint per supported x402 EVM network.
+export const EVM_X402_RPCS = {
+  'eip155:8453': CHAIN_RPCS.base,
+  'eip155:196': CHAIN_RPCS.xlayer,
+  'eip155:56': CHAIN_RPCS.bsc,
+};
+
+function getEvmRpcUrl(network) {
+  return EVM_X402_RPCS[network] || null;
+}
+
+// Known payment tokens per network, in the order servers typically advertise
+// them. A network can accept several stablecoins (BSC accepts four); `decimals`
+// is per token — every BSC stablecoin is an 18-decimal BEP-20 deployment,
+// unlike the 6-decimal tokens on Base and X Layer.
+export const EVM_X402_TOKENS = {
+  'eip155:8453': [
+    { token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', symbol: 'USDC', decimals: 6 }, // Base USDC
+  ],
+  'eip155:196': [
+    { token: '0x779Ded0c9e1022225f8E0630b35a9b54bE713736', symbol: 'USDT0', decimals: 6 }, // X Layer USDT0
+  ],
+  'eip155:56': [
+    { token: '0xcE24439F2D9C6a2289F741120FE202248B666666', symbol: 'U', decimals: 18 }, // United Stables
+    { token: '0x8d0d000ee44948fc98c9b98a4fa4921476f08b0d', symbol: 'USD1', decimals: 18 }, // World Liberty Financial USD
+    { token: '0x55d398326f99059fF775485246999027B3197955', symbol: 'USDT', decimals: 18 }, // Tether USD
+    { token: '0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d', symbol: 'USDC', decimals: 18 }, // Binance-Peg USD Coin
+  ],
+};
+
 /**
  * Check stablecoin balance for x402 payment wallet on the given network.
+ * Pass the token contract paid with (`asset`) to check that specific token;
+ * otherwise the network's first known token is checked.
  * Returns `{ balance, symbol }` (USD amount + token symbol) or null if check fails.
  */
-export async function checkX402Balance(network) {
+export async function checkX402Balance(network, asset = null) {
   try {
     const { listWallets, exportWallet: _exportWallet } = await import('./wallet.js');
     const wallets = listWallets();
@@ -192,13 +280,13 @@ export async function checkX402Balance(network) {
     }
 
     if (network.startsWith('eip155:')) {
-      // Per-network token + RPC. Both tokens are 6-decimals.
       // Default to Base USDC if the network is unknown so existing wallets keep working.
-      const EVM_NETWORKS = {
-        'eip155:8453': { token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', rpc: CHAIN_RPCS.base,   symbol: 'USDC'  }, // Base USDC
-        'eip155:196':  { token: '0x779Ded0c9e1022225f8E0630b35a9b54bE713736', rpc: CHAIN_RPCS.xlayer, symbol: 'USDT0' }, // X Layer USDT0
-      };
-      const { token, rpc, symbol } = EVM_NETWORKS[network] || EVM_NETWORKS['eip155:8453'];
+      const tokens = EVM_X402_TOKENS[network] || EVM_X402_TOKENS['eip155:8453'];
+      const entry = (asset
+        && tokens.find(t => t.token.toLowerCase() === asset.toLowerCase()))
+        || tokens[0];
+      const { token, symbol, decimals } = entry;
+      const rpc = getEvmRpcUrl(network) || EVM_X402_RPCS['eip155:8453'];
       const addr = walletInfo.evm.replace('0x', '').toLowerCase().padStart(64, '0');
       const resp = await fetch(rpc, {
         method: 'POST',
@@ -210,7 +298,7 @@ export async function checkX402Balance(network) {
         }),
       });
       const data = await resp.json();
-      return { balance: parseInt(data.result, 16) / 1e6, symbol };
+      return { balance: parseInt(data.result, 16) / 10 ** decimals, symbol };
     }
 
     return null;