nansen-cli 1.26.1 → 1.27.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.27.0
+
+### Minor Changes
+
+- [#403](https://github.com/nansen-ai/nansen-cli/pull/403) [`fe53dbe`](https://github.com/nansen-ai/nansen-cli/commit/fe53dbe8cf743b970e145e7ad7a00470f16f28df) Thanks [@marius-reed](https://github.com/marius-reed)! - Add prediction market filtering (order_by, volume/liquidity/OI/trader/price/date filters, neg_risk, tags) and address-summary endpoint
+
+### Patch Changes
+
+- [#402](https://github.com/nansen-ai/nansen-cli/pull/402) [`cfd94ce`](https://github.com/nansen-ai/nansen-cli/commit/cfd94ce1e1880e36fb0c97d0ecfe37e614898006) Thanks [@TimNooren](https://github.com/TimNooren)! - Enforce USDC or native token on one side of every swap
+
 ## 1.26.1
 
 ### Patch Changes

package/package.json

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

package/skills/nansen-alerts-webhook-listener/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: nansen-alerts-webhook-listener
+description: Set up a local webhook server to receive Nansen smart alerts in real-time with HMAC signature verification and public tunneling. Use when a user wants to listen for alerts on their local machine.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - NANSEN_API_KEY
+      bins:
+        - nansen
+        - node
+    primaryEnv: NANSEN_API_KEY
+    install:
+      - kind: node
+        package: nansen-cli
+        bins: [nansen]
+allowed-tools: Bash(nansen:*), Bash(node:*), Bash(npx:*), Bash(ngrok:*), Write
+---
+
+# Alert Webhook Listener
+
+Set up a local HTTP server to receive Nansen smart alert webhook payloads in real-time.
+
+## How It Works
+
+Nansen smart alerts support a **webhook** channel type. When an alert fires, Nansen sends an HTTP POST with a JSON payload to your webhook URL. This skill sets up:
+
+1. A local HTTP server (Node.js, zero external dependencies) that receives and displays alert payloads
+2. HMAC-SHA256 signature verification so only authentic Nansen payloads are accepted
+3. A public tunnel so Nansen's servers can reach your local machine
+
+**This skill does NOT create or modify alerts.** It sets up the listener infrastructure and then provides a summary of what the user needs to do to start receiving alerts.
+
+**OpenClaw users:** If OpenClaw is running locally on the same machine, the webhook server can forward verified alert payloads to OpenClaw's Gateway (`/hooks/agent`), triggering an agent turn for each alert. Set the `OPENCLAW_GATEWAY_URL` env var to enable this. See the **OpenClaw Integration** section below.
+
+## Security Warning
+
+**Before proceeding, inform the user:**
+
+> This skill starts an HTTP server on your machine and exposes it to the internet via a tunnel (ngrok or localtunnel). While the server only binds to localhost (`127.0.0.1`) — meaning no one on your local network can access it directly — the tunnel creates a public URL that **anyone on the internet** can send requests to.
+>
+> **Mitigations in place:**
+> - HMAC-SHA256 signature verification rejects all requests not signed by Nansen
+> - 1 MB body size limit prevents memory abuse
+> - Only `POST /webhook` and `GET /health` are accepted; everything else returns 404
+>
+> **You should be aware that:**
+> - The tunnel URL is publicly discoverable (ngrok URLs can be enumerated)
+> - Unsigned requests still reach your machine — they're rejected, but the connection is made
+> - Stop the tunnel when you're done to close the public endpoint
+
+Wait for the user to confirm they want to proceed before continuing.
+
+## Execution Plan
+
+Follow these steps **in order**. Do not skip signature verification — it is mandatory.
+
+### Step 0: Choose a tunnel provider
+
+Before starting, ask the user which tunnel provider they want to use:
+
+| | **ngrok** (recommended) | **localtunnel** |
+|---|---|---|
+| Stability | Stable — persistent connections with keepalive | Flaky — free relay drops idle connections without warning, tunnels die randomly |
+| Install | `brew install ngrok` + free account at ngrok.com | Zero install (`npx localtunnel`) |
+| HTTPS | Yes | Yes |
+| Auth required | Yes (free authtoken from ngrok.com) | No |
+
+**Recommend ngrok.** localtunnel is convenient but unreliable — in testing, tunnels silently exit after minutes, causing alerts to fail with "503 Tunnel Unavailable". ngrok maintains stable connections.
+
+Check if ngrok is available:
+```bash
+which ngrok && ngrok version
+```
+
+If not installed, tell the user:
+1. `brew install ngrok` (or download from ngrok.com)
+2. Create a free account at ngrok.com and copy the authtoken
+3. `ngrok config add-authtoken <token>`
+
+If the user prefers localtunnel or can't install ngrok, proceed with localtunnel but warn them that the tunnel may drop and they'll need to restart it and update their alert's webhook URL.
+
+### Step 1: Generate a webhook secret
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+Store the output — you need it for both the server and the alert configuration. **Never log or echo the secret after this point.**
+
+### Step 2: Write the webhook receiver script
+
+Create `nansen-webhook-server.mjs` in the current working directory. Use **only** Node.js built-in modules (`node:http`, `node:crypto`). No `npm install` required.
+
+**Requirements — do not deviate:**
+
+| Requirement | Detail |
+|---|---|
+| Bind address | `127.0.0.1` only — **never** `0.0.0.0` |
+| Default port | `9477` (override via `PORT` env var) |
+| Webhook path | `POST /webhook` — reject all other method/path combos with 404 |
+| Health check | `GET /health` → 200 `{"status":"ok"}` |
+| Signature verification | Verify `x-nansen-signature` header using HMAC-SHA256 with timing-safe comparison. Reject 401 on mismatch. |
+| Secret validation | Exit on startup if `WEBHOOK_SECRET` env var is missing or < 16 chars |
+| Payload logging | Pretty-print valid JSON payloads to stdout with ISO timestamp |
+| Request size limit | Reject bodies > 1 MB (413) to prevent memory abuse |
+| Graceful shutdown | Handle `SIGINT` and `SIGTERM` — close server, then exit |
+| OpenClaw forwarding | If `OPENCLAW_GATEWAY_URL` env var is set, forward verified payloads to `<url>/hooks/agent` via POST. Include `OPENCLAW_AUTH_TOKEN` as Bearer token if set. Log forward success/failure. |
+| No dependencies | Only `node:http`, `node:https`, and `node:crypto` — nothing from npm |
+
+**Signature verification — use timing-safe comparison:**
+
+```javascript
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+function verifySignature(rawBody, signatureHeader, secret) {
+  if (!signatureHeader || !secret) return false;
+  // Nansen sends "sha256=<hex>" — strip the prefix before comparing
+  const sig = signatureHeader.startsWith('sha256=') ? signatureHeader.slice(7) : signatureHeader;
+  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
+  try {
+    return timingSafeEqual(Buffer.from(sig, 'utf8'), Buffer.from(expected, 'utf8'));
+  } catch {
+    return false; // length mismatch
+  }
+}
+```
+
+**Full server template:**
+
+```javascript
+import { createServer } from 'node:http';
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+const PORT = parseInt(process.env.PORT || '9477', 10);
+const SECRET = process.env.WEBHOOK_SECRET;
+const MAX_BODY = 1_048_576; // 1 MB
+
+// Optional: forward verified payloads to a local OpenClaw Gateway
+const OPENCLAW_URL = process.env.OPENCLAW_GATEWAY_URL; // e.g. http://localhost:3000
+const OPENCLAW_TOKEN = process.env.OPENCLAW_AUTH_TOKEN;
+
+if (!SECRET || SECRET.length < 16) {
+  console.error('WEBHOOK_SECRET env var required (minimum 16 characters).');
+  console.error('Generate one: node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))"');
+  process.exit(1);
+}
+
+function verifySignature(rawBody, signatureHeader) {
+  if (!signatureHeader) return false;
+  // Nansen sends "sha256=<hex>" — strip the prefix before comparing
+  const sig = signatureHeader.startsWith('sha256=') ? signatureHeader.slice(7) : signatureHeader;
+  const expected = createHmac('sha256', SECRET).update(rawBody).digest('hex');
+  try {
+    return timingSafeEqual(Buffer.from(sig, 'utf8'), Buffer.from(expected, 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+async function forwardToOpenClaw(payload) {
+  if (!OPENCLAW_URL) return;
+  const url = `${OPENCLAW_URL.replace(/\/+$/, '')}/hooks/agent`;
+  const headers = { 'Content-Type': 'application/json' };
+  if (OPENCLAW_TOKEN) headers['Authorization'] = `Bearer ${OPENCLAW_TOKEN}`;
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(payload),
+    });
+    if (res.ok) {
+      console.log(`[${ts()}] Forwarded to OpenClaw (${res.status})`);
+    } else {
+      console.error(`[${ts()}] OpenClaw forward failed (${res.status})`);
+    }
+  } catch (err) {
+    console.error(`[${ts()}] OpenClaw forward error: ${err.message}`);
+  }
+}
+
+function ts() { return new Date().toISOString(); }
+
+const server = createServer((req, res) => {
+  if (req.method === 'GET' && req.url === '/health') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    return res.end('{"status":"ok"}');
+  }
+
+  if (req.method !== 'POST' || req.url !== '/webhook') {
+    res.writeHead(404);
+    return res.end();
+  }
+
+  let size = 0;
+  const chunks = [];
+
+  req.on('data', (chunk) => {
+    size += chunk.length;
+    if (size > MAX_BODY) {
+      res.writeHead(413);
+      res.end('{"error":"Payload too large"}');
+      req.destroy();
+      return;
+    }
+    chunks.push(chunk);
+  });
+
+  req.on('end', () => {
+    if (res.writableEnded) return;
+
+    const rawBody = Buffer.concat(chunks).toString('utf8');
+    const signature = req.headers['x-nansen-signature'];
+
+    if (!verifySignature(rawBody, signature)) {
+      console.error(`[${ts()}] REJECTED — invalid signature`);
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      return res.end('{"error":"Invalid signature"}');
+    }
+
+    let payload;
+    try {
+      payload = JSON.parse(rawBody);
+      console.log(`\n[${ts()}] Alert received:`);
+      console.log(JSON.stringify(payload, null, 2));
+    } catch {
+      console.error(`[${ts()}] WARNING — valid signature but malformed JSON`);
+    }
+
+    // Forward to OpenClaw if configured (fire-and-forget — don't block response)
+    if (payload) forwardToOpenClaw(payload);
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end('{"received":true}');
+  });
+});
+
+for (const sig of ['SIGINT', 'SIGTERM']) {
+  process.on(sig, () => {
+    console.log(`\n${sig} — shutting down`);
+    server.close(() => process.exit(0));
+  });
+}
+
+server.listen(PORT, '127.0.0.1', () => {
+  console.log(`Webhook listener ready — http://127.0.0.1:${PORT}/webhook`);
+  if (OPENCLAW_URL) console.log(`OpenClaw forwarding → ${OPENCLAW_URL}/hooks/agent`);
+  console.log('Waiting for alerts… (Ctrl+C to stop)\n');
+});
+```
+
+### Step 3: Start the server and tunnel
+
+Start the server:
+
+```bash
+WEBHOOK_SECRET='<secret>' node nansen-webhook-server.mjs
+```
+
+Then start a public tunnel so Nansen's servers can reach it.
+
+**ngrok (recommended):**
+```bash
+ngrok http 9477
+```
+Get the public URL from ngrok's output or its local API:
+```bash
+curl -s http://127.0.0.1:4040/api/tunnels | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).tunnels[0]?.public_url))"
+```
+The webhook URL is `https://<subdomain>.ngrok-free.dev/webhook`.
+
+**localtunnel (fallback — unreliable):**
+```bash
+npx localtunnel --port 9477
+```
+Prints a URL like `https://xxx.loca.lt`. The webhook URL is `https://xxx.loca.lt/webhook`.
+
+**Warning:** localtunnel's free relay silently drops connections after minutes. When this happens, all alerts fail with "503 Tunnel Unavailable" until you restart the tunnel and update the alert webhook URL. Use ngrok unless you have a reason not to.
+
+**Note:** Tunnel URLs are ephemeral — they change every restart. For permanent setups, deploy the server to a host with a static URL.
+
+### Step 4: Provide a next-steps summary
+
+**Do NOT create or modify any alerts.** Instead, print a clear summary for the user explaining what was set up and what they need to do next.
+
+The summary MUST include:
+1. Confirmation of what was created (the server script path and the generated secret)
+2. The commands to start the server and tunnel (with the actual secret filled in)
+3. The exact `nansen alerts create` or `nansen alerts update` command they should run, with the `--webhook` and `--webhook-secret` flags filled in with the tunnel URL and secret — but leave the alert-specific flags (`--name`, `--type`, `--chains`, etc.) as placeholders for the user to fill in
+4. A reminder that the server and tunnel must be running before the alert is created (Nansen validates the webhook endpoint on creation)
+5. A note that tunnel URLs are ephemeral and will change on restart
+
+Example summary format:
+
+```
+## Webhook listener ready
+
+**Server script:** ./nansen-webhook-server.mjs
+**Port:** 9477
+
+### To start receiving alerts:
+
+1. Start the server (keep this terminal open):
+   WEBHOOK_SECRET='<actual-secret>' node nansen-webhook-server.mjs
+
+2. In a new terminal, start the tunnel:
+   ngrok http 9477          # recommended
+   # or: npx localtunnel --port 9477  (unreliable — tunnel drops silently)
+
+3. Create an alert pointing to your webhook (fill in your alert details):
+   nansen alerts create \
+     --name '<your alert name>' \
+     --type <sm-token-flows|common-token-transfer|smart-contract-call> \
+     --chains <chains> \
+     --webhook 'https://<your-tunnel-url>/webhook' \
+     --webhook-secret '<actual-secret>' \
+     [type-specific flags...]
+
+   Or add the webhook to an existing alert:
+   nansen alerts update <alert-id> \
+     --webhook 'https://<your-tunnel-url>/webhook' \
+     --webhook-secret '<actual-secret>'
+
+Note: The tunnel URL changes each time you restart. Update the alert
+webhook URL if you restart the tunnel.
+
+See `nansen alerts create --help` for full flag reference per alert type.
+```
+
+## Security Checklist
+
+- **Always use a webhook secret** — the server refuses to start without one
+- **Always verify signatures** — never accept unverified payloads
+- **Bind to localhost only** — the tunnel handles public exposure; direct `0.0.0.0` binding exposes you to unauthenticated traffic
+- **Use HTTPS** — both localtunnel and ngrok tunnel via HTTPS by default
+- **Body size limit** — the 1 MB cap prevents memory exhaustion from oversized requests
+- **Timing-safe comparison** — prevents timing side-channel attacks on the signature
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| "Invalid signature" on every request | Ensure the **exact same secret** is in `WEBHOOK_SECRET` and `--webhook-secret` |
+| "Failed to send welcome message" on alert create | Start the server and tunnel **before** creating the alert |
+| No alerts arriving | Check `nansen alerts list --table` — is the alert enabled? Is the webhook URL correct (includes `/webhook`)? |
+| Tunnel URL expired / tunnel died | Restart the tunnel, get the new URL, then `nansen alerts update <id> --webhook '<new-url>/webhook'`. If this keeps happening, switch from localtunnel to ngrok. |
+| Port already in use | Set a different port: `PORT=9478 WEBHOOK_SECRET='...' node nansen-webhook-server.mjs` and update the tunnel accordingly |
+
+## OpenClaw Integration
+
+If the user is running OpenClaw locally on the same machine, the webhook server can forward verified alert payloads to OpenClaw's Gateway, triggering an agent turn for each alert.
+
+**Flow:** `Nansen → ngrok → webhook server (signature check) → OpenClaw /hooks/agent`
+
+### Additional env vars
+
+| Var | Required | Purpose |
+|-----|----------|---------|
+| `OPENCLAW_GATEWAY_URL` | Yes | OpenClaw Gateway base URL (e.g. `http://localhost:3000`) |
+| `OPENCLAW_AUTH_TOKEN` | If auth enabled | Bearer token for OpenClaw webhook endpoints |
+
+### Start command (with OpenClaw forwarding)
+
+```bash
+WEBHOOK_SECRET='<secret>' \
+OPENCLAW_GATEWAY_URL='http://localhost:3000' \
+OPENCLAW_AUTH_TOKEN='<token>' \
+node nansen-webhook-server.mjs
+```
+
+The server logs both the alert payload and the OpenClaw forward status. If OpenClaw is unreachable, the forward fails silently (the alert is still logged to stdout).
+
+### Ask the user
+
+Before enabling OpenClaw forwarding, ask:
+1. Is OpenClaw running locally? What port?
+2. Does their Gateway require auth? If so, what's the Bearer token?
+
+If they don't know or aren't running OpenClaw, skip — the server works fine standalone.
+
+## Notes
+
+- The server uses zero npm dependencies — only Node.js built-ins
+- One server can receive alerts from multiple Nansen alerts (as long as they share the same webhook secret)
+- For production use, deploy to a cloud host with a static URL and run behind a reverse proxy with TLS
+- The `x-nansen-signature` header format is `sha256=<HMAC-SHA256(secret, rawBody)>` — strip the `sha256=` prefix before comparing

