> For the complete documentation index, see [llms.txt](https://docs.nansen.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nansen.ai/cli.md).

# Nansen CLI

### Overview

The Nansen CLI (`nansen-cli`) is a command-line interface for the Nansen API. Research commands return structured JSON by default. Login and other operational commands also support human-readable output.

```bash
npm install -g nansen-cli
```

Or run without installing:

```bash
npx nansen-cli help
```

Source code: [github.com/nansen-ai/nansen-cli](https://github.com/nansen-ai/nansen-cli)

### Authentication

First confirm that the CLI is installed:

```bash
nansen --version
```

`--version` needs no credential. Use version 2.0.0 or newer for browser login.

Browser login is enabled in production. Plain `nansen login` opens a browser and asks you to approve the CLI for your Nansen account. Check the displayed code, account, client, and requested access before approving. The CLI then verifies the account and saves a renewable session in your operating system's credential store. You do not need to copy an API key. Sign in with email and password or Google. Apple sign-in is not supported by this flow.

```bash
nansen login
```

If the CLI cannot open a browser on the same machine, start the approval flow without launching one automatically:

```bash
nansen login --no-browser
```

Open the displayed link on another device and approve the matching code. The terminal does not need an inbound callback, but it still needs access to a supported, unlocked credential store.

Browser login requires Nansen CLI 2.0 or newer. The initial release is qualified only for macOS on Apple silicon, a local Terminal in a GUI login session, an unlocked login Keychain, and a local home directory. Background agents, SSH sessions, and network or synchronized home directories are not qualified. Linux remote-terminal qualification is pending, and Windows is not included in the initial release. API-key commands remain available on those systems.

If Keychain is locked, unlock it and retry. Repeating browser approval does not repair credential-store access. See the [browser-login recovery guide](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md) for storage, renewal, and uncertain logout failures.

Check which credential the CLI will use, then verify it against the API:

```bash
nansen auth status
nansen account
```

`auth status` is an offline check. It labels saved account and expiry details as cached and unverified. `account` is the free live API check.

Ordinary commands renew a selected browser session automatically without opening the browser. If renewal is rejected or its result is uncertain, run a fresh `nansen login`.

Existing API keys still work for direct commands and automation:

```bash
export NANSEN_API_KEY=your-api-key
```

`NANSEN_API_KEY` takes priority over a saved browser session. If it is set when you complete browser login, the CLI saves the new session but continues using the environment key until you unset it.

When upgrading from CLI 1.x, note that plain `nansen login` no longer saves an environment key or prompts for an API key. Direct commands using `NANSEN_API_KEY` need no migration. To save a key, use an explicit legacy mode: `--human`, `--api-key`, or `--api-key-stdin`.

`nansen login --human` saves `NANSEN_API_KEY` when the variable is set. Unset it first to enter the key through a masked interactive prompt:

```bash
unset NANSEN_API_KEY
nansen login --human
```

For automation, pipe a key from your secret manager or redirect a protected key file:

```bash
nansen login --api-key-stdin --json < /path/to/protected-api-key
```

`nansen login --api-key <key>` also remains available, but the key may be recorded in shell history. Plain `nansen login` never copies `NANSEN_API_KEY` into saved configuration. Failed or cancelled browser login preserves the previously saved local credential. A lost final response is not proof that the server issued no session; follow the recovery guide if approval completed but login did not finish locally.

To sign out:

```bash
nansen logout
```

Logout removes saved API authentication and attempts to revoke a saved browser session. It does not unset environment variables, remove wallets or wallet passwords, revoke independently managed API keys, or sign out other devices. Local removal, a server retirement receipt, and API rejection are separate outcomes, so revocation may not take effect immediately. If the credential store is locked or remote retirement is unconfirmed, follow the recovery guide and treat the session as potentially usable.

### Quick Start

```bash
# Trending tokens on Solana
nansen research token screener --chain solana --timeframe 24h

# Smart Money flows
nansen research smart-money netflow --chain solana

# Profile a wallet
nansen research profiler balance --address 0x28c6c06298d514db089934071355e5743bf21d60 --chain ethereum

# Search for an entity
nansen research search "Vitalik Buterin" --type entity
```

### Schema Discovery

The CLI is fully self-documenting via `nansen schema`. This requires no API key and returns a machine-readable JSON reference of all commands, options, return fields, and supported chains.

```bash
nansen schema --pretty                    # Full schema
nansen schema smart-money --pretty        # Single command group
```

Example: query supported chains:

```bash
nansen schema | jq '.supportedChains'
```

Agents should use `nansen schema` as the source of truth for available commands and options.

### Output Format

Research commands use this JSON envelope by default. `--table`, `--format csv`, `--fields` and `--stream` change the output shape:

```json
{
  "success": true,
  "data": { ... }
}
```

Research errors include a machine-readable code:

```json
{
  "success": false,
  "error": "Invalid API key",
  "code": "UNAUTHORIZED",
  "status": 401
}
```

Key error codes: `UNAUTHORIZED`, `CREDITS_EXHAUSTED`, `RATE_LIMITED`, `INVALID_ADDRESS`, `UNSUPPORTED_FILTER`. These are the CLI's own codes: it maps the HTTP API's lowercase `code` values onto them, so they differ from the codes listed in [Error Handling](/getting-started/error-handling.md).

Human login output is not a single JSON response. `nansen login --json` and non-TTY login emit newline-delimited JSON events: normally a pending approval event followed by one terminal result. A preflight error emits only the terminal error. `nansen auth status` reports cached selection without contacting the API.

### Tips for AI Agents

**Use `schema` for self-discovery.** Agents should call `nansen schema` at the start of a session to learn available commands, options, and supported chains -- it costs zero credits.

**Use `--fields` to reduce response size.** Large JSON responses waste agent context tokens.

```bash
nansen research smart-money netflow --chain solana --fields token_symbol,net_flow_usd --limit 10
```

**Use `--stream` for line-oriented tools.** Emits each returned record as an NDJSON line. This is an output format, not a guarantee that the API response is fetched without buffering.

```bash
nansen research token dex-trades --chain ethereum \
  --token 0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9 \
  --limit 100 --stream
```

**Budget credits and payments.** Research costs vary by endpoint. `schema`, `help`, login verification and `account` are free. A supported HTTP 402 challenge can trigger automatic x402 payment from a configured wallet, subject to wallet authorization, payment policy and spending limits. The paid retry sends only the payment credential; it does not top up account credits or change saved authentication. Authentication, authorization and renewal failures never trigger payment. If a command returns `CREDITS_EXHAUSTED`, stop and ask the user how to proceed. See the [payment behavior](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#commands-and-selection).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nansen.ai/cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.