nansen-cli 1.28.0 → 1.30.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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
+
+- [#423](https://github.com/nansen-ai/nansen-cli/pull/423) [`d10aa57`](https://github.com/nansen-ai/nansen-cli/commit/d10aa575c31f7702241ad114276fa5234f2bdf59) Thanks [@imhta](https://github.com/imhta)! - Add Relay aggregator support for Base↔Solana cross-chain swaps. Users now see Relay quotes alongside Li.Fi in `nansen trade quote --to-chain ...`, can execute them through `trade execute`, and optionally use Relay's gasless path with `--gasless` (local/Privy wallets only — not WalletConnect). `trade bridge-status` auto-detects which aggregator produced a tx (via a local tx record) and polls the right backend.
+
 ## 1.28.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
 
@@ -51,7 +57,16 @@ nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
 nansen trade execute --quote <quoteId>
 ```
 
-Amounts are in base units (lamports, wei). Common symbols (`SOL`, `ETH`, `USDC`, `USDT`) resolve automatically. A wallet is required — set one with `nansen wallet default <name>`.
+Cross-chain swaps work the same way — add `--to-chain`. Bridge providers (Li.Fi or Relay) are selected automatically based on best price.
+
+```bash
+nansen trade quote --chain base --to-chain solana --from ETH --to SOL --amount 0.0003 --amount-unit token
+nansen trade execute --quote <quoteId>                # signed broadcast
+nansen trade execute --quote <quoteId> --gasless      # Relay-only: solver pays gas
+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>`.
 
 ## Wallet
 
@@ -67,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.28.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/cli.js

@@ -1520,12 +1520,12 @@ SYMBOLS:
 
 CROSS-CHAIN NOTES (when using --to-chain):
   Supported combos:
-    native → native (ETH <-> SOL) — requires $5+ per trade
+    native → native (ETH <-> SOL)
     USDC → USDC (both directions)
     USDC → native (USDC → ETH or SOL)
     native → USDC (ETH/SOL → USDC)
     non-native → non-native — not supported (use USDC as intermediate)
-  Bridge provider: Li.Fi
+  Bridge providers: Li.Fi or Relay (selected automatically based on best price)
   Typical bridge time: 1-5 minutes`);
       return;
     }

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

@@ -852,7 +852,7 @@
             },
             "to-chain": {
               "type": "string",
-              "description": "Destination blockchain for cross-chain swap (solana or base). Omit for same-chain. At least one side must be USDC or a native token (ETH, SOL). Non-native to non-native is not supported — swap to USDC first, then bridge. Minimum ~$5 per cross-chain trade (Li.Fi bridge)."
+              "description": "Destination blockchain for cross-chain swap (solana or base). Omit for same-chain. At least one side must be USDC or a native token (ETH, SOL). Non-native to non-native is not supported — swap to USDC first, then bridge. Bridge providers (Li.Fi or Relay) are selected automatically based on best price. Sub-dollar swaps are supported via Relay."
             },
             "from": {
               "type": "string",
@@ -880,6 +880,10 @@
             "to-wallet": {
               "type": "string",
               "description": "Destination wallet address for cross-chain swaps. Auto-derived from wallet if omitted."
+            },
+            "aggregator": {
+              "type": "string",
+              "description": "Force a specific aggregator: lifi, relay, jupiter, or okx. Filters the returned quote list client-side; errors if no quote from that aggregator was returned."
             }
           },
           "prerequisites": [
@@ -897,11 +901,15 @@
             "wallet": {
               "type": "string",
               "description": "Wallet name, or \"walletconnect\"/\"wc\" for WalletConnect (EVM only)"
+            },
+            "gasless": {
+              "type": "boolean",
+              "description": "Relay-only: have Relay's solver pay gas + broadcast (user signs only). Requires the selected quote's aggregator to be \"relay\". Not supported via WalletConnect."
             }
           }
         },
         "bridge-status": {
-          "description": "Check cross-chain bridge transaction status",
+          "description": "Check cross-chain bridge transaction status. Aggregator (Li.Fi or Relay) is auto-detected from a local tx record saved at execute time (kept 30 days); pass --aggregator to override when polling from a different machine.",
           "options": {
             "tx-hash": {
               "type": "string",
@@ -917,6 +925,10 @@
               "type": "string",
               "required": true,
               "description": "Destination chain (solana or base)"
+            },
+            "aggregator": {
+              "type": "string",
+              "description": "lifi or relay. Overrides auto-detection — use when polling from a different machine or after the 30-day local record TTL has expired."
             }
           }
         },

