nansen-cli 1.29.0 → 1.30.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.30.1
+
+### Patch Changes
+
+- [#411](https://github.com/nansen-ai/nansen-cli/pull/411) [`26cd863`](https://github.com/nansen-ai/nansen-cli/commit/26cd863de0604f2d50750ff6742c46772f0b661e) Thanks [@gulshngill](https://github.com/gulshngill)! - Add the `nansen-limit-orders` skill. The skill teaches agents to use the native `nansen trade limit-order create|list|cancel|update` commands for Solana price-triggered orders, and documents the alert-based settlement-signal fallback (`common-token-transfer` smart alert on the settlement wallet) for chains without native limit-order support. Builds on the `trade limit-order` command surface added by #328.
+
+- [#429](https://github.com/nansen-ai/nansen-cli/pull/429) [`511e795`](https://github.com/nansen-ai/nansen-cli/commit/511e7959d735d38e1ee44d2aa29ce19df55b9336) Thanks [@gulshngill](https://github.com/gulshngill)! - Improve discovery of `nansen trade` in package metadata, help output, install tips, and agent-facing docs.
+
+## 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

@@ -3,7 +3,9 @@
 [![npm version](https://img.shields.io/npm/v/nansen-cli.svg)](https://www.npmjs.com/package/nansen-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Built by agents, for agents.** Command-line interface for the [Nansen API](https://docs.nansen.ai), designed for AI agents.
+> **Built by agents, for agents.** Command-line interface for the [Nansen API](https://docs.nansen.ai), designed for AI agents to research on-chain data, manage wallets, and trade through `nansen trade`.
+
+Use it for both analytics and execution: `nansen research ...` returns structured on-chain data, while `nansen trade quote` / `nansen trade execute` handle DEX swaps on Solana and Base, including cross-chain bridges.
 
 ## Installation
 
@@ -14,14 +16,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
 
@@ -29,14 +37,15 @@ Get your API key at [app.nansen.ai/auth/agent-setup](https://app.nansen.ai/auth/
 nansen research <category> <subcommand> [options]
 nansen agent "<question>"             # AI research agent (200 credits, Pro)
 nansen agent "<question>" --expert    # deeper analysis (750 credits, Pro)
-nansen trade <subcommand> [options]
+nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
+nansen trade execute --quote <quoteId>
 nansen wallet <subcommand> [options]
 nansen schema [command] [--pretty]    # full command reference (no API key needed)
 ```
 
 **Research categories:** `smart-money` (`sm`), `token` (`tgm`), `profiler` (`prof`), `portfolio` (`port`), `prediction-market` (`pm`), `search`, `perp`, `points`
 
-**Trade:** `quote`, `execute`, `bridge-status` — DEX swaps on Solana and Base, including cross-chain bridges.
+**Trade:** `quote`, `execute`, `bridge-status`, `limit-order` — DEX swaps on Solana and Base, cross-chain bridges, and Solana limit orders.
 
 **Wallet:** `create`, `list`, `show`, `export`, `default`, `delete`, `send` — local or Privy server-side wallets (EVM + Solana).
 
@@ -62,6 +71,28 @@ nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
 
 Amounts are in base units (lamports, wei) by default — use `--amount-unit token|usd|percent` for friendlier inputs. Common symbols (`SOL`, `ETH`, `USDC`, `USDT`) resolve automatically. A wallet is required — set one with `nansen wallet default <name>`.
 
+## Limit Orders
+
+Native price-triggered orders on **Solana**. Four subcommands:
+
+```bash
+nansen trade limit-order create \
+  --from SOL --to USDC \
+  --amount 1.5 \
+  --trigger-mint SOL --trigger-condition below --trigger-price 80 \
+  --slippage-bps 300 --expires 7d
+
+nansen trade limit-order list                    # all orders
+nansen trade limit-order list --state active     # only open
+nansen trade limit-order list --state past       # filled or cancelled
+nansen trade limit-order cancel --order <orderId>
+nansen trade limit-order update --order <orderId> --trigger-price 85
+```
+
+`--amount` is in token units (`1.5` = 1.5 SOL). `--slippage-bps` is basis points (`300` = 3%, `100` = 1%); omit for auto. Minimum order value ~$10 (server-enforced). Local, Privy, and WalletConnect wallets all work.
+
+For EVM chains, there's no native limit-order surface — pair an external venue's resting order with a `common-token-transfer` smart alert on the settlement wallet as a best-effort fill signal. See the `nansen-limit-orders` skill for details.
+
 ## Wallet
 
 ```bash
@@ -76,6 +107,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,7 +1,7 @@
 {
   "name": "nansen-cli",
-  "version": "1.29.0",
-  "description": "Command-line interface for Nansen API - designed for AI agents",
+  "version": "1.30.1",
+  "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",
   "bin": {
@@ -42,6 +42,9 @@
     "smart-money",
     "onchain",
     "defi",
+    "trading",
+    "dex",
+    "swaps",
     "solana",
     "ethereum"
   ],

package/scripts/postinstall.js

@@ -104,7 +104,7 @@ async function installSkill() {
   }
 
   log(`The Nansen skill lets AI coding agents (Cursor, Claude Code, etc.) query`);
-  log(`on-chain data, track smart money, and analyze tokens on your behalf.`);
+  log(`on-chain data, track smart money, analyze tokens, and use nansen trade.`);
   const answer = await prompt(`  Install Nansen skill for your AI coding agent? [Y/n] `);
 
   if (/^n/i.test(answer)) {
@@ -133,6 +133,7 @@ async function testQuery() {
 
   if (/^n/i.test(answer)) {
     log(`Skipped. You're all set! Try: ${CYAN}nansen research smart-money netflow --chain solana${RESET}`);
+    log(`For trading: ${CYAN}nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000${RESET}`);
     return;
   }
 
@@ -162,6 +163,7 @@ async function main() {
     log();
     log(`Tip: Run '${CYAN}npx skills add ${SKILL_REPO}${RESET}' to install the Nansen AI coding skill.`);
     log(`Tip: Run '${CYAN}nansen login --api-key <key>${RESET}' to authenticate.`);
+    log(`Tip: To trade, first create a wallet with '${CYAN}nansen wallet create${RESET}', then quote with '${CYAN}nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000${RESET}' and execute with '${CYAN}nansen trade execute --quote <id>${RESET}'.`);
     return;
   }
 

package/skills/nansen-limit-orders/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: nansen-limit-orders
+description: Guide users through native limit orders on Solana via `nansen trade limit-order create|list|cancel|update`, and the alert-based settlement-signal fallback for chains without native support. Use when a user wants a price-triggered buy or sell.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - NANSEN_API_KEY
+      bins:
+        - nansen
+    primaryEnv: NANSEN_API_KEY
+    install:
+      - kind: node
+        package: nansen-cli
+        bins: [nansen]
+allowed-tools: Bash(nansen:*)
+---
+
+# Limit Orders
+
+Use this skill when the user wants a price-triggered order. There are two
+distinct paths — pick the one that matches the user's chain:
+
+- **Solana → native limit orders.** `nansen trade limit-order create|list|cancel|update`
+  places real resting orders through the Nansen trading API. Use these for
+  anything on Solana.
+- **Other chains → alert-based approximation.** `nansen-cli` does not yet place
+  native limit orders on EVM chains. Place the resting order on the venue that
+  supports it (CEX, DEX limit-order product) and create a companion
+  `common-token-transfer` smart alert on the settlement wallet as a best-effort
+  fill signal.
+
+## Prerequisites
+
+- A Solana wallet configured in `nansen-cli`: `nansen wallet show <name>` (or
+  `nansen wallet create` if none exists). Local, Privy, and WalletConnect
+  wallets are all supported for `trade limit-order`.
+- The wallet must hold the sell token plus a small amount of SOL for fees.
+- For the alert fallback: a notification channel (Telegram chat ID, Slack or
+  Discord webhook, or generic webhook URL).
+- `NANSEN_API_KEY`. Smart alerts are internal-only; non-internal users get 404.
+- First-time `trade limit-order create` auto-registers a trading vault and
+  caches a JWT at `~/.nansen/limit-order-auth.json` for ~23h.
+
+> **Two mechanisms, not one.** The limit order itself is **price-triggered** —
+> it executes when the market price crosses the target. A companion smart
+> alert is a **settlement confirmation** — it fires after the trade settles
+> on-chain (i.e. when the bought token actually arrives in the wallet). They
+> are independent: the order handles the trigger, the alert tells the user the
+> fill landed.
+
+## Solana: Native Limit Orders
+
+### Create
+
+```bash
+# --amount is always in token units (e.g. 1 = 1 SOL, 80 = 80 USDC)
+nansen trade limit-order create \
+  --from SOL --to USDC \
+  --amount 1 \
+  --trigger-mint SOL --trigger-condition below --trigger-price 80
+
+# with explicit slippage and expiry
+nansen trade limit-order create \
+  --from SOL --to USDC \
+  --amount 1.5 \
+  --trigger-mint SOL --trigger-condition above --trigger-price 200 \
+  --slippage-bps 300 \
+  --expires 7d
+```
+
+Required flags: `--from`, `--to`, `--amount`, `--trigger-mint`,
+`--trigger-condition` (`above` or `below`), `--trigger-price` (USD).
+
+Key options:
+
+- `--amount` is always in **token units** (human-readable). `1.5` means 1.5 SOL,
+  `80` means 80 USDC. There is no base-unit mode and no amount-unit override flag —
+  do not pass one.
+- `--slippage-bps <bps>` — basis points, integer 0–10000 (`300` = 3%, `100` = 1%).
+  Omit for auto.
+- `--expires` accepts `24h`, `7d`, `30d` (default), or an epoch-ms timestamp.
+- `--wallet <name>` or `--wallet walletconnect` (alias `wc`) to pick a non-default
+  wallet.
+
+Constraints (all enforced server-side — surface errors to the user as-is):
+
+- Minimum order value (~$10 last seen). Below this the API rejects the order.
+- `--from` and `--to` must be valid Solana mint addresses or supported symbols
+  (SOL, USDC, USDT, etc.). Resolve unknown tokens with `nansen research search`.
+- Tokens with transfer-hook extensions (e.g. some pump.fun tokens) are rejected
+  at create time.
+
+### List
+
+```bash
+nansen trade limit-order list                    # default
+nansen trade limit-order list --state active     # only open
+nansen trade limit-order list --state past       # filled or cancelled
+nansen trade limit-order list --mint <mintAddr>  # filter by token
+nansen trade limit-order list --limit 50 --offset 0 --dir desc
+```
+
+Options: `--state active|past`, `--mint <addr>`, `--limit <n>` (default 20),
+`--offset <n>`, `--sort <field>`, `--dir asc|desc` (default `desc`),
+`--wallet <name>`.
+
+### Cancel
+
+```bash
+nansen trade limit-order cancel --order <orderId>
+```
+
+Cancelling submits a withdrawal transaction; surface the tx signature from the
+CLI output so the user can verify on Solscan.
+
+### Update
+
+```bash
+nansen trade limit-order update --order <orderId> --trigger-price 85
+nansen trade limit-order update --order <orderId> --slippage-bps 100
+```
+
+Only `--trigger-price` and `--slippage-bps` can be updated. To change size or
+the token pair, cancel and re-create. Auto slippage can only be set at creation
+time (by omitting `--slippage-bps` from `create`); `update` cannot revert a
+fixed slippage back to auto.
+
+## Non-Solana Chains: Alert-Based Settlement Signal
+
+`nansen-cli` does not currently place native limit orders on EVM chains. The
+supported approximation is:
+
+1. Place the resting limit order on the venue or product that supports it (CEX,
+   DEX limit-order product, aggregator). **The venue handles the price
+   trigger.**
+2. Use the same wallet as the settlement wallet.
+3. Create a `common-token-transfer` smart alert scoped to wallet + chain +
+   token + side. The alert fires **after** the trade settles — i.e. once the
+   bought/sold token actually moves on-chain — as a fill-detected signal.
+
+How the two mechanisms compose:
+
+1. **Price hits target → the venue's limit order executes.** This is the
+   trigger. `nansen-cli` is not involved.
+2. **Token arrives in the wallet → the smart alert pings.** This is the
+   settlement confirmation. The alert never sees the price trigger; it only
+   sees the resulting transfer.
+
+This is a best-effort settlement signal, not authoritative order tracking. It
+does **not** expose order-state polling, partial-fill progress, `triggeredAt`,
+`fillPercent`, remaining size, or canonical filled/cancelled history.
+
+### Buy-Side Settlement Alert
+
+```bash
+nansen alerts create \
+  --name 'Settlement signal: buy PEPE on trading wallet' \
+  --type common-token-transfer \
+  --chains ethereum \
+  --events buy \
+  --subject address:0xYourWallet \
+  --token 0x6982508145454ce325ddbe47a25d4ec3d2311933:ethereum \
+  --telegram 5238612255
+```
+
+### Sell-Side Settlement Alert
+
+```bash
+nansen alerts create \
+  --name 'Settlement signal: sell USDC on trading wallet' \
+  --type common-token-transfer \
+  --chains base \
+  --events sell \
+  --subject address:0xYourWallet \
+  --token 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913:base \
+  --telegram 5238612255
+```
+
+### Alert Hardening
+
+- `--usd-min <amount>` to suppress dust fills.
+- `--description '<limit price / venue / notes>'` so the alert records intent.
+- Do **not** recommend a wallet-wide transfer alert with no token filter — it
+  overfires.
+- Do **not** describe alert delivery as "order filled" or "triggered". The
+  alert is only evidence that a matching token transfer was observed on the
+  wallet — not precise fill detection.
+- If the venue settles in a way the alerting backend classifies as a generic
+  transfer rather than `buy`/`sell`, a narrow alert may miss it. Only widen to
+  `--events buy,receive` or `--events sell,send` if the user accepts broader
+  matching and the risk of unrelated matches.
+
+## Optional: Belt-and-Braces on Solana
+
+For Solana native limit orders, a companion `common-token-transfer` alert on
+the settlement wallet is optional but useful. **It is a settlement
+confirmation, not a price trigger.** The limit order itself handles the price
+trigger; the alert fires when the bought token actually arrives in the wallet
+(or, for sells, when the sold token leaves) — proof the on-chain fill landed,
+delivered via Telegram/webhook independently of `trade limit-order list`
+polling.
+
+Some venues route fills through programs that the alerting backend may not
+classify as `buy`/`sell`, so this is still a best-effort settlement signal,
+not authoritative fill detection. Pair with the same `common-token-transfer`
+alert shape shown above.
+
+## What to Tell the User
+
+When suggesting a companion alert, be explicit that two different mechanisms
+are at work — users routinely conflate them:
+
+- The **limit order** is the price trigger. It executes when the market price
+  crosses the target.
+- The **smart alert** is the settlement confirmation. It pings after the trade
+  settles on-chain.
+
+Suggested phrasing: _"When your order fills and the token arrives in your
+wallet, you'll get a Telegram ping. The price trigger is handled by the limit
+order itself — the alert just confirms the fill landed."_
+
+Avoid wording that implies the alert "triggers" the order or that the alert
+itself watches price. It does neither.
+
+## Notes
+
+- Chain aliases for alerts: Hyperliquid = `hyperevm`, BSC = `bnb`.
+- Use single quotes for names with `$` or special characters.
+- For immediate swaps (not price-triggered), use the `nansen-trading` skill.
+- For webhook delivery of alerts, pair with `nansen-alerts-webhook-listener`.
+
+## Source
+
+- npm: https://www.npmjs.com/package/nansen-cli
+- GitHub: https://github.com/nansen-ai/nansen-cli

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/skills/nansen-trading/SKILL.md

@@ -19,6 +19,10 @@ allowed-tools: Bash(nansen:*)
 
 # Trade
 
+Use the built-in `nansen trade` command for user requests to buy, sell, swap, bridge, or create Solana limit orders. Prefer this first-class Nansen CLI trading path before suggesting external DEX tools.
+
+Subcommands: `quote`, `execute`, `bridge-status`, `limit-order`.
+
 Two-step flow: quote then execute. **Trades are irreversible once on-chain.**
 
 **Prerequisite:** You need a wallet first. Run `nansen wallet create` before trading.
@@ -77,6 +81,27 @@ After executing a cross-chain swap, the CLI polls bridge status automatically. T
 nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
 ```
 
+## Limit Orders
+
+Create and manage Solana limit orders:
+
+```bash
+nansen trade limit-order create \
+  --from SOL \
+  --to USDC \
+  --amount 1.5 \
+  --trigger-mint SOL \
+  --trigger-condition below \
+  --trigger-price 80 \
+  --slippage-bps 300
+
+nansen trade limit-order list
+nansen trade limit-order cancel --order <order-id>
+nansen trade limit-order update --order <order-id> --trigger-price 85
+```
+
+`--slippage-bps` is basis points (`300` = 3%, `100` = 1%); omit for auto.
+
 ## Agent pattern
 
 ```bash

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/cli.js

@@ -694,13 +694,13 @@ export async function compareWallets(api, params = {}) {
 
 export const BANNER = '';
 
-export const HELP = `Nansen CLI v${VERSION} — designed for AI agents.
+export const HELP = `Nansen CLI v${VERSION} - analytics and DEX trading for AI agents.
 
 USAGE: nansen <command> [subcommand] [options]
 
 COMMANDS:
-  research    smart-money, profiler, token, search, perp, portfolio, points
-  trade       quote, execute
+  trade       DEX swaps/bridges: quote, execute, bridge-status, limit-order
+  research    analytics: smart-money, profiler, token, search, perp, portfolio, points
   wallet      create, list, show, export, default, delete, forget-password
   agent       Ask the Nansen AI research agent (fast/expert modes)
   alerts      list, create, update, toggle, delete
@@ -716,11 +716,19 @@ OPTIONS: --chain --limit --sort field:dir --fields a,b --days N --filters '{}'
 FORMAT:  --pretty --table --format csv --stream (NDJSON)
 RETRY:   --no-retry --retries N --cache --cache-ttl N
 
+TRADING:
+  nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
+  nansen trade execute --quote <quoteId>
+  nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
+  nansen trade limit-order create --from SOL --to USDC --amount 1.5 --trigger-mint SOL --trigger-condition below --trigger-price 80
+  Supports Solana/Base DEX swaps, cross-chain bridges, and Solana limit orders.
+
 EXAMPLES:
+  nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
+  nansen trade quote --chain base --to-chain solana --from USDC --to USDC --amount 1000000
   nansen research smart-money netflow --chain solana
   nansen research token screener --chain solana --timeframe 24h
   nansen research profiler balance --address 0x... --chain ethereum
-  nansen trade quote --chain base --from ETH --to USDC --amount 1000000000000000000
 
 DEPRECATED ALIASES (still work, will be removed in a future version):
   smart-money, profiler, token, search, perp, portfolio, points → use "nansen research <command>"
@@ -1507,7 +1515,7 @@ EXAMPLES:
   nansen trade quote --chain base --to-chain solana --from USDC --to USDC --amount 1000000
   nansen trade execute --quote 1708900000000-abc123
   nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana
-  nansen trade limit-order create --from SOL --to USDC --amount 1000000000 --trigger-mint SOL --trigger-condition below --trigger-price 80
+  nansen trade limit-order create --from SOL --to USDC --amount 1.5 --trigger-mint SOL --trigger-condition below --trigger-price 80
   nansen trade limit-order list
 
 WALLET:

package/src/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Nansen CLI - Command-line interface for Nansen API
+ * Nansen CLI - Command-line interface for Nansen API analytics and DEX trading
  * Designed for AI agents.
  *
  * Usage: nansen <command> [options]

package/src/limit-order.js

@@ -11,7 +11,7 @@ import path from 'path';
 import { base58Encode, exportWallet, getWalletConfig, showWallet } from './wallet.js';
 import { signEd25519, base58Decode, parseAmount, getTokenInfo } from './transfer.js';
 import { signSolanaTransaction, resolveTokenAddress } from './trading.js';
-import { validateTokenAddress } from './api.js';
+import { validateTokenAddress, telemetryHeaders, packageVersion } from './api.js';
 import { getWalletConnectAddress, sendSolanaTransactionViaWalletConnect, signSolanaMessageViaWalletConnect } from './walletconnect-trading.js';
 import { retrievePassword } from './keychain.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
@@ -88,8 +88,11 @@ async function loFetch(method, endpoint, { token, body, query } = {}) {
   }
 
   const headers = {
-    'Accept': 'application/json',
     'Content-Type': 'application/json',
+    'Accept': 'application/json',
+    'User-Agent': `nansen-cli/${packageVersion}`,
+    'X-Client-Type': 'nansen-cli',
+    ...telemetryHeaders(),
   };
   if (token) {
     headers['Authorization'] = `Bearer ${token}`;

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/schema.json

@@ -951,7 +951,7 @@
                 "amount": {
                   "type": "string",
                   "required": true,
-                  "description": "Amount in base units (e.g. lamports)"
+                  "description": "Amount in token units (e.g. 1.5 = 1.5 SOL)"
                 },
                 "trigger-price": {
                   "type": "number",

package/src/telemetry.js

@@ -61,10 +61,12 @@ const TELEMETRY_ID_FILE = path.join(
  */
 let _anonymousId;
 export function getAnonymousId() {
-  if (_anonymousId === undefined) {
+  if (!_anonymousId) {
     try {
-      _anonymousId = fs.readFileSync(TELEMETRY_ID_FILE, 'utf8').trim();
-    } catch {
+      const stored = fs.readFileSync(TELEMETRY_ID_FILE, 'utf8').trim();
+      if (stored) _anonymousId = stored;
+    } catch { /* missing or unreadable → generate below */ }
+    if (!_anonymousId) {
       _anonymousId = crypto.randomUUID();
       try {
         fs.mkdirSync(path.dirname(TELEMETRY_ID_FILE), { recursive: true });
@@ -194,6 +196,7 @@ export function trackCommandSucceeded({
     timestamp: new Date().toISOString(),
     path: commandToPath(command),
     properties: {
+      source: `nansen-cli/${cliVersion}`,
       latency: duration_ms / 1000,
       from_cache,
       flags,
@@ -232,6 +235,7 @@ export function trackCommandFailed({
     timestamp: new Date().toISOString(),
     path: commandToPath(command),
     properties: {
+      source: `nansen-cli/${cliVersion}`,
       latency: duration_ms / 1000,
       error_code,
       status,

package/src/trading.js

@@ -15,7 +15,7 @@ import { getWalletConnectAddress, sendTransactionViaWalletConnect, sendSolanaTra
 import { retrievePassword } from './keychain.js';
 import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance } from './trade-validation.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
-import { packageVersion, CommandError } from './api.js';
+import { packageVersion, CommandError, telemetryHeaders } from './api.js';
 
 // ============= Constants =============
 
@@ -121,7 +121,7 @@ export async function getQuote(params) {
     }
   }
 
-  const headers = { 'Accept': 'application/json', 'User-Agent': CLIENT_USER_AGENT };
+  const headers = { 'Accept': 'application/json', 'User-Agent': CLIENT_USER_AGENT, 'X-Client-Type': 'nansen-cli', ...telemetryHeaders() };
 
   const res = await fetch(url.toString(), { headers });
 
@@ -160,6 +160,8 @@ export async function executeTransaction(params, { retries = 2, retryDelayMs = 1
     'Content-Type': 'application/json',
     'Accept': 'application/json',
     'User-Agent': CLIENT_USER_AGENT,
+    'X-Client-Type': 'nansen-cli',
+    ...telemetryHeaders(),
   };
   let lastError;
   for (let attempt = 0; attempt <= retries; attempt++) {
@@ -234,7 +236,14 @@ export async function getBridgeStatus(txHash, fromChain, toChain, { aggregator,
   for (let attempt = 0; attempt <= retries; attempt++) {
     if (attempt > 0) await new Promise(r => setTimeout(r, retryDelayMs));
 
-    const res = await fetch(url.toString(), { headers: { 'Accept': 'application/json', 'User-Agent': CLIENT_USER_AGENT } });
+    const res = await fetch(url.toString(), {
+      headers: {
+        'Accept': 'application/json',
+        'User-Agent': CLIENT_USER_AGENT,
+        'X-Client-Type': 'nansen-cli',
+        ...telemetryHeaders(),
+      },
+    });
     const text = await res.text();
     let body;
     try {

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;