back
loading skill details...
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.
---
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
```bash
# --amount is always in token units (e.g. 1 = 1 SOL, 80 = 80 USDC)
nansen trade limit-order create \
--from SOL --to USDC \
--amount 1 \
--trigger-mint SOL --trigger-condition below --trigger-price 80
# with explicit slippage and expiry
nansen trade limit-order create \
--from SOL --to USDC \
--amount 1.5 \
--trigger-mint SOL --trigger-condition above --trigger-price 200 \
--slippage-bps 300 \
--expires 7d
```
Required flags: `--from`, `--to`, `--amount`, `--trigger-mint`,
`--trigger-condition` (`above` or `below`), `--trigger-price` (USD).
Key options:
- `--amount` is always in **token units** (human-readable). `1.5` means 1.5 SOL,
`80` means 80 USDC. There is no base-unit mode and no amount-unit override flag —
do not pass one.
- `--slippage-bps <bps>` — basis points, integer 0–10000 (`300` = 3%, `100` = 1%).
Omit for auto.
- `--expires` accepts `24h`, `7d`, `30d` (default), or an epoch-ms timestamp.
- `--wallet <name>` or `--wallet walletconnect` (alias `wc`) to pick a non-default
wallet.
Constraints (all enforced server-side — surface errors to the user as-is):
- Minimum order value (~$10 last seen). Below this the API rejects the order.
- `--from` and `--to` must be valid Solana mint addresses or supported symbols
(SOL, USDC, USDT, etc.). Resolve unknown tokens with `nansen research search`.
- Tokens with transfer-hook extensions (e.g. some pump.fun tokens) are rejected
at create time.
### List
```bash
nansen trade limit-order list # default
nansen trade limit-order list --state active # only open
nansen trade limit-order list --state past # filled or cancelled
nansen trade limit-order list --mint <mintAddr> # filter by token
nansen trade limit-order list --limit 50 --offset 0 --dir desc
```
Options: `--state active|past`, `--mint <addr>`, `--limit <n>` (default 20),
`--offset <n>`, `--sort <field>`, `--dir asc|desc` (default `desc`),
`--wallet <name>`.
### Cancel
```bash
nansen trade limit-order cancel --order <orderId>
```
Cancelling submits a withdrawal transaction; surface the tx signature from the
CLI output so the user can verify on Solscan.
### Update
```bash
nansen trade limit-order update --order <orderId> --trigger-price 85
nansen trade limit-order update --order <orderId> --slippage-bps 100
```
Only `--trigger-price` and `--slippage-bps` can be updated. To change size or
the token pair, cancel and re-create. Auto slippage can only be set at creation
time (by omitting `--slippage-bps` from `create`); `update` cannot revert a
fixed slippage back to auto.
## Non-Solana Chains: Alert-Based Settlement Signal
`nansen-cli` does not currently place native limit orders on EVM chains. The
supported approximation is:
1. Place the resting limit order on the venue or product that supports it (CEX,
DEX limit-order product, aggregator). **The venue handles the price
trigger.**
2. Use the same wallet as the settlement wallet.
3. Create a `common-token-transfer` smart alert scoped to wallet + chain +
token + side. The alert fires **after** the trade settles — i.e. once the
bought/sold token actually moves on-chain — as a fill-detected signal.
How the two mechanisms compose:
1. **Price hits target → the venue's limit order executes.** This is the
trigger. `nansen-cli` is not involved.
2. **Token arrives in the wallet → the smart alert pings.** This is the
settlement confirmation. The alert never sees the price trigger; it only
sees the resulting transfer.
This is a best-effort settlement signal, not authoritative order tracking. It
does **not** expose order-state polling, partial-fill progress, `triggeredAt`,
`fillPercent`, remaining size, or canonical filled/cancelled history.
### Buy-Side Settlement Alert
```bash
nansen alerts create \
--name 'Settlement signal: buy PEPE on trading wallet' \
--type common-token-transfer \
--chains ethereum \
--events buy \
--subject address:0xYourWallet \
--token 0x6982508145454ce325ddbe47a25d4ec3d2311933:ethereum \
--telegram 5238612255
```
### Sell-Side Settlement Alert
```bash
nansen alerts create \
--name 'Settlement signal: sell USDC on trading wallet' \
--type common-token-transfer \
--chains base \
--events sell \
--subject address:0xYourWallet \
--token 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913:base \
--telegram 5238612255
```
### Alert Hardening
- `--usd-min <amount>` to suppress dust fills.
- `--description '<limit price / venue / notes>'` so the alert records intent.
- Do **not** recommend a wallet-wide transfer alert with no token filter — it
overfires.
- Do **not** describe alert delivery as "order filled" or "triggered". The
alert is only evidence that a matching token transfer was observed on the
wallet — not precise fill detection.
- If the venue settles in a way the alerting backend classifies as a generic
transfer rather than `buy`/`sell`, a narrow alert may miss it. Only widen to
`--events buy,receive` or `--events sell,send` if the user accepts broader
matching and the risk of unrelated matches.
## Optional: Belt-and-Braces on Solana
For Solana native limit orders, a companion `common-token-transfer` alert on
the settlement wallet is optional but useful. **It is a settlement
confirmation, not a price trigger.** The limit order itself handles the price
trigger; the alert fires when the bought token actually arrives in the wallet
(or, for sells, when the sold token leaves) — proof the on-chain fill landed,
delivered via Telegram/webhook independently of `trade limit-order list`
polling.
Some venues route fills through programs that the alerting backend may not
classify as `buy`/`sell`, so this is still a best-effort settlement signal,
not authoritative fill detection. Pair with the same `common-token-transfer`
alert shape shown above.
## What to Tell the User
When suggesting a companion alert, be explicit that two different mechanisms
are at work — users routinely conflate them:
- The **limit order** is the price trigger. It executes when the market price
crosses the target.
- The **smart alert** is the settlement confirmation. It pings after the trade
settles on-chain.
Suggested phrasing: _"When your order fills and the token arrives in your
wallet, you'll get a Telegram ping. The price trigger is handled by the limit
order itself — the alert just confirms the fill landed."_
Avoid wording that implies the alert "triggers" the order or that the alert
itself watches price. It does neither.
## Notes
- Chain aliases for alerts: Hyperliquid = `hyperevm`, BSC = `bnb`.
- Use single quotes for names with `$` or special characters.
- For immediate swaps (not price-triggered), use the `nansen-trading` skill.
- For webhook delivery of alerts, pair with `nansen-alerts-webhook-listener`.
## Source
- npm: https://www.npmjs.com/package/nansen-cli
- GitHub: https://github.com/nansen-ai/nansen-cli
don't have the plugin yet? install it then click "run inline in claude" again.
formalized all six required components with explicit decision logic, edge cases (auth expiry, rate limits, transfer-hook tokens, empty results, alert misclassification), external connection setup (nansen_api_key env var, notification channels), and clear outcome signals for all paths.
use this skill when a user wants to place a price-triggered order (buy or sell). solana gets native limit orders via the nansen trading api; other chains fall back to a two-part strategy (resting order placed manually on a venue, plus a settlement signal via smart alert). the skill walks through creation, listing, cancellation, and updates for solana orders, and provides the alert setup for evm chains.
nansen trade limit-order commands and smart alerts. smart alerts are internal-only; external users receive 404 errors.nansen-cli. install via npm install -g nansen-cli or configured in openclaw metadata. provides nansen binary.nansen wallet show <name> or nansen wallet create. supports local, Privy, and WalletConnect wallets. must hold the sell token plus a small amount of SOL for transaction fees.--subject address:0x... in alert creation.So11111111111111111111111111111111111111112 for SOL); evm contract address with chain suffix for alerts (e.g. 0x6982508145454ce325ddbe47a25d4ec3d2311933:ethereum).input: wallet name (or walletconnect), sell token symbol/mint, buy token symbol/mint.
run:
nansen wallet show <wallet-name>
nansen research search <token-symbol> # if symbol unknown
output: wallet balance, keys, and token mint address. surface any "wallet not found" error; instruct user to create via nansen wallet create.
edge case: if wallet holds insufficient sell token or sol for fees, inform user of required balance and halt until topped up.
input: from-token, to-token, amount (in token units), trigger-mint, trigger-condition (above or below), trigger-price (usd), optional slippage-bps (0-10000, integer), optional expiry (24h, 7d, 30d, or epoch-ms timestamp), optional wallet name.
run:
nansen trade limit-order create \
--from <from-token> --to <to-token> \
--amount <amount> \
--trigger-mint <trigger-token> --trigger-condition <above|below> --trigger-price <usd-price> \
--wallet <name>
optional flags:
--slippage-bps <bps> # e.g. 300 = 3%. omit for auto.
--expires <duration> # e.g. 7d, 30d (default). omit for 30d.
output: order id, status (pending/active), trigger conditions, slippage, and expiry timestamp. on first-time create, the cli auto-registers a trading vault and caches a jwt at ~/.nansen/limit-order-auth.json (valid ~23h).
edge cases:
nansen research search or suggest resolved mint address.~/.nansen/limit-order-auth.json is stale (>23h), next create will re-authenticate. user may be prompted to sign again.input: optional state filter (active or past), optional mint filter, optional pagination (limit, offset), optional sorting (field, direction).
run:
nansen trade limit-order list --state <active|past>
or with filters:
nansen trade limit-order list --state active --mint <mint> --limit 50 --offset 0 --dir desc
output: order id, token pair, amount, trigger conditions, current status (pending, active, filled, cancelled), timestamp.
edge case: empty result set means no orders in that state. surface plainly; do not error.
input: order id, new trigger-price (usd) or new slippage-bps (0-10000).
run:
nansen trade limit-order update --order <order-id> --trigger-price <new-price>
or:
nansen trade limit-order update --order <order-id> --slippage-bps <new-bps>
output: updated order details, new trigger price or slippage, confirmation timestamp.
constraints: only --trigger-price and --slippage-bps can be updated. to change size or token pair, cancel and re-create. auto slippage (set by omitting --slippage-bps on create) cannot be reverted via update.
input: order id.
run:
nansen trade limit-order cancel --order <order-id>
output: transaction signature (solana tx hash), status change to cancelled, timestamp.
surface the tx signature so user can verify on solscan (https://solscan.io/).
edge case: if order is already filled or expired, cancel is a no-op and returns the current state.
input: buy or sell side, amount, limit price, settlement wallet.
user places the order manually on the venue or dex that supports limit orders (e.g. uniswap, curve, cex). the venue handles the price trigger; nansen is not involved here.
output: order confirmation from venue.
input: alert name, token (buy or sell side), chain, settlement wallet address, notification channel, optional usd-min threshold, optional description.
buy-side example:
nansen alerts create \
--name 'Settlement signal: buy PEPE on trading wallet' \
--type common-token-transfer \
--chains ethereum \
--events buy \
--subject address:0xYourWallet \
--token 0x6982508145454ce325ddbe47a25d4ec3d2311933:ethereum \
--telegram 5238612255 \
--usd-min 50 \
--description 'limit price 0.00000050, uniswap'
sell-side example:
nansen alerts create \
--name 'Settlement signal: sell USDC on trading wallet' \
--type common-token-transfer \
--chains base \
--events sell \
--subject address:0xYourWallet \
--token 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913:base \
--telegram 5238612255 \
--usd-min 100
output: alert id, status (enabled), token, chain, event types, notification channel.
edge cases:
buy/sell. if user misses fill signals, widen --events to buy,receive or sell,send (accepting broader matches and unrelated false positives).--usd-min to suppress below-threshold transfers.even with native solana limit orders, add a companion common-token-transfer alert to confirm the fill landed on-chain. same alert shapes as non-solana, but scoped to solana chain. this is a settlement confirmation, not a price trigger; the limit order itself handles the trigger.
if user is on solana: use native limit order commands (nansen trade limit-order create|list|cancel|update). optionally add a settlement signal alert as belt-and-braces.
if user is on evm or other non-solana chain: do not use nansen trade limit-order. instead, instruct user to place the resting order on a venue that supports limit orders, then create a common-token-transfer smart alert to signal when the fill settles on-chain.
if user wants to modify an order: if only trigger price or slippage needs to change, use update. if token pair or size must change, cancel the old order and create a new one.
if alert fires multiple times for the same fill: use --usd-min to filter dust, or widen event types only if user accepts the noise.
if native limit order create fails with auth error: jwt in ~/.nansen/limit-order-auth.json may be stale (>23h old). instruct user to delete the file and retry; cli will re-authenticate.
if alert does not fire after order fills: ask user if the settlement happened on a different wallet, different chain, or via a program the backend may not classify as buy/sell. if necessary, widen --events to buy,receive or sell,send.
solana native orders:
solana orders are always returned in token units (human-readable). no base-unit mode.
alerts:
files written: ~/.nansen/limit-order-auth.json (jwt cache, created on first limit-order create, ~23h ttl).
native solana limit order success:
nansen trade limit-order list --state active and sees the order in the list with status active.filled. user can verify via list or polling.non-solana settlement alert success:
cancellation success: user runs nansen trade limit-order cancel --order <id> and receives a solana tx signature. they verify on solscan that the withdrawal transaction settled. order status flips to cancelled in list.
update success: user runs nansen trade limit-order update --order <id> --trigger-price <new-price>, receives confirmation of new price, and can verify via list.