package/skills/nansen-trading/SKILL.md

@@ -33,7 +33,18 @@ nansen trade quote \
   --amount 1000000000
 ```
 
-Symbols resolve automatically: `SOL`, `ETH`, `USDC`, `USDT`, `WETH`. Raw addresses also work.
+Symbols resolve automatically: `SOL`, `ETH`, `USDC`, `USDT`, `WETH`. Raw addresses also work. Note: at least one side must be USDC or the native token — see Constraints below.
+
+## Constraints
+
+**Swap constraint:** At least one side of every swap must be **USDC** or the chain's **native token** (SOL on Solana, ETH on Base). Arbitrary token-to-token swaps (e.g. WETH→USDT, BONK→JUP) are rejected.
+
+- USDC (Solana): `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
+- USDC (Base): `0x833589fcd6edb6e08f4c7c32d4f71b54bda02913`
+- Native SOL: `So11111111111111111111111111111111111111112`
+- Native ETH: `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`
+
+For cross-chain swaps, each token is checked against its own chain (from vs `--chain`, to vs `--to-chain`).
 
 ## Execute
 

package/src/api.js

@@ -1230,11 +1230,11 @@ export class NansenAPI {
   // ============= Prediction Market Endpoints =============
 
   async pmOhlcv(params = {}) {
-    const { marketId, sort, pagination } = params;
+    const { marketId, orderBy, sort, pagination } = params;
     if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/ohlcv', {
       market_id: marketId,
-      sort,
+      order_by: orderBy || sort,
       pagination
     });
   }