package/src/trading.js

@@ -37,6 +37,10 @@ const WRAPPED_NATIVE_TOKENS = {
 // Wrapped-native addresses (WETH) are derived from WRAPPED_NATIVE_TOKENS
 // to avoid duplication — keep that map as the single source of truth.
 const EVM_NATIVE = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
+// Relay returns the Solana System Program mint as the sentinel for native SOL.
+// Recognise it as native so approval/value validation behaves correctly when
+// cross-chain quotes route through Relay. (LiFi/Jupiter still use WSOL.)
+const NATIVE_SOL_SYSTEM_MINT = '11111111111111111111111111111111';
 const TOKEN_SYMBOLS = {
   solana: {
     SOL:  'So11111111111111111111111111111111111111112',
@@ -206,37 +210,60 @@ export async function executeTransaction(params, { retries = 2, retryDelayMs = 1
 
 /**
  * Check the status of a cross-chain bridge transaction.
+ * Retries on 502/503 (Cloudflare/upstream gateway hiccups) like executeTransaction.
  * @param {string} txHash - Source chain transaction hash
  * @param {string} fromChain - Source chain name (e.g. 'base')
  * @param {string} toChain - Destination chain name (e.g. 'solana')
+ * @param {object} [opts]
+ * @param {string} [opts.aggregator] - 'lifi' (default) or 'relay'. Relay txHashes
+ *   return NOT_FOUND when polled with the LiFi default, so this must be set.
+ * @param {number} [opts.retries=2] - Retry count for 502/503.
+ * @param {number} [opts.retryDelayMs=1500] - Delay between retries.
  * @returns {Promise<object>} Bridge status
  */
-export async function getBridgeStatus(txHash, fromChain, toChain) {
+export async function getBridgeStatus(txHash, fromChain, toChain, { aggregator, retries = 2, retryDelayMs = 1500 } = {}) {
   const fromConfig = resolveChain(fromChain);
   const toConfig = resolveChain(toChain);
   const url = new URL('/bridge/status', TRADING_API_URL);
   url.searchParams.set('txHash', txHash);
   url.searchParams.set('fromChain', fromConfig.lifiChainId || fromConfig.index);
   url.searchParams.set('toChain', toConfig.lifiChainId || toConfig.index);
+  if (aggregator) url.searchParams.set('aggregator', aggregator);
 
-  const res = await fetch(url.toString(), { headers: { 'Accept': 'application/json', 'User-Agent': CLIENT_USER_AGENT } });
-  const text = await res.text();
-  let body;
-  try {
-    body = JSON.parse(text);
-  } catch {
-    throw Object.assign(
-      new Error(`Bridge status API returned non-JSON response (status ${res.status}).`),
-      { code: 'BRIDGE_STATUS_ERROR', status: res.status, details: text.slice(0, 200) }
-    );
-  }
-  if (!res.ok) {
-    throw Object.assign(
-      new Error(body.message || `Bridge status check failed with status ${res.status}`),
-      { code: body.code || 'BRIDGE_STATUS_ERROR', status: res.status, details: body.details }
-    );
+  let lastError;
+  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 text = await res.text();
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      // Non-JSON response (typically Cloudflare HTML on 502/503). Don't leak the
+      // HTML body to the user — surface a clean status hint and a retry tip.
+      const hint = res.status === 502 || res.status === 503
+        ? ' Upstream bridge service is temporarily unavailable. Retry in a moment, or check the source-chain explorer to confirm the tx landed.'
+        : '';
+      lastError = Object.assign(
+        new Error(`Bridge status API returned non-JSON response (status ${res.status}).${hint}`),
+        { code: 'BRIDGE_STATUS_ERROR', status: res.status }
+      );
+      if ((res.status === 502 || res.status === 503) && attempt < retries) continue;
+      throw lastError;
+    }
+    if (!res.ok) {
+      const isTransient = res.status === 502 || res.status === 503;
+      lastError = Object.assign(
+        new Error(body.message || `Bridge status check failed with status ${res.status}`),
+        { code: body.code || 'BRIDGE_STATUS_ERROR', status: res.status, details: body.details }
+      );
+      if (isTransient && attempt < retries) continue;
+      throw lastError;
+    }
+    return body;
   }
-  return body;
+  throw lastError;
 }
 
 /**
@@ -248,14 +275,15 @@ export async function getBridgeStatus(txHash, fromChain, toChain) {
  * @param {number} [opts.timeoutMs=600000] - Timeout (default 10 min)
  * @param {number} [opts.pollMs=10000] - Poll interval (default 10s)
  * @param {Function} [opts.log=console.log] - Logger
+ * @param {string} [opts.aggregator] - 'lifi' or 'relay'; forwarded to bridge-status query.
  * @returns {Promise<object>} Final bridge status
  */
-export async function pollBridgeStatus(txHash, fromChain, toChain, { timeoutMs = 600000, pollMs = 10000, log = console.log } = {}) {
+export async function pollBridgeStatus(txHash, fromChain, toChain, { timeoutMs = 600000, pollMs = 10000, log = console.log, aggregator } = {}) {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
     let status;
     try {
-      status = await getBridgeStatus(txHash, fromChain, toChain);
+      status = await getBridgeStatus(txHash, fromChain, toChain, { aggregator });
     } catch (err) {
       // Transient errors (502, 503, network failures) — retry after poll interval.
       log(`  Bridge: poll error (${err.status || err.code || 'unknown'}) — retrying...`);
@@ -266,7 +294,13 @@ export async function pollBridgeStatus(txHash, fromChain, toChain, { timeoutMs =
     const receiving = status.receiving?.status || 'pending';
     log(`  Bridge: ${sending} → ${receiving}`);
 
-    if (status.status === 'DONE' || status.receiving?.status === 'DONE') return status;
+    const isTerminal = status.status === 'DONE' || status.receiving?.status === 'DONE';
+    if (isTerminal) {
+      if (status.substatus === 'REFUNDED') {
+        log(`  Bridge: REFUNDED — funds returned on source chain`);
+      }
+      return status;
+    }
     if (status.status === 'FAILED') {
       throw Object.assign(
         new Error(`Bridge failed: ${status.substatusMessage || 'unknown error'}`),
@@ -282,6 +316,43 @@ export async function pollBridgeStatus(txHash, fromChain, toChain, { timeoutMs =
   );
 }
 
+// Tx records keep aggregator metadata for `bridge-status`. They're not stale-able
+// the way quotes are (a finished tx doesn't expire), but cap them to bound disk use.
+const TX_RECORD_TTL_MS = 30 * 24 * 3600 * 1000; // 30 days
+
+/**
+ * Persist a tx → aggregator mapping for cross-chain swaps so `bridge-status`
+ * can pass the right `aggregator` query param without a new CLI flag.
+ * Lives next to saved quotes; uses a 30-day TTL (longer than quotes) so users
+ * can still resolve the aggregator hours/days after the swap.
+ */
+export function saveTxRecord(txHash, { aggregator, requestId, fromChain, toChain }) {
+  if (!txHash) return;
+  const dir = getQuotesDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const data = { txHash, aggregator, requestId, fromChain, toChain, timestamp: Date.now() };
+  fs.writeFileSync(path.join(dir, `tx-${txHash}.json`), JSON.stringify(data, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Load a previously saved tx record. Returns null if not found or older than 30 days.
+ */
+export function loadTxRecord(txHash) {
+  if (!txHash) return null;
+  const filePath = path.join(getQuotesDir(), `tx-${txHash}.json`);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (Date.now() - data.timestamp > TX_RECORD_TTL_MS) {
+      fs.unlinkSync(filePath);
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
 // ============= Quote Storage =============
 
 /**
@@ -324,7 +395,9 @@ export function loadQuote(quoteId) {
 }
 
 /**
- * Remove quotes older than 1 hour.
+ * Remove stale files from the quotes dir. Quote files use a 1-hour TTL because
+ * the price is stale; tx records use a 30-day TTL because a finalized tx hash
+ * is permanent and `bridge-status` needs the aggregator hint long after execute.
  */
 export function cleanupQuotes() {
   const dir = getQuotesDir();
@@ -332,9 +405,10 @@ export function cleanupQuotes() {
   const now = Date.now();
   for (const file of fs.readdirSync(dir)) {
     if (!file.endsWith('.json')) continue;
+    const ttl = file.startsWith('tx-') ? TX_RECORD_TTL_MS : 3600000;
     try {
       const data = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
-      if (now - data.timestamp > 3600000) fs.unlinkSync(path.join(dir, file));
+      if (now - data.timestamp > ttl) fs.unlinkSync(path.join(dir, file));
     } catch { /* ignore */ }
   }
 }
@@ -732,7 +806,11 @@ function resolveTradePassword() {
 }
 
 function isNativeToken(mintAddress) {
-  return /^0x[eE]{40}$/.test(mintAddress);
+  if (!mintAddress) return false;
+  if (mintAddress.startsWith('0x')) return /^0x[eE]{40}$/.test(mintAddress);
+  // Solana: WSOL mint (Jupiter/LiFi) and System Program (Relay) both denote native SOL.
+  return mintAddress === 'So11111111111111111111111111111111111111112'
+      || mintAddress === NATIVE_SOL_SYSTEM_MINT;
 }
 
 /**
@@ -767,6 +845,7 @@ export function getWrappedNativeFromWarning(tokenAddress, chain) {
 const KNOWN_DECIMALS = {
   // Solana
   'So11111111111111111111111111111111111111112': 9,   // SOL/WSOL
+  '11111111111111111111111111111111': 9,              // Native SOL (Relay system-mint sentinel)
   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v': 6, // USDC
   'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB': 6,  // USDT
   // Base (EVM) — lowercase for case-insensitive matching
@@ -912,12 +991,17 @@ export function formatQuote(quote, index) {
   }
   if (quote.tradingFeeInUsd) lines.push(`    Trading Fee:  $${quote.tradingFeeInUsd}`);
   if (quote.networkFeeInUsd) lines.push(`    Network Fee:  $${quote.networkFeeInUsd}`);
-  if (quote.approvalAddress && !isNativeToken(quote.inputMint)) lines.push(`    ⚠ Requires token approval to: ${quote.approvalAddress}`);
+  // Empty string is Relay's "no approval needed" sentinel — gate on truthy + non-empty.
+  if (quote.approvalAddress && quote.approvalAddress !== '' && !isNativeToken(quote.inputMint)) {
+    lines.push(`    ⚠ Requires token approval to: ${quote.approvalAddress}`);
+  }
   const meta = quote.metadata || {};
   if (meta.isCrossChain) {
     if (meta.bridgeTool) lines.push(`    Bridge:       ${meta.bridgeTool}`);
-    if (meta.executionDuration) {
-      const mins = Math.round(meta.executionDuration / 60);
+    // LiFi uses executionDuration; Relay uses estimatedTimeSeconds.
+    const durationSec = meta.executionDuration ?? meta.estimatedTimeSeconds;
+    if (durationSec) {
+      const mins = Math.round(durationSec / 60);
       lines.push(`    Est. Time:    ${mins < 1 ? '< 1 min' : `~${mins} min`}`);
     }
     if (meta.feeCosts?.length) {
@@ -962,6 +1046,13 @@ export function buildTradingCommands(deps = {}) {
       const maxAutoSlippage = options['max-auto-slippage'];
       const swapMode = options['swap-mode'] || 'exactIn';
       const amountUnit = options['amount-unit'];
+      const aggregatorFilter = options.aggregator;
+      if (aggregatorFilter && !['lifi', 'relay', 'jupiter', 'okx'].includes(aggregatorFilter)) {
+        throw new CommandError(
+          `Invalid --aggregator: "${aggregatorFilter}". Use one of: lifi, relay, jupiter, okx.`,
+          'INVALID_AGGREGATOR'
+        );
+      }
 
       if (!chain || !from || !to || !amount) {
         throw new CommandError(`
@@ -985,6 +1076,8 @@ OPTIONS:
   --auto-slippage           Enable auto slippage calculation
   --max-auto-slippage <pct> Max auto slippage when auto-slippage enabled
   --swap-mode <mode>        exactIn (default) or exactOut
+  --aggregator <name>       Force a specific aggregator (lifi, relay, jupiter, okx).
+                            Filters the quote list client-side; errors if none match.
 
 EXAMPLES:
   nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
@@ -997,13 +1090,13 @@ EXAMPLES:
 
 CROSS-CHAIN NOTES (when using --to-chain):
   Supported combos:
-    native → native (ETH <-> SOL) — requires $5+ per trade
+    native → native (ETH <-> SOL)
     USDC → USDC (both directions)
     USDC → native (USDC → ETH or SOL)
     native → USDC (ETH/SOL → USDC)
     non-native → non-native — not supported (use USDC as intermediate)
-  Bridge provider: Li.Fi
-  Typical bridge time: 1-5 minutes
+  Bridge providers: Li.Fi or Relay (selected automatically based on best price)
+  Typical bridge time: seconds to a few minutes (Relay is usually faster)
 `, 'MISSING_ARGS');
       }
 
@@ -1167,10 +1260,8 @@ CROSS-CHAIN NOTES (when using --to-chain):
         };
         if (isCrossChain) {
           params.toChainIndex = toChainConfig.index;
-          // Opt out of Relay aggregator: CLI bypasses backend /execute so the
-          // Redis aggregator hint is never set, and /bridge/status defaults to
-          // LiFi — polling a Relay txHash there returns NOT_FOUND.
-          params.disabledAggregators = 'relay';
+          // Relay and LiFi are both first-class cross-chain aggregators; backend picks per quote.
+          // bridge-status auto-detects which aggregator produced a tx via the local tx record.
           if (toWallet) {
             params.toWalletAddress = toWallet;
             log(`  Destination wallet: ${toWallet}`);
@@ -1199,6 +1290,22 @@ CROSS-CHAIN NOTES (when using --to-chain):
           throw new CommandError(msg, 'NO_QUOTES');
         }
 
+        // Client-side filter: if --aggregator is passed, drop everything else.
+        // Done client-side because the backend's aggregator-selection knob
+        // (disabledAggregators) silently accepts unknown values, so a server
+        // filter would mask typos. This way we own the validation.
+        if (aggregatorFilter) {
+          const matching = response.quotes.filter(q => q.aggregator === aggregatorFilter);
+          if (!matching.length) {
+            const seen = [...new Set(response.quotes.map(q => q.aggregator))].join(', ') || 'none';
+            throw new CommandError(
+              `No quotes from aggregator "${aggregatorFilter}" for this pair. Backend returned: ${seen}.`,
+              'AGGREGATOR_NOT_AVAILABLE'
+            );
+          }
+          response.quotes = matching;
+        }
+
         log('');
         response.quotes.forEach((q, i) => log(formatQuote(q, i)));
 
@@ -1217,7 +1324,8 @@ CROSS-CHAIN NOTES (when using --to-chain):
           log(`  Pin #1:  nansen trade execute --quote ${quoteId} --quote-index 0`);
         }
 
-        if (response.quotes[0]?.approvalAddress && !isNativeToken(response.quotes[0]?.inputMint)) {
+        const firstQuote = response.quotes[0];
+        if (firstQuote?.approvalAddress && firstQuote.approvalAddress !== '' && !isNativeToken(firstQuote.inputMint)) {
           log(`\n  Warning: This token swap requires an ERC-20 approval step.`);
           log(`    The execute command will handle this automatically.`);
         }
@@ -1241,6 +1349,7 @@ CROSS-CHAIN NOTES (when using --to-chain):
       const quoteId = options.quote || options['quote-id'] || args[0];
       const walletName = options.wallet;
       const noSimulate = flags['no-simulate'];
+      const gasless = Boolean(flags.gasless);
 
       if (!quoteId) {
         throw new CommandError(`Usage: nansen trade execute --quote <quoteId> [options]
@@ -1249,6 +1358,7 @@ OPTIONS:
   --quote <id>              Quote ID from 'nansen quote'
   --wallet <name>           Wallet name (default: default wallet)
   --no-simulate             Skip pre-broadcast simulation
+  --gasless                 Relay-only: have Relay's solver pay gas (no WalletConnect)
 
 EXAMPLES:
   nansen trade execute --quote 1708900000000-abc123`, 'MISSING_ARGS');
@@ -1346,6 +1456,22 @@ EXAMPLES:
             continue;
           }
 
+          const isRelay = currentQuote.aggregator === 'relay';
+          if (gasless) {
+            if (!isRelay) {
+              throw new CommandError(
+                `--gasless is only supported for Relay quotes. Selected quote ${quoteName} is from "${currentQuote.aggregator}". Re-run with --quote-index to pin a Relay quote, or omit --gasless.`,
+                'GASLESS_UNSUPPORTED_AGGREGATOR'
+              );
+            }
+            if (isWalletConnect) {
+              throw new CommandError(
+                'Gasless swaps are not supported via WalletConnect (mobile wallets typically auto-broadcast, breaking the gasless flow). Use a local or Privy wallet.',
+                'GASLESS_UNSUPPORTED_WALLET'
+              );
+            }
+          }
+
           log(`\nExecuting trade on ${chainConfig.name}...`);
           if (endIndex - startIndex > 1) {
             log(`  Trying quote ${qi + 1}/${allQuotes.length} (${quoteName})...`);
@@ -1399,7 +1525,8 @@ EXAMPLES:
               }
 
               // Handle approval if needed
-              if (currentQuote.approvalAddress && !isNative) {
+              // Empty-string approvalAddress is Relay's "no approval needed" sentinel — skip.
+              if (currentQuote.approvalAddress && currentQuote.approvalAddress !== '' && !isNative) {
                 const inputAmount = BigInt(currentQuote.inputAmount || currentQuote.inAmount || '0');
                 const existingAllowance = await checkErc20Allowance(
                   chain, currentQuote.inputMint, walletAddress, currentQuote.approvalAddress
@@ -1449,7 +1576,7 @@ EXAMPLES:
               }
 
               // Pre-flight simulation
-              if (!noSimulate) {
+              if (!noSimulate && !gasless) {
                 const sim = await simulateEvmCall(chain, {
                   from: walletAddress,
                   to: currentQuote.transaction.to,
@@ -1587,7 +1714,8 @@ EXAMPLES:
               }
 
               // Handle approval via WalletConnect if needed
-              if (currentQuote.approvalAddress && !isNative) {
+              // Empty-string approvalAddress is Relay's "no approval needed" sentinel — skip.
+              if (currentQuote.approvalAddress && currentQuote.approvalAddress !== '' && !isNative) {
                 const inputAmount = BigInt(currentQuote.inputAmount || currentQuote.inAmount || '0');
                 const existingAllowance = await checkErc20Allowance(
                   chain, currentQuote.inputMint, wcAddress, currentQuote.approvalAddress
@@ -1635,7 +1763,7 @@ EXAMPLES:
               }
 
               // Pre-flight simulation
-              if (!noSimulate) {
+              if (!noSimulate && !gasless) {
                 const txData = currentQuote.transaction;
                 const sim = await simulateEvmCall(chain, {
                   from: wcAddress,
@@ -1700,13 +1828,24 @@ EXAMPLES:
 
                 // Cross-chain: poll bridge status after source tx success
                 if (quoteData.toChain && quoteData.toChain !== quoteData.chain) {
+                  saveTxRecord(wcResult.txHash, {
+                    aggregator: currentQuote.aggregator,
+                    requestId: currentQuote.metadata?.requestId,
+                    fromChain: quoteData.chain,
+                    toChain: quoteData.toChain,
+                  });
                   log(`\n  Cross-chain bridge in progress (${chainConfig.name} → ${resolveChain(quoteData.toChain).name})...`);
                   try {
-                    const bridgeResult = await pollBridgeStatus(wcResult.txHash, quoteData.chain, quoteData.toChain, { log });
-                    log(`\n  ✓ Bridge completed!`);
-                    if (bridgeResult.receiving?.txHash) {
-                      const toChainConfig = resolveChain(quoteData.toChain);
-                      log(`    Destination tx: ${toChainConfig.explorer}${bridgeResult.receiving.txHash}`);
+                    const bridgeResult = await pollBridgeStatus(wcResult.txHash, quoteData.chain, quoteData.toChain, { log, aggregator: currentQuote.aggregator });
+                    if (bridgeResult.substatus === 'REFUNDED') {
+                      log(`\n  ⚠ Bridge refunded — funds returned on source chain.`);
+                      if (bridgeResult.substatusMessage) log(`    Reason: ${bridgeResult.substatusMessage}`);
+                    } else {
+                      log(`\n  ✓ Bridge completed!`);
+                      if (bridgeResult.receiving?.txHash) {
+                        const toChainConfig = resolveChain(quoteData.toChain);
+                        log(`    Destination tx: ${toChainConfig.explorer}${bridgeResult.receiving.txHash}`);
+                      }
                     }
                   } catch (bridgeErr) {
                     log(`\n  Bridge status: ${bridgeErr.message}`);
@@ -1752,7 +1891,8 @@ EXAMPLES:
                 }
               }
 
-              if (currentQuote.approvalAddress && !isNative) {
+              // Empty-string approvalAddress is Relay's "no approval needed" sentinel — skip.
+              if (currentQuote.approvalAddress && currentQuote.approvalAddress !== '' && !isNative) {
                 // Check if sufficient allowance already exists
                 const inputAmount = BigInt(currentQuote.inputAmount || currentQuote.inAmount || currentQuote.transaction?.value || '0');
                 const existingAllowance = await checkErc20Allowance(
@@ -1808,7 +1948,7 @@ EXAMPLES:
               // Pre-flight simulation (EVM only) — catch logic reverts before spending gas
               // Runs AFTER approval so eth_call sees the current allowance state
               // Simulates WITHOUT gas limit to check swap logic; gas re-estimation is separate
-              if (!noSimulate) {
+              if (!noSimulate && !gasless) {
                 const txData = currentQuote.transaction;
                 const sim = await simulateEvmCall(chain, {
                   from: walletAddress,
@@ -1851,13 +1991,35 @@ EXAMPLES:
               );
             }
 
-            log('  Broadcasting...');
+            log(gasless ? '  Forwarding to Relay solver (gasless)...' : '  Broadcasting...');
             const execParams = {
               signedTransaction,
               chain,
-              simulate: !noSimulate,
+              simulate: !noSimulate && !gasless,
             };
-            if (requestId) execParams.requestId = requestId;
+            // The backend's /execute schema is strict; sending fields it doesn't expect
+            // for the (chain × aggregator × gasless) combination causes 502s or
+            // "Unrecognized keys" rejections. The matrix we've validated against the
+            // live backend:
+            //   - EVM signed (any aggregator): no extra fields. requestId/aggregator
+            //     trigger schema errors.
+            //   - Solana signed (Jupiter/OKX): include requestId for Jupiter Ultra
+            //     intent resolution.
+            //   - Solana signed (Relay): omit requestId — backend tries to look it up
+            //     as a Jupiter intent and 502s.
+            //   - Gasless (EVM): aggregator + gasless + steps + requestId.
+            //   - Gasless (Solana): currently rejected by the backend ("Unrecognized
+            //     keys"); we still send the gasless envelope and let the backend
+            //     surface the error so users notice when support lands.
+            if (gasless) {
+              execParams.aggregator = 'relay';
+              execParams.gasless = true;
+              const gaslessRequestId = requestId || currentQuote.metadata?.requestId;
+              if (gaslessRequestId) execParams.requestId = gaslessRequestId;
+              if (currentQuote.metadata?.steps) execParams.steps = currentQuote.metadata.steps;
+            } else if (requestId && !isRelay) {
+              execParams.requestId = requestId; // Solana Jupiter Ultra
+            }
 
             const result = await executeTransaction(execParams);
 
@@ -1900,13 +2062,27 @@ EXAMPLES:
 
               // Cross-chain: poll bridge status after source tx success
               if (quoteData.toChain && quoteData.toChain !== quoteData.chain) {
+                saveTxRecord(txId, {
+                  aggregator: currentQuote.aggregator,
+                  requestId: currentQuote.metadata?.requestId,
+                  fromChain: quoteData.chain,
+                  toChain: quoteData.toChain,
+                });
+                if (isRelay && currentQuote.metadata?.requestId) {
+                  log(`    Relay:       https://relay.link/transaction/${currentQuote.metadata.requestId}`);
+                }
                 log(`\n  Cross-chain bridge in progress (${chainConfig.name} → ${resolveChain(quoteData.toChain).name})...`);
                 try {
-                  const bridgeResult = await pollBridgeStatus(txId, quoteData.chain, quoteData.toChain, { log });
-                  log(`\n  ✓ Bridge completed!`);
-                  if (bridgeResult.receiving?.txHash) {
-                    const toChainConfig = resolveChain(quoteData.toChain);
-                    log(`    Destination tx: ${toChainConfig.explorer}${bridgeResult.receiving.txHash}`);
+                  const bridgeResult = await pollBridgeStatus(txId, quoteData.chain, quoteData.toChain, { log, aggregator: currentQuote.aggregator });
+                  if (bridgeResult.substatus === 'REFUNDED') {
+                    log(`\n  ⚠ Bridge refunded — funds returned on source chain.`);
+                    if (bridgeResult.substatusMessage) log(`    Reason: ${bridgeResult.substatusMessage}`);
+                  } else {
+                    log(`\n  ✓ Bridge completed!`);
+                    if (bridgeResult.receiving?.txHash) {
+                      const toChainConfig = resolveChain(quoteData.toChain);
+                      log(`    Destination tx: ${toChainConfig.explorer}${bridgeResult.receiving.txHash}`);
+                    }
                   }
                 } catch (bridgeErr) {
                   log(`\n  Bridge status: ${bridgeErr.message}`);
@@ -1950,8 +2126,13 @@ EXAMPLES:
       const fromChain = options['from-chain'] || args[1];
       const toChain = options['to-chain'] || args[2];
 
+      const aggregatorOverride = options.aggregator;
+      if (aggregatorOverride && aggregatorOverride !== 'lifi' && aggregatorOverride !== 'relay') {
+        throw new CommandError(`Invalid --aggregator: "${aggregatorOverride}". Use "lifi" or "relay".`, 'INVALID_AGGREGATOR');
+      }
+
       if (!txHash || !fromChain || !toChain) {
-        throw new CommandError(`Usage: nansen trade bridge-status --tx-hash <hash> --from-chain <chain> --to-chain <chain>
+        throw new CommandError(`Usage: nansen trade bridge-status --tx-hash <hash> --from-chain <chain> --to-chain <chain> [--aggregator <lifi|relay>]
 
 Check the status of a cross-chain bridge transaction.
 
@@ -1959,15 +2140,28 @@ OPTIONS:
   --tx-hash <hash>          Source chain transaction hash
   --from-chain <chain>      Source chain (solana or base)
   --to-chain <chain>        Destination chain (solana or base)
+  --aggregator <name>       lifi or relay. Overrides auto-detection from the
+                            local tx record. Use this when polling from a
+                            different machine or after the record has expired.
 
 EXAMPLES:
-  nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana`, 'MISSING_ARGS');
+  nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana
+  nansen trade bridge-status --tx-hash 0xabc... --from-chain base --to-chain solana --aggregator relay`, 'MISSING_ARGS');
       }
 
       try {
-        const status = await getBridgeStatus(txHash, fromChain, toChain);
+        // Resolution order: explicit --aggregator flag → local tx record → backend
+        // default (LiFi). The override matters when polling from a fresh machine
+        // or after the 30-day record TTL expires.
+        const txRecord = loadTxRecord(txHash);
+        const aggregator = aggregatorOverride || txRecord?.aggregator;
+        const status = await getBridgeStatus(txHash, fromChain, toChain, { aggregator });
         log(`\nBridge Status: ${status.status || 'unknown'}`);
-        if (status.substatus) log(`  Substatus:   ${status.substatus}`);
+        if (status.substatus === 'REFUNDED') {
+          log(`  ⚠ REFUNDED — funds returned on source chain`);
+        } else if (status.substatus) {
+          log(`  Substatus:   ${status.substatus}`);
+        }
         if (status.substatusMessage) log(`  Message:     ${status.substatusMessage}`);
         if (status.tool) log(`  Bridge:      ${status.tool}`);
         if (status.sending?.txHash) {
@@ -1982,7 +2176,15 @@ EXAMPLES:
           if (status.receiving.amount) log(`    Amount:    ${status.receiving.amount}`);
           if (status.receiving.txLink) log(`    Explorer:  ${status.receiving.txLink}`);
         }
-        if (status.lifiExplorerLink) log(`  Li.Fi:       ${status.lifiExplorerLink}`);
+        const explorerLink = status.lifiExplorerLink || status.relayExplorerLink || status.explorerLink;
+        if (explorerLink) log(`  Explorer:    ${explorerLink}`);
+        if (aggregator === 'relay' && txRecord?.requestId) {
+          log(`  Relay:       https://relay.link/transaction/${txRecord.requestId}`);
+        } else if (aggregator === 'relay') {
+          // No local record (cross-machine / expired). Surface the explorer
+          // by tx hash so users can still cross-reference manually.
+          log(`  Relay:       https://relay.link/transaction/${txHash}`);
+        }
         log('');
       } catch (err) {
         if (err instanceof CommandError) throw err;

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;