/nansen-limit-orders

name: nansen-limit-orders
description: Guide users through native limit orders on Solana via `nansen trade limit-order create|list|cancel|update`, and the alert-based settlement-signal fallback for chains without native support. Use when a user wants a price-triggered buy or sell.
metadata:
  openclaw:
    requires:
      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).

Limit Orders

Use this skill when the user wants a price-triggered order. There are two distinct paths — pick the one that matches the user's chain:

• **Solana → native limit orders.** `nansen trade limit-order create|list|cancel|update`

places real resting orders through the Nansen trading API. Use these for anything on Solana.

• **Other chains → alert-based approximation.** `nansen-cli` does not yet place

native limit orders on EVM chains. Place the resting order on the venue that supports it (CEX, DEX limit-order product) and create a companion `common-token-transfer` smart alert on the settlement wallet as a best-effort fill signal.

Prerequisites

• A Solana wallet configured in `nansen-cli`: `nansen wallet show <name>` (or

`nansen wallet create` if none exists). Local, Privy, and WalletConnect wallets are all supported for `trade limit-order`.

• The wallet must hold the sell token plus a small amount of SOL for fees.
• For the alert fallback: a notification channel (Telegram chat ID, Slack or

Discord webhook, or generic webhook URL).

• A selected nansen:api browser session or conventional API key for smart alerts; existing endpoint restrictions still apply.
• First-time `trade limit-order create` auto-registers a trading vault and

caches a JWT at `~/.nansen/limit-order-auth.json` for ~23h.

> **Two mechanisms, not one.** The limit order itself is **price-triggered** — > it executes when the market price crosses the target. A companion smart > alert is a **settlement confirmation** — it fires after the trade settles > on-chain (i.e. when the bought token actually arrives in the wallet). They > are independent: the order handles the trigger, the alert tells the user the > fill landed.

Solana: Native Limit Orders

Create

# --amount is always in token units (e.g. 1 = 1 SOL, 80 = 80 USDC)
nansen trade limit-order create \
  --from SOL --to USDC \
  --amount 1 \
  --trigger-mint SOL --trigger-condition below --trigger-price 80

# with explicit slippage and expiry
nansen trade limit-order create \
  --from SOL --to USDC \
  --amount 1.5 \
  --trigger-mint SOL --trigger-condition above --trigger-price 200 \
  --slippage-bps 300 \
  --expires 7d

Required flags: `--from`, `--to`, `--amount`, `--trigger-mint`, `--trigger-condition` (`above` or `below`), `--trigger-price` (USD).

Key options:

• `--amount` is always in **token units** (human-readable). `1.5` means 1.5 SOL,

`80` means 80 USDC. There is no base-unit mode and no amount-unit override flag — do not pass one.

• `--slippage-bps <bps>` — basis points, integer 0–10000 (`300` = 3%, `100` = 1%).

Omit for auto.

• `--expires` accepts `24h`, `7d`, `30d` (default), or an epoch-ms timestamp.
• `--wallet <name>` or `--wallet walletconnect` (alias `wc`) to pick a non-default

wallet.

Constraints (all enforced server-side — surface errors to the user as-is):

• Minimum order value (~$10 last seen). Below this the API rejects the order.
• `--from` and `--to` must be valid Solana mint addresses or supported symbols

(SOL, USDC, USDT, etc.). Resolve unknown tokens with `nansen research search`.

• Tokens with transfer-hook extensions (e.g. some pump.fun tokens) are rejected

at create time.

List

nansen trade limit-order list                    # default
nansen trade limit-order list --state active     # only open
nansen trade limit-order list --state past       # filled or cancelled
nansen trade limit-order list --mint <mintAddr>  # filter by token
nansen trade limit-order list --limit 50 --offset 0 --dir desc

Options: `--state active|past`, `--mint <addr>`, `--limit <n>` (default 20), `--offset <n>`, `--sort <field>`, `--dir asc|desc` (default `desc`), `--wallet <name>`.

Cancel

nansen trade limit-order cancel --order <orderId>

Cancelling submits a withdrawal transaction; surface the tx signature from the CLI output so the user can verify on Solscan.

Update

nansen trade limit-order update --order <orderId> --trigger-price 85
nansen trade limit-order update --order <orderId> --slippage-bps 100

Only `--trigger-price` and `--slippage-bps` can be updated. To change size or the token pair, cancel and re-create. Auto slippage can only be set at creation time (by omitting `--slippage-bps` from `create`); `update` cannot revert a fixed slippage back to auto.

Non-Solana Chains: Alert-Based Settlement Signal

`nansen-cli` does not currently place native limit orders on EVM chains. The supported approximation is:

1. Place the resting limit order on the venue or product that supports it