@@ -1249,71 +1249,105 @@ export class NansenAPI {
   }
 
   async pmTopHolders(params = {}) {
-    const { marketId, sort, pagination } = params;
+    const { marketId, orderBy, sort, pagination } = params;
     if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/top-holders', {
       market_id: marketId,
-      sort,
+      order_by: orderBy || sort,
       pagination
     });
   }
 
   async pmTradesByMarket(params = {}) {
-    const { marketId, pagination } = params;
+    const { marketId, orderBy, pagination } = params;
     if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/trades-by-market', {
       market_id: marketId,
+      order_by: orderBy,
       pagination
     });
   }
 
   async pmTradesByAddress(params = {}) {
-    const { address, pagination } = params;
+    const { address, orderBy, pagination } = params;
     // Polymarket runs exclusively on Polygon
     const validation = validateAddress(address, 'polygon');
     if (!validation.valid) throw new NansenError(validation.error, validation.code);
     return this.request('/api/v1/prediction-market/trades-by-address', {
       address,
+      order_by: orderBy,
       pagination
     });
   }
 
   async pmMarketScreener(params = {}) {
-    const { sortBy = 'volume_24hr', query = '', status = '', pagination } = params;
-    return this.request('/api/v1/prediction-market/market-screener', {
+    const { orderBy, sortBy = 'volume_24hr', query = '', status = '', tags, minLiquidity, maxLiquidity, minUniqueTraders24h, maxUniqueTraders24h, minVolume24hr, maxVolume24hr, negRisk, minOpenInterest, maxOpenInterest, endDateBefore, endDateAfter, minPrice, maxPrice, pagination } = params;
+    const body = {
       sort_by: sortBy,
       query,
       status,
       pagination
-    });
+    };
+    if (orderBy) body.order_by = orderBy;
+    if (tags && tags.length) body.tags = tags;
+    if (minLiquidity != null) body.min_liquidity = minLiquidity;
+    if (maxLiquidity != null) body.max_liquidity = maxLiquidity;
+    if (minUniqueTraders24h != null) body.min_unique_traders_24h = minUniqueTraders24h;
+    if (maxUniqueTraders24h != null) body.max_unique_traders_24h = maxUniqueTraders24h;
+    if (minVolume24hr != null) body.min_volume_24hr = minVolume24hr;
+    if (maxVolume24hr != null) body.max_volume_24hr = maxVolume24hr;
+    if (negRisk != null) body.neg_risk = negRisk;
+    if (minOpenInterest != null) body.min_open_interest = minOpenInterest;
+    if (maxOpenInterest != null) body.max_open_interest = maxOpenInterest;
+    if (endDateBefore) body.end_date_before = endDateBefore;
+    if (endDateAfter) body.end_date_after = endDateAfter;
+    if (minPrice != null) body.min_price = minPrice;
+    if (maxPrice != null) body.max_price = maxPrice;
+    return this.request('/api/v1/prediction-market/market-screener', body);
   }
 
   async pmEventScreener(params = {}) {
-    const { sortBy = 'volume_24hr', query = '', status = '', pagination } = params;
-    return this.request('/api/v1/prediction-market/event-screener', {
+    const { orderBy, sortBy = 'volume_24hr', query = '', status = '', tags, minLiquidity, maxLiquidity, minUniqueTraders24h, maxUniqueTraders24h, minVolume24hr, maxVolume24hr, negRisk, minOpenInterest, maxOpenInterest, endDateBefore, endDateAfter, pagination } = params;
+    const body = {
       sort_by: sortBy,
       query,
       status,
       pagination
-    });
+    };
+    if (orderBy) body.order_by = orderBy;
+    if (tags && tags.length) body.tags = tags;
+    if (minLiquidity != null) body.min_liquidity = minLiquidity;
+    if (maxLiquidity != null) body.max_liquidity = maxLiquidity;
+    if (minUniqueTraders24h != null) body.min_unique_traders_24h = minUniqueTraders24h;
+    if (maxUniqueTraders24h != null) body.max_unique_traders_24h = maxUniqueTraders24h;
+    if (minVolume24hr != null) body.min_volume_24hr = minVolume24hr;
+    if (maxVolume24hr != null) body.max_volume_24hr = maxVolume24hr;
+    if (negRisk != null) body.neg_risk = negRisk;
+    if (minOpenInterest != null) body.min_open_interest = minOpenInterest;
+    if (maxOpenInterest != null) body.max_open_interest = maxOpenInterest;
+    if (endDateBefore) body.end_date_before = endDateBefore;
+    if (endDateAfter) body.end_date_after = endDateAfter;
+    return this.request('/api/v1/prediction-market/event-screener', body);
   }
 
   async pmPnlByMarket(params = {}) {
-    const { marketId, pagination } = params;
+    const { marketId, orderBy, pagination } = params;
     if (!marketId) throw new NansenError('market_id is required. Run: nansen research pm market-screener --query "your search"', ErrorCode.MISSING_PARAM);
     return this.request('/api/v1/prediction-market/pnl-by-market', {
       market_id: marketId,
+      order_by: orderBy,
       pagination
     });
   }
 
   async pmPnlByAddress(params = {}) {
-    const { address, pagination } = params;
+    const { address, orderBy, pagination } = params;
     // Polymarket runs exclusively on Polygon
     const validation = validateAddress(address, 'polygon');
     if (!validation.valid) throw new NansenError(validation.error, validation.code);
     return this.request('/api/v1/prediction-market/pnl-by-address', {
       address,
+      order_by: orderBy,
       pagination
     });
   }
