--- name: nansen-trading description: Execute DEX swaps on Solana or Base (including cross-chain bridges) and Hyperliquid perpetual trades. Use when buying or selling a token, getting a swap quote, executing a trade, or opening/closing/managing a perp position. metadata: openclaw: requires: env: - NANSEN_WALLET_PASSWORD bins: - nansen primaryEnv: NANSEN_API_KEY install: - kind: node package: nansen-cli bins: [nansen] allowed-tools: Bash(nansen:*) --- ## Authentication Nansen account API calls accept a selected `nansen:api` browser session or conventional API key with the same permissions. `NANSEN_API_KEY` takes precedence; optional `primaryEnv` preserves configured-key injection. Run `nansen auth status` for offline selection. Cached access expiry alone permits automatic renewal during an authorized task. Stop on anonymous selection, invalid state, blocked/uncertain renewal or actual auth failure; never drop a credential or fall back to anonymous x402 payment. Browser login does not grant wallet signing, privileged service identity or a persistent MCP integration key. Preserve all confirmation, signing, sanctions and geographic checks below. Browser login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope). # 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. ## Quote ```bash nansen trade quote \ --chain solana \ --from SOL \ --to USDC \ --amount 1000000000 ``` 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 ```bash nansen trade execute --quote nansen trade execute --quote --dry-run # preview only, nothing is broadcast nansen trade execute --quote --yes # skip the confirmation prompt ``` **`--dry-run`** runs every sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints the trade that *would* be sent (chain, tokens, amounts, recipient, approval, fees); and stops before wallet credentials or signing. No wallet password is needed, the quote is not consumed, and the command exits 0. Real execution still resolves and revalidates the live signer. On Base, preview also reads the current token allowance and runs the pre-broadcast revert simulation when no approval is outstanding. **Confirmation.** When stdin is an interactive terminal, `execute` prints the plan and asks `Broadcast this transaction? [y/N]` before broadcasting. Answering anything but `y`/`yes` aborts with exit code 1 and nothing signed. Pass `--yes` (`-y`), or set `NANSEN_YES=1`, to skip the question. **Agents and CI are unaffected:** when stdin is *not* a terminal (a pipe, a CI job, an agent shell) the command proceeds without prompting, exactly as before. `--yes` is accepted there and is simply a no-op, so it is safe to always pass it. The same flags and rules apply to `nansen bridge execute`. ### Exit codes (`trade execute`, `bridge execute`) | Code | Meaning | |------|---------| | `0` | Broadcast succeeded, or the dry run completed | | `1` | Declined at the confirmation prompt, or the execution failed | ## Cross-Chain Swap Bridge tokens between Solana and Base using `--to-chain`: ```bash nansen trade quote \ --chain base \ --to-chain solana \ --from USDC \ --to USDC \ --amount 1000000 ``` For Solana↔Base bridges, the destination wallet address is auto-derived from your wallet (which stores both EVM and Solana keys). Override with `--to-wallet
` if needed. Note: you need gas on the **source** chain to submit the initial transaction (e.g. SOL for Solana→Base, ETH for Base→Solana). ## Bridge Status After executing a cross-chain swap, the CLI polls bridge status automatically. To check manually: ```bash nansen trade bridge-status --tx-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 nansen trade limit-order update --order --trigger-price 85 ``` `--slippage-bps` is basis points (`300` = 3%, `100` = 1%); omit for auto. ## Agent pattern ```bash # Pipe quote ID directly into execute quote_id=$(nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000 2>&1 | grep "Quote ID:" | awk '{print $NF}') nansen trade execute --quote "$quote_id" ``` ## Common Token Addresses | Token | Chain | Address | |-------|-------|---------| | SOL | Solana | `So11111111111111111111111111111111111111112` | | USDC | Solana | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | | ETH | Base | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` | | USDC | Base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | ## Amounts By default, `--amount` accepts **integer base units** (lamports, wei, etc). Use `--amount-unit token` for human-readable token amounts, or `--amount-unit usd` to specify a USD value — the CLI resolves price and decimals automatically. ```bash # Base units (default) nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000 # Token units (0.5 SOL = 500000000 lamports, resolved automatically) nansen trade quote --chain solana --from SOL --to USDC --amount 0.5 --amount-unit token # USD amount ($50 worth of SOL, price resolved via Nansen search API) nansen trade quote --chain solana --from SOL --to USDC --amount 50 --amount-unit usd ``` | Token | Decimals | 1 token = | |-------|----------|-----------| | SOL | 9 | `1000000000` | | ETH | 18 | `1000000000000000000` | | USDC | 6 | `1000000` | If the user says "$20 worth of X", use `--amount-unit usd` directly — no manual conversion needed. The CLI fetches the current price and converts for you. ## Flags ### `trade quote` flags | Flag | Purpose | |------|---------| | `--chain` | Source chain: `solana` or `base` | | `--to-chain` | Destination chain for cross-chain swap (omit for same-chain) | | `--from` | Source token (symbol or address) | | `--to` | Destination token (symbol or address, resolved against destination chain) | | `--amount` | Amount in base units (integer), or token/USD units with `--amount-unit` | | `--amount-unit` | `token` for token units (e.g. 0.5 SOL), `usd` for USD (e.g. 50), `base` = default | | `--wallet` | Wallet name (default: default wallet) | | `--to-wallet` | Destination wallet address (auto-derived for cross-chain if omitted) | | `--slippage` | Slippage tolerance as decimal (e.g. 0.03) | | `--auto-slippage` | Enable auto slippage calculation | | `--max-auto-slippage` | Max auto slippage when `--auto-slippage` is enabled | | `--swap-mode` | `exactIn` (default) or `exactOut` | ### `trade execute` flags | Flag | Purpose | |------|---------| | `--quote` | Quote ID from `trade quote` | | `--wallet` | Wallet name (default: default wallet) | | `--quote-index` | Pin a specific quote by index (0-based) when multiple quotes were returned | | `--no-simulate` | Skip pre-broadcast simulation | | `--dry-run` | Validate and print what would be sent, then stop. Nothing is signed or broadcast | | `--yes`, `-y` | Skip the confirmation prompt (same as `NANSEN_YES=1`); no-op when stdin is not a terminal | ### `trade bridge-status` flags | Flag | Purpose | |------|---------| | `--tx-hash` | Source tx hash | | `--from-chain` | Source chain (for bridge-status) | | `--to-chain` | Destination chain (for bridge-status) | ## Environment Variables | Var | Purpose | |-----|---------| | `NANSEN_WALLET_PASSWORD` | **Required for `trade execute`.** Wallet encryption password — persisted in `~/.nansen/.env`. Source before executing: `source ~/.nansen/.env && nansen trade execute ...` | | `NANSEN_API_KEY` | API key (also set via explicit `nansen login --human`; browser sessions are not wallet or RPC keys) | | `NANSEN_YES` | Set to `1` to skip the `execute` confirmation prompt, like `--yes` | > **Agents:** Never hold a wallet password only in session memory. If `NANSEN_WALLET_PASSWORD` is not in `~/.nansen/.env`, follow the setup flow in the nansen-wallet-manager skill Password Policy to generate and persist one before proceeding. ## Notes - Quotes expire after ~1 hour. If execute fails, get a fresh quote. - A wallet is required even for quotes (the API builds sender-specific transactions). - Compliance screen: `trade quote` and `trade execute` check the signing wallet (and any distinct `--to-wallet` destination) against the compliance blocklist through the Nansen API before requesting a quote or signing — the same fail-closed check `bridge` and `perp` run. A flagged address aborts with code `SANCTIONED`; if the screening call itself fails the command aborts with `SCREENING_UNAVAILABLE`. Nothing is signed or broadcast in either case. - ERC-20 swaps may require an approval step — execute handles this automatically. # Perp Trading Use `nansen perp` for Hyperliquid perpetual trading. Uses the same wallet and `NANSEN_WALLET_PASSWORD` as DEX trading; requires an **EVM** wallet. **Perp orders are irreversible once signed.** Subcommands: `order`, `cancel`, `close`, `leverage`, `positions`, `orders`, `account`, `meta`. The asset is selected with `--coin` (e.g. `BTC`, `ETH`); `--symbol` is accepted as an alias. List tradable assets and their max leverage with `nansen perp meta` (use `--filter ` or `--all` to see beyond the first 20). ## Open a position ```bash # Limit long: 0.1 ETH at $1600 nansen perp order --coin ETH --side buy --size 0.1 --price 1600 --type limit # Market short with optional take-profit / stop-loss nansen perp order --coin BTC --side sell --size 0.001 --price 95000 --type market \ --take-profit 90000 --stop-loss 98000 ``` - `--side`: `buy`/`long` to open a long, `sell`/`short` to open a short. - `--size`: position size in base asset units (positive number). - `--price`: limit price (or mark price for market orders). - `--type`: `limit` (default) or `market`. `--tif`: `Gtc` (default), `Ioc`, `Alo`. - `--slippage`: decimal in `[0,1]` for market orders (default `0.03` = 3%). On success the command prints the Hyperliquid order id (`oid`) and the fill (size @ avg price). A resting (unfilled) order also prints a ready-to-run `nansen perp cancel --coin --oid `. Attached take-profit/stop-loss legs are labelled and each print their own `oid`. ## Close / cancel ```bash # Close: sell to close a long, buy to close a short (validated against your open position) nansen perp close --coin ETH --size 0.1 --price 1600 --side sell # Cancel a resting order by id nansen perp cancel --coin ETH --oid 123456 ``` ## Leverage, transfers & account ```bash nansen perp leverage --coin ETH --leverage 5 --margin-type cross # or isolated nansen perp transfer --direction spot-to-perp --amount 25 # or perp-to-spot nansen perp positions nansen perp account # account value, unrealized PnL, margin used, withdrawable, spot USDC ``` `--leverage` must be a whole integer and is capped at the asset's maximum (see `perp meta`). **Spot vs Perps:** perp trading draws from the **Perps** balance, but USDC sent to a wallet via Hyperliquid's **Send** lands in **Spot** (and shows as `Spot USDC` in `perp account`). Move it across with `perp transfer --direction spot-to-perp --amount ` before trading. (Deposits via the bridge land in Perps directly.) ## Source - npm: https://www.npmjs.com/package/nansen-cli - GitHub: https://github.com/nansen-ai/nansen-cli Browser login uses `nansen:api` with the same account API permissions as an API key, subject to existing plan/account/endpoint checks. Trading still requires a separately configured wallet and its signing authorization. Hosted simulation uses the selected credential only on the matching trusted Nansen API origin; arbitrary RPC endpoints never receive Nansen credentials.