nansen-cli 1.29.0 → 1.30.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.30.0
+
+### Minor Changes
+
+- [#422](https://github.com/nansen-ai/nansen-cli/pull/422) [`10da2f0`](https://github.com/nansen-ai/nansen-cli/commit/10da2f03284a501d94c433f543b9f1866005d3fc) Thanks [@gulshngill](https://github.com/gulshngill)! - Add x402 support for paying with USDT0 on X Layer alongside Base USDC and Solana SPL USDC. The CLI auto-signs the payment using whatever the API advertises in the 402 `accepts` list — no client-side allowlist, since `src/x402-evm.js` already reads `extra.name`, `extra.version`, and `asset` generically. New `NANSEN_XLAYER_RPC` env var overrides the default X Layer RPC, and `checkX402Balance()` now picks the right token + RPC based on the requirement's `network` field.
+
+### Patch Changes
+
+- [#422](https://github.com/nansen-ai/nansen-cli/pull/422) [`dc9d1c1`](https://github.com/nansen-ai/nansen-cli/commit/dc9d1c1d740128a8667e79a7a4afb3ff31ed1cc5) Thanks [@gulshngill](https://github.com/gulshngill)! - Document MPP (Tempo) as a third paid-access rail alongside API key and x402. Adds a `nansen-mpp-payment` skill, a README section explaining when to reach for the separate `tempo` CLI, and updates the no-API-key 402 error to mention tempo as a third option.
+
+- [#422](https://github.com/nansen-ai/nansen-cli/pull/422) [`93e6a6d`](https://github.com/nansen-ai/nansen-cli/commit/93e6a6d6655380d311739e5f814dda2876b0206a) Thanks [@gulshngill](https://github.com/gulshngill)! - Fix x402 low-balance warning to use the actual stablecoin symbol (USDC or USDT0) returned by `checkX402Balance()` instead of hardcoding "USDC".
+
+- [#422](https://github.com/nansen-ai/nansen-cli/pull/422) [`8f9397f`](https://github.com/nansen-ai/nansen-cli/commit/8f9397f2e1940a7a501cd450eae58a3b243b4782) Thanks [@gulshngill](https://github.com/gulshngill)! - Fix x402 payment header decoding and WalletConnect payment payload encoding to use UTF-8 instead of Latin-1. Previously the `Payment-Required` header was decoded with `atob()`, which corrupted multi-byte UTF-8 chars in fields like `extra.name = 'USD₮0'`. The corrupted name then signed the wrong EIP-712 domain and the server rejected with `invalid_exact_evm_signature`. X Layer USDT0 payments now sign correctly; Base USDC was unaffected because `'USD Coin'` is pure ASCII.
+
 ## 1.29.0
 
 ### Minor Changes

package/README.md

@@ -14,14 +14,20 @@ npx skills add nansen-ai/nansen-cli  # load agent skill files
 
 ## Auth
 
-```bash
-nansen login --api-key <key>   # save key to ~/.nansen/config.json
-nansen login --human           # interactive prompt
-export NANSEN_API_KEY=...      # env var (highest priority)
-nansen logout                  # remove saved key
-```
+Three options — pick whichever fits your setup:
+
+1. **API key** (subscription):
+   ```bash
+   nansen login --api-key <key>   # save key to ~/.nansen/config.json
+   nansen login --human           # interactive prompt
+   export NANSEN_API_KEY=...      # env var (highest priority)
+   nansen logout                  # remove saved key
+   ```
+   Get your API key at [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup).
 
-Get your API key at [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/agent-setup).
+2. **x402 micropayment** (no key needed): `nansen wallet create`, fund with USDC on Base or Solana, or USDT0 on X Layer, then call any endpoint — the CLI signs `Payment-Signature` headers automatically on 402 responses. See [Wallet](#wallet).
+
+3. **MPP via tempo** (no key needed): install the [tempo CLI](https://docs.tempo.xyz) separately, run `tempo wallet login` to set up, then call the Nansen API through `tempo request`. The Nansen API selects the MPP rail when it sees `Authorization: Payment ...`. See [MPP / Tempo](#mpp--tempo) below.
 
 ## Commands
 
@@ -76,6 +82,40 @@ nansen wallet send --wallet <name> --to <addr> --amount <n> --chain <chain>
 
 **Privy wallets** are server-side — no password, no local key storage. Requires `PRIVY_APP_ID` and `PRIVY_APP_SECRET` env vars. Get credentials at [dashboard.privy.io](https://dashboard.privy.io).
 
+## MPP / Tempo
+
+The Nansen API supports [MPP](https://mpp.dev/protocol) (Tempo's stablecoin payment rail) as an alternative to API keys and x402. MPP is handled by the **separate** [tempo CLI](https://docs.tempo.xyz) — `nansen-cli` itself does not sign MPP credentials. You use the two CLIs side-by-side.
+
+**One-time setup:**
+
+```bash
+# 1. Install the tempo CLI
+curl -fsSL https://tempo.xyz/install | bash
+# 2. Log in + fund the tempo wallet
+tempo wallet login
+tempo wallet fund     # follow the on-screen instructions to deposit USDC
+```
+
+**Calling the Nansen API via tempo:**
+
+```bash
+tempo request POST https://api.nansen.ai/api/v1/smart-money/netflow \
+  --json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
+```
+
+`tempo request` handles the full `Authorization: Payment` challenge/response: on a 402 with `WWW-Authenticate: Payment ...` it signs a Tempo credential, retries, and surfaces the `Payment-Receipt` header on success.
+
+**When to use which rail:**
+
+| Situation | Rail |
+|---|---|
+| You have a subscription | API key |
+| You want anonymous pay-per-call with a Base/Solana wallet you already manage | x402 (`nansen wallet`) |
+| You hold USDT0 on X Layer and want to pay from there | x402 (`nansen wallet`) |
+| You already use tempo for other paid APIs, or want micropayments without managing your own wallet keys | MPP (`tempo request`) |
+
+> Note: MPP is server-side opt-in (`MPP_ENABLED=true` on the API). It's available on dev today and rolling out to prod — if `tempo request` returns a non-MPP 402, fall back to x402 or an API key.
+
 ## Key Options
 
 | Option | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",

package/skills/nansen-mpp-payment/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: nansen-mpp-payment
+description: Pay-per-call access to the Nansen API via MPP (Tempo). Use when a user wants anonymous Nansen access without an API key and without managing their own Base/Solana wallet — they install the tempo CLI separately and call the API through `tempo request`.
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - tempo
+    install:
+      - kind: external
+        name: tempo
+        docs: https://docs.tempo.xyz
+allowed-tools: Bash(tempo:*), Bash(nansen:*)
+---
+
+# MPP / Tempo
+
+The Nansen API supports three paid-access rails: API key, x402 (handled by `nansen-cli`), and MPP via Tempo (handled by the **separate** [tempo CLI](https://docs.tempo.xyz)). This skill covers the third.
+
+`nansen-cli` does **not** sign MPP credentials. Use this skill when the user wants to call the Nansen API through `tempo request` because they already use tempo, want micropayments without managing wallet keys themselves, or don't want to fund a Base/Solana USDC wallet.
+
+For API-key auth, see `nansen-wallet-manager`. For x402 micropayment with a local wallet, see `nansen-trading` / `nansen-wallet-manager`.
+
+## When to use this skill
+
+- User says "MPP", "tempo", "Authorization: Payment", or "Payment-Receipt".
+- User has no Nansen API key and doesn't want to set up a Base/Solana wallet.
+- User is already paying for other APIs through tempo and wants Nansen on the same rail.
+
+## One-time setup
+
+```bash
+# 1. Install the tempo CLI
+curl -fsSL https://tempo.xyz/install | bash
+# 2. Log in (creates / unlocks the tempo wallet)
+tempo wallet login
+# 3. Fund it with USDC on the chain tempo selects for your environment
+tempo wallet fund
+# 4. Confirm the wallet is ready
+tempo wallet whoami
+```
+
+## Calling the Nansen API
+
+`tempo request` handles the full MPP challenge/response: it sends the request, signs the `Authorization: Payment` credential when the API responds 402 + `WWW-Authenticate: Payment ...`, retries, and exposes the `Payment-Receipt` header on success.
+
+```bash
+# Smart Money netflow
+tempo request POST https://api.nansen.ai/api/v1/smart-money/netflow \
+  --json '{"chains":["solana"],"pagination":{"page":1,"page_size":10}}'
+
+# TGM holders
+tempo request POST https://api.nansen.ai/api/v1/tgm/holders \
+  --json '{"token_address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","chain":"solana"}'
+```
+
+Endpoint paths and request shapes are the same as the rest of the Nansen API — run `nansen schema <command>` (no API key required) to look up the body shape, then call the matching `/api/v1/...` path through `tempo request`.
+
+## Discovering paid endpoints
+
+```bash
+curl https://api.nansen.ai/.well-known/x402
+```
+
+Returns `paymentProtocols: ["x402", "mpp"]` (when MPP is enabled server-side) and the list of paid resources.
+
+## How MPP differs from x402
+
+| | **x402** (nansen-cli native) | **MPP via tempo** (this skill) |
+|---|---|---|
+| Header sent on retry | `Payment-Signature: <base64>` | `Authorization: Payment <credential>` |
+| 402 challenge header | `Payment-Required: <base64>` | `WWW-Authenticate: Payment ...` |
+| Success header | _(none)_ | `Payment-Receipt: <base64>` |
+| Wallet | local, Privy, or WalletConnect — managed by `nansen-cli` | tempo-managed (separate CLI) |
+| Chains | Base USDC, Solana SPL USDC, X Layer USDT0 | Tempo's chain (mainnet `USDC` in prod, moderato `pathUSD` in dev) |
+| nansen-cli code path | `src/x402.js` auto-signs on 402 | not handled — call via `tempo request` directly |
+
+## Notes
+
+- MPP is server-side opt-in. If `tempo request` returns a 402 without `WWW-Authenticate: Payment`, MPP isn't enabled for that endpoint/environment — fall back to an API key or x402.
+- Don't try to add `--mpp-*` flags to `nansen-cli` — the supported integration is "use tempo separately". If the user asks for tighter integration, point them at this skill and confirm the requirement before adding code.
+- Per-request price is the same as x402 (1 credit ≈ $0.001 with 10x markup, e.g. 1-credit endpoints cost $0.01).
+
+## Source
+
+- npm: https://www.npmjs.com/package/nansen-cli
+- GitHub: https://github.com/nansen-ai/nansen-cli
+- MPP protocol: https://mpp.dev/protocol
+- Tempo docs: https://docs.tempo.xyz

package/src/api.js

@@ -498,9 +498,9 @@ export class NansenAPI {
     if (network) {
       try {
         const { checkX402Balance } = await import('./x402.js');
-        const balance = await checkX402Balance(network);
-        if (balance !== null && balance < 0.25) {
-          console.error(`[x402] Warning: USDC balance low ($${balance.toFixed(2)}). Fund your wallet to avoid interruptions.`);
+        const result = await checkX402Balance(network);
+        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.`);
         }
       } catch { /* balance check is best-effort */ }
     }
@@ -648,7 +648,7 @@ export class NansenAPI {
                 const paymentHeader = response.headers.get('payment-required');
                 if (paymentHeader) {
                   try {
-                    paymentRequirements = JSON.parse(atob(paymentHeader));
+                    paymentRequirements = JSON.parse(Buffer.from(paymentHeader, 'base64').toString('utf8'));
                   } catch {
                     data.paymentRequiredRaw = paymentHeader;
                   }
@@ -665,9 +665,10 @@ export class NansenAPI {
                     if (result !== null) return result;
                   } catch (x402Err) {
                     if (!this.apiKey) {
-                      message = 'No API key configured. Two ways to authenticate:\n' +
+                      message = 'No API key configured. Three ways to authenticate:\n' +
                         '  1. API key: nansen login --api-key <key> (get key at https://app.nansen.ai/auth/agent-setup)\n' +
-                        '  2. x402 micropayment: nansen wallet create + fund with USDC (no API key needed)';
+                        '  2. x402 micropayment: nansen wallet create + fund with USDC on Base/Solana or USDT0 on X Layer (no API key needed)\n' +
+                        '  3. MPP via tempo: install tempo CLI, run `tempo wallet login`, then call the API with `tempo request` (see skills/nansen-mpp-payment)';
                     } else {
                       message = `x402 auto-payment failed: ${x402Err.message}`;
                     }

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_XLAYER_RPC     Custom X Layer RPC
  *   NANSEN_SOLANA_RPC     Custom Solana RPC
  *
  * Backward-compat aliases (deprecated — prefer the forms above):
@@ -19,11 +20,13 @@
 
 const DEFAULT_EVM_RPC    = 'https://eth.public-rpc.com';
 const DEFAULT_BASE_RPC   = 'https://mainnet.base.org';
+const DEFAULT_XLAYER_RPC = 'https://rpc.xlayer.tech';
 const DEFAULT_SOLANA_RPC = 'https://api.mainnet-beta.solana.com';
 
 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,
+  xlayer:   process.env.NANSEN_XLAYER_RPC || DEFAULT_XLAYER_RPC,
   solana:   process.env.NANSEN_SOLANA_RPC || DEFAULT_SOLANA_RPC,
 };

package/src/walletconnect-x402.js

@@ -113,7 +113,7 @@ export function buildPaymentSignatureHeader({ signature, authorization, resource
       authorization,
     },
   };
-  return btoa(JSON.stringify(paymentPayload));
+  return Buffer.from(JSON.stringify(paymentPayload), 'utf8').toString('base64');
 }
 
 /**

package/src/x402.js

@@ -24,7 +24,9 @@ export function parsePaymentRequirements(response) {
   if (!header) return null;
 
   try {
-    const decoded = JSON.parse(atob(header));
+    // UTF-8 decode (not atob → Latin-1) — server sends UTF-8 bytes
+    // for fields like extra.name = 'USD₮0'.
+    const decoded = JSON.parse(Buffer.from(header, 'base64').toString('utf8'));
     // V2 format: { accepts: [...], ... }
     if (decoded.accepts && Array.isArray(decoded.accepts)) {
       return decoded.accepts;
@@ -155,8 +157,8 @@ export async function createPaymentSignature(response, url, options = {}) {
 }
 
 /**
- * Check USDC balance for x402 payment wallet.
- * Returns balance in USD (number) or null if check fails.
+ * Check stablecoin balance for x402 payment wallet on the given network.
+ * Returns `{ balance, symbol }` (USD amount + token symbol) or null if check fails.
  */
 export async function checkX402Balance(network) {
   try {
@@ -183,25 +185,32 @@ export async function checkX402Balance(network) {
       });
       const data = await resp.json();
       const accounts = data.result?.value || [];
-      if (accounts.length === 0) return 0;
-      return parseFloat(accounts[0].account.data.parsed.info.tokenAmount.uiAmountString || '0');
+      const balance = accounts.length === 0
+        ? 0
+        : parseFloat(accounts[0].account.data.parsed.info.tokenAmount.uiAmountString || '0');
+      return { balance, symbol: 'USDC' };
     }
 
     if (network.startsWith('eip155:')) {
-      // Base USDC balance check — RPC URL from shared registry so NANSEN_BASE_RPC override applies
-      const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+      // 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 addr = walletInfo.evm.replace('0x', '').toLowerCase().padStart(64, '0');
-      const resp = await fetch(CHAIN_RPCS.base, {
+      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: USDC_BASE, data: `0x70a08231${addr}` }, 'latest'],
+          params: [{ to: token, data: `0x70a08231${addr}` }, 'latest'],
         }),
       });
       const data = await resp.json();
-      return parseInt(data.result, 16) / 1e6;
+      return { balance: parseInt(data.result, 16) / 1e6, symbol };
     }
 
     return null;