@@ -1334,6 +1368,17 @@ export class NansenAPI {
     });
   }
 
+  async pmAddressSummary(params = {}) {
+    const { address, pagination } = params;
+    // Polymarket runs exclusively on Polygon
+    const validation = validateAddress(address, 'polygon');
+    if (!validation.valid) throw new NansenError(validation.error, validation.code);
+    return this.request('/api/v1/prediction-market/address-summary', {
+      address,
+      pagination
+    });
+  }
+
   // ============= Points Endpoints =============
 
   async pointsLeaderboard(params = {}) {

package/src/cli.js

@@ -1407,23 +1407,40 @@ export function buildCommands(deps = {}) {
       const sortBy = options['sort-by'];
       const query = options.query;
       const status = options.status;
-      const sort = parseSort(options.sort);
+      const orderBy = parseSort(options.sort, options['order-by']);
       const pagination = buildPagination(options);
 
+      // Screener-specific filter options
+      const tags = options.tags ? options.tags.split(',').map(t => t.trim()) : undefined;
+      const minLiquidity = options['min-liquidity'] != null ? Number(options['min-liquidity']) : undefined;
+      const maxLiquidity = options['max-liquidity'] != null ? Number(options['max-liquidity']) : undefined;
+      const minUniqueTraders24h = options['min-unique-traders-24h'] != null ? Number(options['min-unique-traders-24h']) : undefined;
+      const maxUniqueTraders24h = options['max-unique-traders-24h'] != null ? Number(options['max-unique-traders-24h']) : undefined;
+      const minVolume24hr = options['min-volume-24hr'] != null ? Number(options['min-volume-24hr']) : undefined;
+      const maxVolume24hr = options['max-volume-24hr'] != null ? Number(options['max-volume-24hr']) : undefined;
+      const negRisk = options['neg-risk'] != null ? options['neg-risk'] === 'true' : undefined;
+      const minOpenInterest = options['min-open-interest'] != null ? Number(options['min-open-interest']) : undefined;
+      const maxOpenInterest = options['max-open-interest'] != null ? Number(options['max-open-interest']) : undefined;
+      const endDateBefore = options['end-date-before'];
+      const endDateAfter = options['end-date-after'];
+      const minPrice = options['min-price'] != null ? Number(options['min-price']) : undefined;
+      const maxPrice = options['max-price'] != null ? Number(options['max-price']) : undefined;
+
       const handlers = {
-        'ohlcv': () => apiInstance.pmOhlcv({ marketId, sort, pagination }),
+        'ohlcv': () => apiInstance.pmOhlcv({ marketId, orderBy, pagination }),
         'orderbook': () => apiInstance.pmOrderbook({ marketId, pagination }),
-        'top-holders': () => apiInstance.pmTopHolders({ marketId, sort, pagination }),
-        'trades-by-market': () => apiInstance.pmTradesByMarket({ marketId, pagination }),
-        'trades-by-address': () => apiInstance.pmTradesByAddress({ address, pagination }),
-        'market-screener': () => apiInstance.pmMarketScreener({ sortBy, query, status, pagination }),
-        'event-screener': () => apiInstance.pmEventScreener({ sortBy, query, status, pagination }),
-        'pnl-by-market': () => apiInstance.pmPnlByMarket({ marketId, pagination }),
-        'pnl-by-address': () => apiInstance.pmPnlByAddress({ address, pagination }),
+        'top-holders': () => apiInstance.pmTopHolders({ marketId, orderBy, pagination }),
+        'trades-by-market': () => apiInstance.pmTradesByMarket({ marketId, orderBy, pagination }),
+        'trades-by-address': () => apiInstance.pmTradesByAddress({ address, orderBy, pagination }),
+        'market-screener': () => apiInstance.pmMarketScreener({ orderBy, sortBy, query, status, tags, minLiquidity, maxLiquidity, minUniqueTraders24h, maxUniqueTraders24h, minVolume24hr, maxVolume24hr, negRisk, minOpenInterest, maxOpenInterest, endDateBefore, endDateAfter, minPrice, maxPrice, pagination }),
+        'event-screener': () => apiInstance.pmEventScreener({ orderBy, sortBy, query, status, tags, minLiquidity, maxLiquidity, minUniqueTraders24h, maxUniqueTraders24h, minVolume24hr, maxVolume24hr, negRisk, minOpenInterest, maxOpenInterest, endDateBefore, endDateAfter, pagination }),
+        'pnl-by-market': () => apiInstance.pmPnlByMarket({ marketId, orderBy, pagination }),
+        'pnl-by-address': () => apiInstance.pmPnlByAddress({ address, orderBy, pagination }),
         'position-detail': () => apiInstance.pmPositionDetail({ marketId, pagination }),
         'categories': () => apiInstance.pmCategories({ pagination }),
+        'address-summary': () => apiInstance.pmAddressSummary({ address, pagination }),
         'help': () => ({
-          commands: ['ohlcv', 'orderbook', 'top-holders', 'trades-by-market', 'trades-by-address', 'market-screener', 'event-screener', 'pnl-by-market', 'pnl-by-address', 'position-detail', 'categories'],
+          commands: ['ohlcv', 'orderbook', 'top-holders', 'trades-by-market', 'trades-by-address', 'market-screener', 'event-screener', 'pnl-by-market', 'pnl-by-address', 'position-detail', 'categories', 'address-summary'],
           description: 'Polymarket prediction market analytics',
           example: 'nansen research pm market-screener --sort-by volume_24hr --limit 20'
         })

package/src/index.js

@@ -14,4 +14,4 @@
 import { runCLI } from './cli.js';
 
 // Main entry point
-runCLI(process.argv.slice(2));
+await runCLI(process.argv.slice(2));

package/src/schema.json

@@ -588,18 +588,42 @@
               "endpoint": "/api/v1/prediction-market/market-screener",
               "description": "Get Prediction Market Screener",
               "options": {
-                "query": {
-                  "default": ""
-                }
+                "query": { "default": "" },
+                "sort-by": { "description": "Deprecated: use --sort field:dir instead" },
+                "tags": {},
+                "min-liquidity": {},
+                "max-liquidity": {},
+                "min-unique-traders-24h": {},
+                "max-unique-traders-24h": {},
+                "min-volume-24hr": {},
+                "max-volume-24hr": {},
+                "neg-risk": {},
+                "min-open-interest": {},
+                "max-open-interest": {},
+                "end-date-before": {},
+                "end-date-after": {},
+                "min-price": {},
+                "max-price": {}
               }
             },
             "event-screener": {
               "endpoint": "/api/v1/prediction-market/event-screener",
               "description": "Get Prediction Market Event Screener",
               "options": {
-                "query": {
-                  "default": ""
-                }
+                "query": { "default": "" },
+                "sort-by": { "description": "Deprecated: use --sort field:dir instead" },
+                "tags": {},
+                "min-liquidity": {},
+                "max-liquidity": {},
+                "min-unique-traders-24h": {},
+                "max-unique-traders-24h": {},
+                "min-volume-24hr": {},
+                "max-volume-24hr": {},
+                "neg-risk": {},
+                "min-open-interest": {},
+                "max-open-interest": {},
+                "end-date-before": {},
+                "end-date-after": {}
               }
             },
             "pnl-by-market": {
@@ -641,6 +665,15 @@
             "categories": {
               "endpoint": "/api/v1/prediction-market/categories",
               "description": "Get Prediction Market Categories"
+            },
+            "address-summary": {
+              "endpoint": "/api/v1/prediction-market/address-summary",
+              "description": "Get wallet-level PnL summary for a Polymarket address",
+              "options": {
+                "address": {
+                  "required": true
+                }
+              }
             }
           },
           "description": "Polymarket prediction market analytics"

package/src/trade-validation.js

@@ -61,6 +61,16 @@ export function validateQuoteInput({ chain, toChain, from, to, amount }) {
       );
     }
   }
+
+  // 5. At least one side must be USDC or the native token
+  const fromIsAnchor = isUsdcOrNative(from, normalizedChain);
+  const toIsAnchor = isUsdcOrNative(to, normalizedToChain);
+  if (!fromIsAnchor && !toIsAnchor) {
+    const anchorDesc = normalizedChain === normalizedToChain
+      ? `USDC or the native token (${NATIVE_SYMBOLS[normalizedChain] ?? normalizedChain})`
+      : `USDC or the native token on either side (${NATIVE_SYMBOLS[normalizedChain] ?? normalizedChain} on ${normalizedChain}, ${NATIVE_SYMBOLS[normalizedToChain] ?? normalizedToChain} on ${normalizedToChain})`;
+    throw new Error(`Invalid swap: at least one token must be ${anchorDesc}. Got: ${from} → ${to}.`);
+  }
 }
 
 // Native token decimals per chain (for converting balance from base units)
@@ -112,6 +122,12 @@ const NATIVE_TOKEN_ADDRESSES = {
   base: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
 };
 
+// USDC contract addresses per chain.
+const USDC_ADDRESSES = {
+  solana: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+  base: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+};
+
 // Native token symbols for error messages.
 const NATIVE_SYMBOLS = { solana: 'SOL', base: 'ETH' };
 
@@ -120,6 +136,21 @@ const FEE_BUFFER = { solana: 0.005, base: 0.00004 };
 const HIGH_PERCENTAGE_THRESHOLD = 95;
 const AUTO_ADJUST_THRESHOLD_PERCENT = 2;
 
+/**
+ * Check if an address is USDC or the native token for a chain (case-insensitive for EVM).
+ */
+function isUsdcOrNative(address, chain) {
+  const usdc = USDC_ADDRESSES[chain];
+  const native = NATIVE_TOKEN_ADDRESSES[chain];
+  if (!usdc && !native) return false;
+  if (chain === 'solana') {
+    return address === usdc || address === native;
+  }
+  // EVM: case-insensitive
+  const lower = address.toLowerCase();
+  return (usdc && lower === usdc.toLowerCase()) || (native && lower === native.toLowerCase());
+}
+
 /**
  * Check if an address is the native token for a chain (case-insensitive for EVM).
  */

package/src/transfer.js

@@ -21,6 +21,16 @@ const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
 // Alias: buildEvmTransaction uses 'evm' as a generic fallback
 const CHAIN_IDS = { ...EVM_CHAIN_IDS, evm: 1 };
 
+// ============= Address Derivation =============
+
+function deriveEvmAddress(privateKeyHex) {
+  const privBuf = Buffer.from(privateKeyHex, 'hex');
+  const ecdh = crypto.createECDH('secp256k1');
+  ecdh.setPrivateKey(privBuf);
+  const pubKey = ecdh.getPublicKey(null, 'uncompressed');
+  return '0x' + keccak256(pubKey.subarray(1)).subarray(12).toString('hex');
+}
+
 // ============= Address Validation =============
 
 function validateEvmAddress(address) {
@@ -106,12 +116,9 @@ async function buildEvmTransaction({ to, amount, token, privateKey, chain, max =
   const rpcUrl = CHAIN_RPCS[chain] || CHAIN_RPCS.evm;
   const chainId = CHAIN_IDS[chain] || 1;
 
-  // Derive address
+  // Derive address and buffer for signing
   const privBuf = Buffer.from(privateKey, 'hex');
-  const ecdh = crypto.createECDH('secp256k1');
-  ecdh.setPrivateKey(privBuf);
-  const pubKey = ecdh.getPublicKey(null, 'uncompressed');
-  const from = '0x' + keccak256(pubKey.subarray(1)).subarray(12).toString('hex');
+  const from = deriveEvmAddress(privateKey);
 
   // Nonce
   const nonceHex = await rpcCall(rpcUrl, 'eth_getTransactionCount', [from, 'latest']);
@@ -735,11 +742,7 @@ export async function sendTokens({ to, amount, chain, token = null, wallet = nul
 
     if (max && token) {
       // Max ERC-20: full token balance
-      const privBuf = Buffer.from(walletData.evm.privateKey, 'hex');
-      const ecdh = crypto.createECDH('secp256k1');
-      ecdh.setPrivateKey(privBuf);
-      const pubKey = ecdh.getPublicKey(null, 'uncompressed');
-      const from = '0x' + keccak256(pubKey.subarray(1)).subarray(12).toString('hex');
+      const from = deriveEvmAddress(walletData.evm.privateKey);
       const balResult = await rpcCall(rpcUrl, 'eth_call', [{
         to: token, data: '0x70a08231' + from.slice(2).padStart(64, '0'),
       }, 'latest']);

package/src/wallet.js

@@ -247,6 +247,14 @@ function getWalletFile(name) {
   return path.join(getWalletsDir(), `${name}.json`);
 }
 
+function requireWalletFile(name) {
+  const walletFile = getWalletFile(name);
+  if (!fs.existsSync(walletFile)) {
+    throw new Error(`Wallet "${name}" not found`);
+  }
+  return walletFile;
+}
+
 /**
  * Verify the global password against stored hash.
  */
@@ -466,10 +474,7 @@ export function createWallet(name, password) {
  * Show wallet details (addresses only, no keys).
  */
 export function showWallet(name) {
-  const walletFile = getWalletFile(name);
-  if (!fs.existsSync(walletFile)) {
-    throw new Error(`Wallet "${name}" not found`);
-  }
+  const walletFile = requireWalletFile(name);
 
   const data = JSON.parse(fs.readFileSync(walletFile, 'utf8'));
   const config = getWalletConfig();
@@ -495,10 +500,7 @@ export function showWallet(name) {
  * Export private keys for a wallet (requires password).
  */
 export function exportWallet(name, password) {
-  const walletFile = getWalletFile(name);
-  if (!fs.existsSync(walletFile)) {
-    throw new Error(`Wallet "${name}" not found`);
-  }
+  const walletFile = requireWalletFile(name);
 
   const data = JSON.parse(fs.readFileSync(walletFile, 'utf8'));
   if (data.provider && data.provider !== 'local') {
@@ -527,10 +529,7 @@ export function exportWallet(name, password) {
  * Set the default wallet.
  */
 export function setDefaultWallet(name) {
-  const walletFile = getWalletFile(name);
-  if (!fs.existsSync(walletFile)) {
-    throw new Error(`Wallet "${name}" not found`);
-  }
+  requireWalletFile(name);
 
   const config = getWalletConfig();
   config.defaultWallet = name;
@@ -543,10 +542,7 @@ export function setDefaultWallet(name) {
  * Delete a wallet.
  */
 export async function deleteWallet(name, password) {
-  const walletFile = getWalletFile(name);
-  if (!fs.existsSync(walletFile)) {
-    throw new Error(`Wallet "${name}" not found`);
-  }
+  const walletFile = requireWalletFile(name);
 
   const data = JSON.parse(fs.readFileSync(walletFile, 'utf8'));
   const config = getWalletConfig();