# Zora CLI

> Build an AI Agent. Trade Coins.

## Getting Started

:::info
These docs cover **@zoralabs/cli v1.1.0**.
:::

### Install

Requires **Node.js 20+**.

```bash
npm install -g @zoralabs/cli@1.1.0
```

Or run any command directly without installing:

```bash
npx @zoralabs/cli@1.1.0 explore
```

### Browse Coins

Start exploring coins immediately — no wallet or API key needed:

```bash
# Top creator coins by market cap
zora explore --sort mcap

# Trending coins
zora explore --sort trending

# New coins
zora explore --sort new
```

### Look Up a Coin

```bash
# By contract address
zora get 0x71e764a744af3fe52f598154e4a15f888737dae5

# By creator name (for creator coins)
zora get creator-coin jakeward
```

Example output:

```
BAGOFUCKS
  Address     0x71e764a744af3fe52f598154e4a15f888737dae5
  Type        post
  Market Cap  $877,476.85
  24h Δ       $189,062.70
  Volume 24h  $13,046.67
  Holders     409
  Creator     jakeward
  Created     6 days ago
```

### Set Up a Wallet

Trading commands (`buy`, `sell`, `send`) require a wallet. Create one:

```bash
# Interactive — choose to create or import
zora setup

# Non-interactive — generate a new wallet
zora setup --create
```

```json
{
  "address": "0xb4a06BdD9e0E60FFE22E4E7590842bfD2069034E",
  "source": "~/.config/zora/wallet.json"
}
```

:::warning
The private key is stored at `~/.config/zora/wallet.json` with restricted permissions. This is the only copy — losing it means losing access to the wallet.
:::

Alternatively, set the `ZORA_PRIVATE_KEY` environment variable:

```bash
export ZORA_PRIVATE_KEY=0x...
```

### Configure an API Key (Optional)

Read-only commands work without an API key but may be rate-limited. Get a key at [zora.co/settings/developer](https://zora.co/settings/developer):

```bash
zora auth configure
# Prompts for your API key

zora auth status --json
```

```json
{
  "authenticated": true,
  "key": "f7c3502c...3458",
  "source": "~/.config/zora/config.json"
}
```

Or set via environment variable:

```bash
export ZORA_API_KEY=your-key-here
```

### Make a Trade

```bash
# Buy with 0.01 ETH
zora buy 0x71e764a744af3fe52f598154e4a15f888737dae5 --eth 0.01

# Get a quote without executing
zora buy 0x71e764a744af3fe52f598154e4a15f888737dae5 --eth 0.01 --quote

# Sell 50% of a position
zora sell 0x71e764a744af3fe52f598154e4a15f888737dae5 --percent 50

# Send ETH to another address
zora send eth --to 0x... --amount 0.1
```

### Check Balances

```bash
# Interactive live-updating view
zora balance

# JSON snapshot
zora balance --json
```

### JSON Mode

Every command supports `--json` for machine-readable output. This is essential for scripting and AI agent integration:

```bash
zora explore --json --sort trending --limit 5
zora get 0x... --json
zora balance --json
```

See the [JSON Mode & Scripting](/guides/json-mode) guide and [AI Agent Integration](/guides/ai-agents) guide for more.

### Next Steps

* [Command Reference](/commands/explore) — detailed docs for every command
* [AI Agent Integration](/guides/ai-agents) — build agents that trade coins
* [JSON Mode & Scripting](/guides/json-mode) — automation patterns
* [Configuration](/guides/configuration) — environment variables and config files


## SKILL.md

import { CopyBox } from "../components/CopyBox";

export const skillUrl = (() => {
  const root =
    typeof import.meta !== "undefined" && import.meta.env?.VITE_SITE_ROOT_URL;
  if (root) return `${root}/skill.md`;
  if (typeof window !== "undefined")
    return `${window.location.origin}/skill.md`;
  return "https://yoursite.com/skill.md";
})();

### Give this to your agent

<CopyBox>
  {`Install the Zora CLI skill from ${skillUrl}`}
</CopyBox>

Or add this one-liner to your `CLAUDE.md`, `.cursorrules`, or agent system prompt:

<CopyBox>
  {`Fetch and follow the Zora CLI skill from ${skillUrl}`}
</CopyBox>

The agent will fetch the skills file at runtime and have full access to the Zora protocol.

### Integration Examples

#### Claude Code

Add to `CLAUDE.md`:

<CopyBox>
  {`Fetch and follow the Zora CLI skill from ${skillUrl}`}
</CopyBox>

Then ask:

```
Find the top trending coins on Zora and analyze their price history
```

#### Cursor

Add to `.cursorrules`:

<CopyBox>
  {`Fetch and follow the Zora CLI skill from ${skillUrl}`}
</CopyBox>

#### Custom Agents

For any tool-use capable LLM, add the skills URL to the system prompt. The agent needs the ability to execute shell commands and parse JSON output.

### Full Skills Reference

The hosted `SKILL.md` contains the following reference.

````markdown
# Zora CLI Skills

You have access to the Zora CLI (`npx @zoralabs/cli`) for interacting with the Zora protocol on Base.
All commands support `--json` for structured output. Always use `--json` for parsing responses.
Trade commands require `--yes` to skip confirmation prompts.

## Environment Variables

- `ZORA_PRIVATE_KEY` — Wallet private key (hex, with or without 0x prefix)
- `ZORA_API_KEY` — API key for higher rate limits (get one at zora.co/settings/developer)

## Read Commands (no wallet needed)

### Browse coins

```bash
npx @zoralabs/cli explore --json --sort <sort> --type <type> --limit <n>
```

Sort: mcap, volume, new, trending, featured
Type: all, creator-coin, post, trend
Returns: `{ "coins": [...], "nextCursor": "..." }`

### Look up a coin

```bash
npx @zoralabs/cli get [creator-coin|trend] <address-or-name> --json
```

Returns: `{ "name", "address", "coinType", "marketCap", "volume24h", "uniqueHolders", "createdAt", "creatorHandle" }`

### Price history

```bash
npx @zoralabs/cli price-history [creator-coin|trend] <address-or-name> --json --interval <1h|24h|1w|1m|ALL>
```

Returns: `{ "coin", "interval", "high", "low", "change", "prices": [{ "timestamp", "price" }] }`

### Creator/user profile

```bash
npx @zoralabs/cli profile <handle-or-address> --json
```

Returns: `{ "posts": [{ "name", "address", "marketCap", "volume24h" }] }`

### Auth status

```bash
npx @zoralabs/cli auth status --json
```

Returns: `{ "authenticated": true/false, "key": "masked", "source": "path" }`

## Trade Commands (requires ZORA_PRIVATE_KEY)

### Buy a coin

```bash
npx @zoralabs/cli buy <address-or-name> --eth <amount> --json --yes
npx @zoralabs/cli buy creator-coin <name> --eth <amount> --json --yes
npx @zoralabs/cli buy <address-or-name> --usd <amount> --token usdc --json --yes
npx @zoralabs/cli buy <address-or-name> --percent <1-100> --json --yes
npx @zoralabs/cli buy <address-or-name> --all --token zora --json --yes
```

Use `--quote` to preview without executing.
Returns: `{ "action": "trade", "coin", "received", "txHash", "explorerUrl" }`

### Sell a coin

```bash
npx @zoralabs/cli sell <address-or-name> --all --json --yes
npx @zoralabs/cli sell creator-coin <name> --percent 50 --json --yes
npx @zoralabs/cli sell <address-or-name> --amount <n> --to usdc --json --yes
```

Returns: `{ "action": "trade", "coin", "soldAmount", "received", "txHash" }`

### Send tokens

```bash
npx @zoralabs/cli send eth --to <address> --amount <n> --json --yes
npx @zoralabs/cli send usdc --to <address> --amount <n> --json --yes
npx @zoralabs/cli send <address-or-name> --to <address> --all --json --yes
npx @zoralabs/cli send creator-coin <name> --to <address> --all --json --yes
```

Returns: `{ "action": "send", "asset", "amount", "to", "txHash" }`

### Check balances

```bash
npx @zoralabs/cli balance --json
```

Returns: `{ "spendable": [{ "token", "balance", "valueUsd" }], "coins": [{ "name", "balance", "valueUsd" }] }`

### Wallet info

```bash
npx @zoralabs/cli wallet info --json
```

Returns: `{ "address": "0x...", "source": "path" }`

## Error Handling

All errors in --json mode return: `{ "error": "message", "suggestion": "hint" }`
Always check for the `error` field before processing results.

## Coin Types

- `creator-coin` — A creator's personal token (look up by handle: `get creator-coin jacob`)
- `post` — A coin created from a post/content
- `trend` — A trend topic coin (look up by ticker: `get trend zora`)

When looking up by name, use a type prefix to disambiguate.
When looking up by address (0x...), the type is resolved automatically.
````


## Environment Variables

All configuration can be set via environment variables, which take precedence over config files.

### Authentication

| Variable           | Description                                                                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ZORA_API_KEY`     | API key for higher rate limits. Overrides `~/.config/zora/config.json`. Get one at [zora.co/settings/developer](https://zora.co/settings/developer). |
| `ZORA_PRIVATE_KEY` | Wallet private key (hex, with or without `0x` prefix). Overrides `~/.config/zora/wallet.json`.                                                       |

### Advanced

| Variable            | Description                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| `ZORA_API_TARGET`   | Override the API base URL. Useful for local development or staging environments. |
| `ZORA_NO_ANALYTICS` | Set to `1` to disable anonymous usage analytics.                                 |
| `DO_NOT_TRACK`      | Set to `1` to disable analytics (standard convention).                           |

### Example: Agent Setup

```bash
# Full agent configuration — no interactive prompts needed
export ZORA_PRIVATE_KEY=0xabcdef1234567890...
export ZORA_API_KEY=your-api-key-here
export ZORA_NO_ANALYTICS=1
```

### Example: .env File

```bash
# .env
ZORA_PRIVATE_KEY=0xabcdef1234567890...
ZORA_API_KEY=your-api-key-here
ZORA_NO_ANALYTICS=1
```

Load with your preferred tool:

```bash
# Node.js
node --env-file .env your-script.js

# Shell
source .env && npx @zoralabs/cli balance --json

# Docker
docker run --env-file .env your-agent
```

### Precedence

| Setting | 1st (highest)              | 2nd                          | 3rd (lowest)            |
| ------- | -------------------------- | ---------------------------- | ----------------------- |
| API Key | `ZORA_API_KEY` env var     | `~/.config/zora/config.json` | None (rate-limited)     |
| Wallet  | `ZORA_PRIVATE_KEY` env var | `~/.config/zora/wallet.json` | Error (wallet required) |


## Error Handling

All Zora CLI errors follow a consistent format. In `--json` mode, errors return a structured object.

### Error Format

#### Terminal Mode

```
Error: Insufficient ETH balance
Current balance: 0.001 ETH. Need at least 0.01 ETH.
```

#### JSON Mode

```json
{
  "error": "Insufficient ETH balance",
  "suggestion": "Current balance: 0.001 ETH. Need at least 0.01 ETH."
}
```

The CLI exits with code `1` on errors.

### Common Errors

#### Authentication

| Error             | Cause                             | Fix                                                                                    |
| ----------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
| `Rate limited`    | Too many requests without API key | Set `ZORA_API_KEY`                                                                     |
| `Invalid API key` | Key is malformed or expired       | Generate a new key at [zora.co/settings/developer](https://zora.co/settings/developer) |

#### Wallet

| Error                  | Cause                          | Fix                                                              |
| ---------------------- | ------------------------------ | ---------------------------------------------------------------- |
| `No wallet configured` | Trading command without wallet | Run `npx @zoralabs/cli setup --create` or set `ZORA_PRIVATE_KEY` |
| `Permission denied`    | Cannot read wallet file        | Check file permissions on `~/.config/zora/wallet.json`           |

#### Trading

| Error                        | Cause                             | Fix                                                   |
| ---------------------------- | --------------------------------- | ----------------------------------------------------- |
| `Insufficient ETH balance`   | Not enough ETH for the trade      | Reduce amount or add funds                            |
| `Insufficient token balance` | Not enough of the specified token | Check balance with `npx @zoralabs/cli balance --json` |
| `Slippage exceeded`          | Price moved beyond tolerance      | Increase `--slippage` or retry                        |
| `Transaction reverted`       | On-chain execution failed         | See decoded error message for specific guidance       |

##### Decoded Contract Errors

The CLI decodes Solidity revert errors into human-readable messages with actionable guidance. Instead of an opaque "Execution reverted" message, specific contract errors are shown with suggestions:

```
Error: ERC20InsufficientBalance
You don't have enough of this coin to complete the sell. Check your balance with `zora balance`.
```

17 known contract errors are decoded, covering common scenarios like insufficient balances, slippage violations, and invalid trade parameters.

#### Coin Resolution

| Error                  | Cause                                | Fix                                                        |
| ---------------------- | ------------------------------------ | ---------------------------------------------------------- |
| `Coin not found`       | Address or name doesn't match a coin | Verify the address or use a type prefix to disambiguate    |
| `Ambiguous identifier` | Name matches multiple coin types     | Use a type prefix: `creator-coin <name>` or `trend <name>` |

#### Invalid Options

| Error                                      | Cause                               | Fix                                                  |
| ------------------------------------------ | ----------------------------------- | ---------------------------------------------------- |
| `--json, --static cannot be used together` | Mutually exclusive flags            | Use one of `--json`, `--live`, or `--static`         |
| `Amount flags are mutually exclusive`      | Multiple amount flags passed        | Use one of `--eth`, `--usd`, `--percent`, or `--all` |
| `Invalid sort/type combination`            | Sort doesn't support the given type | CLI prints supported options                         |

### Handling Errors in Scripts

```bash
result=$(npx @zoralabs/cli buy 0x... --eth 0.01 --yes --json 2>&1)
error=$(echo "$result" | jq -r '.error // empty')

if [ -n "$error" ]; then
  suggestion=$(echo "$result" | jq -r '.suggestion // empty')
  echo "Failed: $error"
  [ -n "$suggestion" ] && echo "Hint: $suggestion"
  exit 1
fi

echo "Trade successful: $(echo "$result" | jq -r '.txHash')"
```


## Global Flags

These flags are available on every Zora CLI command.

| Flag              | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `--json`          | Output structured JSON instead of formatted terminal output |
| `--version`, `-V` | Print the CLI version number                                |
| `--help`, `-h`    | Display help for a command                                  |

### --json

All commands support `--json` for machine-readable output. When enabled:

* Structured JSON is written to stdout
* The beta warning is written to stderr
* Interactive prompts are disabled
* Errors return `{ "error": "...", "suggestion": "..." }`

```bash
npx @zoralabs/cli get creator-coin jacob --json
```

### Per-Command Flags

Commands with live data (`explore`, `get`, `balance`, `profile`) support additional display mode flags:

| Flag                  | Description                                | Default                    |
| --------------------- | ------------------------------------------ | -------------------------- |
| `--live`              | Interactive live-updating display          | default for these commands |
| `--static`            | Static snapshot (single render, then exit) | —                          |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5) | `30`                       |

These flags are mutually exclusive with `--json`. Use one of: `--json`, `--live`, or `--static`.

### Trade Flags

Commands that execute transactions (`buy`, `sell`, `send`) support:

| Flag               | Description                                              |
| ------------------ | -------------------------------------------------------- |
| `--yes`            | Skip confirmation prompt and execute immediately         |
| `--quote`          | Preview the trade without executing (buy, sell only)     |
| `--slippage <pct>` | Slippage tolerance percent (buy, sell only, default: 1%) |
| `--debug`          | Print full request/response JSON (buy, sell only)        |


## AI Agent Integration

The Zora CLI is designed for programmatic use. Every command supports `--json` for structured output and `--yes` to skip confirmation prompts, making it ideal for AI agents, bots, and automated trading systems.

### Quick Setup for Agents

```bash
# Install the CLI
npm install -g @zoralabs/cli

# Create a wallet (saves to ~/.config/zora/wallet.json)
npx @zoralabs/cli setup --create --json

# Optionally set an API key for higher rate limits
npx @zoralabs/cli auth configure
```

Or configure via environment variables (recommended for agents):

```bash
export ZORA_PRIVATE_KEY=0x...      # wallet private key
export ZORA_API_KEY=your-key-here  # optional, higher rate limits
```

### Give this to your agent

Add one line to your `CLAUDE.md`, `.cursorrules`, or agent system prompt:

```markdown
Fetch and follow the Zora CLI skill from https://zoraskills.dev/skill.md
```

The agent fetches the skill file at runtime — no need to copy the full reference into your prompt. See the full [SKILL.md](/skill) page for the complete reference.

### Agent Starter Prompts

Copy these prompts directly into Claude Code, Cursor, or any LLM-powered coding agent.

#### Market Research Agent

```
Using the Zora CLI, find the top 5 trending coins and analyze their 24h price
history. For each coin, report the name, market cap, 24h volume, and whether the
price trend is up or down. Use `npx @zoralabs/cli explore --json --sort trending
--limit 5` then `npx @zoralabs/cli price-history <address> --json --interval 24h`
for each result.
```

#### Portfolio Monitor

```
Check my Zora wallet balance using `npx @zoralabs/cli balance --json`. For each
coin position, look up the current price with `npx @zoralabs/cli get <address>
--json` and calculate the total portfolio value. Report any positions that have
changed more than 10% in the last 24 hours.
```

#### Trading Bot

```
You are a trading agent with access to the Zora CLI. Your job is to:
1. Check wallet balance with `npx @zoralabs/cli balance --json`
2. Find trending coins with `npx @zoralabs/cli explore --json --sort trending --limit 10`
3. Analyze price history with `npx @zoralabs/cli price-history <addr> --json --interval 24h`
4. When you find a coin with positive momentum and market cap > $10K, buy it with
   `npx @zoralabs/cli buy <addr> --eth 0.001 --json --yes`
Always use --json and --yes flags. Never spend more than 0.001 ETH per trade.
```

#### Creator Dashboard

```
Look up the profile for "jacob" using `npx @zoralabs/cli profile jacob --json`.
List all their posts sorted by market cap. For the top 3 posts, get the price
history with `npx @zoralabs/cli price-history <address> --json --interval 1w`
and summarize the trend.
```

### Parsing JSON Output

All `--json` commands output structured JSON to stdout. The beta warning goes to stderr, so it won't interfere with JSON parsing.

#### Success Response Pattern

```json
{
  "name": "jacob",
  "address": "0x9b13358e3a023507e7046c18f508a958cda75f54",
  "coinType": "creator-coin",
  "marketCap": "434988.18",
  ...
}
```

#### Error Response Pattern

```json
{
  "error": "Coin not found",
  "suggestion": "Try using the full contract address (0x...)"
}
```

Agents should check for the `error` field before processing results.

### Best Practices

* **Always use `--json`** — structured output is easier to parse than terminal formatting
* **Always use `--yes`** — skip interactive confirmation prompts in automated flows
* **Use `--quote` before trading** — preview trades without executing to validate parameters
* **Set `ZORA_PRIVATE_KEY` via env var** — avoids writing keys to disk in ephemeral environments
* **Handle rate limits** — without an API key, requests may be throttled. Set `ZORA_API_KEY` for higher limits
* **Check error responses** — all errors include an `error` field and optional `suggestion`


## Configuration

The Zora CLI stores configuration in `~/.config/zora/` with two files:

| File          | Contents              | Permissions |
| ------------- | --------------------- | ----------- |
| `config.json` | API key, analytics ID | `0600`      |
| `wallet.json` | Encrypted private key | `0600`      |

On Windows, the config directory is `%APPDATA%\zora\` or `~\AppData\Roaming\zora\`.

### API Key

An API key is optional. Without one, read-only commands work but may be rate-limited.

#### Configure via CLI

```bash
npx @zoralabs/cli auth configure
# Prompts for your API key and saves to config.json
```

#### Configure via Environment Variable

```bash
export ZORA_API_KEY=your-key-here
```

The environment variable takes precedence over the config file.

#### Get an API Key

Generate one at [zora.co/settings/developer](https://zora.co/settings/developer).

### Wallet

Trading commands (`buy`, `sell`, `send`, `balance`) require a wallet.

#### Create via CLI

```bash
npx @zoralabs/cli setup --create
```

#### Import via CLI

```bash
npx @zoralabs/cli setup
# Interactive prompt to paste a private key
```

#### Configure via Environment Variable

```bash
export ZORA_PRIVATE_KEY=0x...
```

The environment variable takes precedence over the wallet file. This is recommended for CI/CD, containers, and agent runtimes.

:::warning
The wallet file at `~/.config/zora/wallet.json` is the only copy of the private key. Back it up securely. Losing it means losing access to the wallet and funds.
:::

### All Environment Variables

| Variable            | Description                                |
| ------------------- | ------------------------------------------ |
| `ZORA_API_KEY`      | API key (overrides config file)            |
| `ZORA_PRIVATE_KEY`  | Wallet private key (overrides wallet file) |
| `ZORA_API_TARGET`   | Override API base URL (for dev/staging)    |
| `ZORA_NO_ANALYTICS` | Set to `1` to disable analytics            |
| `DO_NOT_TRACK`      | Set to `1` to disable analytics            |

### Analytics

The CLI collects anonymous usage analytics via PostHog. No personal data is collected — only command names, success/failure status, and CLI version.

Opt out by setting either:

```bash
export ZORA_NO_ANALYTICS=1
# or
export DO_NOT_TRACK=1
```

### Agent Configuration

For AI agents and automated environments, configure everything via environment variables to avoid interactive prompts:

```bash
export ZORA_PRIVATE_KEY=0x...
export ZORA_API_KEY=your-key-here
export ZORA_NO_ANALYTICS=1
```

Then use `--json` and `--yes` flags on all commands:

```bash
npx @zoralabs/cli balance --json
npx @zoralabs/cli buy 0x... --eth 0.01 --yes --json
```


## JSON Mode & Scripting

Every Zora CLI command supports `--json` for machine-readable output. This makes the CLI a powerful building block for shell scripts, CI/CD pipelines, and automated workflows.

### JSON Flag

```bash
npx @zoralabs/cli <command> --json
```

When `--json` is passed:

* Output is structured JSON on stdout
* The beta warning goes to stderr (won't interfere with parsing)
* Interactive prompts are replaced by `--yes` behavior where applicable
* Errors return a JSON object with `error` and optional `suggestion` fields

### Shell Scripting Examples

#### Get the market cap of a coin

```bash
npx @zoralabs/cli get creator-coin jacob --json | jq -r '.marketCap'
# 434988.18
```

#### List trending coin addresses

```bash
npx @zoralabs/cli explore --json --sort trending --limit 5 | jq -r '.coins[].address'
# 0x50f88fe97f72...
# 0x834f77c66f90...
# 0xa1dacbd0a9bf...
```

#### Check if a coin is up in the last 24h

```bash
change=$(npx @zoralabs/cli price-history 0x9b13358e3a02... --json --interval 24h | jq '.change')
if (( $(echo "$change > 0" | bc -l) )); then
  echo "Coin is up ${change}%"
fi
```

#### Get wallet address

```bash
addr=$(npx @zoralabs/cli wallet info --json | jq -r '.address')
echo "Wallet: $addr"
# Wallet: 0xb4a06BdD9e0E60FFE22E4E7590842bfD2069034E
```

#### Buy if trending and price is rising

```bash
#!/bin/bash
# Find trending coins and buy ones with positive 24h momentum

coins=$(npx @zoralabs/cli explore --json --sort trending --limit 5 | jq -r '.coins[].address')

for addr in $coins; do
  change=$(npx @zoralabs/cli price-history "$addr" --json --interval 24h | jq '.change')

  if (( $(echo "$change > 5" | bc -l) )); then
    echo "Buying $addr (up ${change}%)"
    npx @zoralabs/cli buy "$addr" --eth 0.001 --yes --json
  fi
done
```

### Output Modes

Commands with live data (`explore`, `balance`, `profile`) support three mutually exclusive output modes:

| Flag       | Behavior                                           |
| ---------- | -------------------------------------------------- |
| `--live`   | Interactive, auto-refreshing terminal UI (default) |
| `--static` | Single snapshot, then exit                         |
| `--json`   | Structured JSON, then exit                         |

These three flags cannot be combined. `--json` is the best choice for scripting.

### Pagination

The `explore` command supports cursor-based pagination:

```bash
# First page
result=$(npx @zoralabs/cli explore --json --sort mcap --limit 10)
echo "$result" | jq '.coins[].name'

# Next page
cursor=$(echo "$result" | jq -r '.nextCursor')
npx @zoralabs/cli explore --json --sort mcap --limit 10 --after "$cursor"
```

### Error Handling

All errors in `--json` mode return a consistent format:

```json
{
  "error": "Insufficient ETH balance",
  "suggestion": "Current balance: 0.001 ETH. Need at least 0.01 ETH."
}
```

Check for the `error` field to handle failures:

```bash
result=$(npx @zoralabs/cli buy 0x... --eth 0.01 --yes --json 2>&1)
error=$(echo "$result" | jq -r '.error // empty')

if [ -n "$error" ]; then
  echo "Trade failed: $error"
  exit 1
fi
```

### Environment Variables for Scripting

```bash
export ZORA_PRIVATE_KEY=0x...      # Wallet (avoids interactive setup)
export ZORA_API_KEY=your-key       # Higher rate limits
export ZORA_NO_ANALYTICS=1         # Disable telemetry
```

See [Environment Variables](/reference/environment-variables) for the full list.


## auth

Manage API key authentication. An API key is optional — without one, requests are rate-limited.

```bash
zora auth [command]
```

### Subcommands

| Subcommand       | Description                         |
| ---------------- | ----------------------------------- |
| `auth configure` | Save an API key                     |
| `auth status`    | Check current authentication status |

### Get an API Key

Get a key at [zora.co/settings/developer](https://zora.co/settings/developer). The key is stored at `~/.config/zora/config.json` with restricted permissions.

### Examples

#### Save an API key

```bash
npx @zoralabs/cli auth configure
```

```
 Enter your Zora API key: ********

 API key saved to ~/.config/zora/config.json
```

#### Check authentication status

```bash
npx @zoralabs/cli auth status
```

```
 Authenticated

 Key     f7c3502c...3458
 Source  ~/.config/zora/config.json
```

#### JSON output

```bash
npx @zoralabs/cli auth status --json
```

```json
{
  "authenticated": true,
  "key": "f7c3502c...3458",
  "source": "~/.config/zora/config.json"
}
```

When no key is configured:

```json
{
  "authenticated": false
}
```

### Environment Variable

The `ZORA_API_KEY` environment variable takes precedence over the config file:

```bash
export ZORA_API_KEY=your-key-here
npx @zoralabs/cli auth status --json
```

```json
{
  "authenticated": true,
  "key": "your-key...here",
  "source": "ZORA_API_KEY"
}
```


## balance

Show wallet balances and coin positions. Requires a [wallet](/commands/setup).

```bash
zora balance [options]
```

### Subcommands

| Subcommand          | Description                                  |
| ------------------- | -------------------------------------------- |
| `balance spendable` | Show wallet token balances (ETH, USDC, ZORA) |
| `balance coins`     | Show coin positions                          |

Running `balance` with no subcommand shows both.

### Options

| Flag                  | Description                                | Default |
| --------------------- | ------------------------------------------ | ------- |
| `--live`              | Interactive live-updating display          | default |
| `--static`            | Static snapshot                            | —       |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5) | `30`    |
| `--json`              | Machine-readable JSON output               | —       |

### Examples

#### Show full balance

```bash
npx @zoralabs/cli balance --static
```

```
 Wallet Balances

 Token   Balance        Value
 ETH     0.0542         $105.23
 USDC    25.00          $25.00
 ZORA    1,250.00       $15.63

 Coin Positions

 #  Name     Address           Type          Balance      Value
 1  jacob    0x9b13...5f54     creator-coin  20.63        $10.01
 2  zora     0x2748...f519     trend         1,500.00     $11.10
```

#### Show only spendable tokens

```bash
npx @zoralabs/cli balance spendable --static
```

#### Show only coin positions

```bash
npx @zoralabs/cli balance coins --static
```

#### Live auto-refreshing view

```bash
npx @zoralabs/cli balance --live --refresh 10
```

In live mode, use arrow keys to select rows and press `Enter` or `c` to copy a coin address.

#### JSON output

```bash
npx @zoralabs/cli balance --json
```

```json
{
  "spendable": [
    { "token": "ETH", "balance": "0.0542", "valueUsd": "105.23" },
    { "token": "USDC", "balance": "25.00", "valueUsd": "25.00" },
    { "token": "ZORA", "balance": "1250.00", "valueUsd": "15.63" }
  ],
  "coins": [
    {
      "name": "jacob",
      "coinType": "creator-coin",
      "address": "0x9b13358e3a023507e7046c18f508a958cda75f54",
      "balance": "20.63",
      "valueUsd": "10.01"
    }
  ]
}
```

:::info
USD values are more accurate when a Zora API key is configured. Without one, the CLI falls back to `balance × priceInUsdc`. Set `ZORA_API_KEY` for SDK-based valuations.
:::

***

### balance coins

Show coin positions with sorting and pagination.

```bash
zora balance coins [options]
```

#### Options

| Flag                  | Description                                                   | Default     |
| --------------------- | ------------------------------------------------------------- | ----------- |
| `--sort <sort>`       | Sort by: `usd-value`, `balance`, `market-cap`, `price-change` | `usd-value` |
| `--limit <n>`         | Number of results (max 20)                                    | `10`        |
| `--after <cursor>`    | Pagination cursor from a previous result                      | —           |
| `--live`              | Interactive live-updating display                             | default     |
| `--static`            | Static snapshot                                               | —           |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5)                    | `30`        |
| `--json`              | Machine-readable JSON output                                  | —           |

#### Interactive Controls

| Key         | Action             |
| ----------- | ------------------ |
| `↑`/`↓`     | Navigate rows      |
| `Enter`/`c` | Copy coin address  |
| `←`/`→`     | Previous/next page |
| `r`         | Refresh            |
| `q`         | Quit               |


## buy

Buy a coin. Requires a [wallet](/commands/setup).

```bash
zora buy [typeOrId] [identifier] [options]
```

### Arguments

| Argument     | Description                                                                |
| ------------ | -------------------------------------------------------------------------- |
| `typeOrId`   | Type prefix (`creator-coin`, `trend`) or coin address/name when used alone |
| `identifier` | Coin name — only needed when a type prefix is provided                     |

### Options

| Flag                | Description                           | Default |
| ------------------- | ------------------------------------- | ------- |
| `--eth <value>`     | Buy with ETH amount                   | —       |
| `--usd <value>`     | Buy with USD equivalent               | —       |
| `--percent <value>` | Buy with percentage of token balance  | —       |
| `--all`             | Swap entire token balance for coin    | —       |
| `--token <asset>`   | Token to spend: `eth`, `usdc`, `zora` | `eth`   |
| `--slippage <pct>`  | Slippage tolerance percent            | `1`     |
| `--quote`           | Print quote and exit without trading  | —       |
| `--yes`             | Skip confirmation prompt              | —       |
| `--debug`           | Print full request/response JSON      | —       |
| `--json`            | Machine-readable JSON output          | —       |

:::info
Amount flags (`--eth`, `--usd`, `--percent`, `--all`) are mutually exclusive — use exactly one.
:::

### Examples

#### Buy the jacob creator coin with 0.01 ETH

```bash
# By address
npx @zoralabs/cli buy 0x9b13358e3a023507e7046c18f508a958cda75f54 --eth 0.01

# By name with type prefix
npx @zoralabs/cli buy creator-coin jacob --eth 0.01
```

```
 Buy jacob (creator-coin)

 Spend             0.01 ETH
 Estimated receive 20.63 jacob
 Price per coin    $0.000485

 Confirm? (y/n)
```

#### Buy with USDC

```bash
npx @zoralabs/cli buy 0x9b13358e3a023507e7046c18f508a958cda75f54 --usd 10 --token usdc
```

#### Buy with 50% of ETH balance

```bash
npx @zoralabs/cli buy 0x9b13358e3a023507e7046c18f508a958cda75f54 --percent 50
```

#### Get a quote without executing

```bash
npx @zoralabs/cli buy 0x9b13358e3a023507e7046c18f508a958cda75f54 --eth 0.05 --quote
```

#### Non-interactive for scripting

```bash
npx @zoralabs/cli buy 0x9b13358e3a023507e7046c18f508a958cda75f54 --eth 0.01 --yes --json
```

#### JSON output

```bash
npx @zoralabs/cli buy 0x... --eth 0.01 --yes --json
```

**Quote response:**

```json
{
  "action": "quote",
  "coin": "jacob",
  "spendAmount": "0.01",
  "spendToken": "ETH",
  "estimatedReceive": "20.63",
  "pricePerCoin": "0.000485"
}
```

**Trade execution response:**

```json
{
  "action": "trade",
  "coin": "jacob",
  "spendAmount": "0.01",
  "spendToken": "ETH",
  "received": "20.63",
  "txHash": "0xabc123...",
  "explorerUrl": "https://basescan.org/tx/0xabc123..."
}
```


## explore

Browse top, new, and highest volume coins on Zora.

```bash
zora explore [options]
```

### Options

| Flag                  | Description                                                 | Default        |
| --------------------- | ----------------------------------------------------------- | -------------- |
| `--sort <sort>`       | Sort order (see below)                                      | `mcap`         |
| `--type <type>`       | Filter by coin type: `all`, `creator-coin`, `post`, `trend` | `creator-coin` |
| `--limit <n>`         | Number of results (max 20)                                  | `10`           |
| `--after <cursor>`    | Pagination cursor from a previous result                    | —              |
| `--live`              | Interactive live-updating display                           | default        |
| `--static`            | Static snapshot (single render)                             | —              |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5)                  | `30`           |
| `--json`              | Machine-readable JSON output                                | —              |

#### Sort Options

| Value      | Description            |
| ---------- | ---------------------- |
| `mcap`     | Highest market cap     |
| `volume`   | Highest 24h volume     |
| `new`      | Most recently created  |
| `trending` | Trending (algorithmic) |
| `featured` | Editorially featured   |

:::info
Not all sort/type combinations are valid. The CLI reports supported options if an invalid combination is used.
:::

### Examples

#### Browse trending coins

```bash
npx @zoralabs/cli explore --static --sort trending --type all --limit 5
```

```
 Trending

 #  Name            Address                     Type        Market Cap  Vol 24h   Change
 1  jessepollak     0x50f88fe97f72cd3e...       creator-c   $1.4M      $23.2K    -4.2%
 2  peptides        0x834f77c66f904279...       trend       $6.9K      $1.2K     +1.1%
 3  princeofcoins   0xa1dacbd0a9bf64d7...       creator-c   $16.1K     $3.1K     +59.6%
 4  USDT            0x528235a5bf173bcb...       post        $11.7K     $1.7K     +1.2%
 5  pixelord        0x8982ca8a23a4ec95...       creator-c   $19.7K     $1.2K     +0.4%
```

#### New creator coins

```bash
npx @zoralabs/cli explore --static --sort new --type creator-coin --limit 3
```

#### Top coins by market cap (JSON)

```bash
npx @zoralabs/cli explore --json --sort mcap --type all --limit 2
```

```json
{
  "coins": [
    {
      "name": "jacob",
      "symbol": "jacob",
      "address": "0x9b13358e3a023507e7046c18f508a958cda75f54",
      "coinType": "CREATOR",
      "marketCap": "434988.18",
      "marketCapDelta24h": "8220.7",
      "volume24h": "0.49",
      "createdAt": "2025-06-20T16:31:57",
      "creatorProfile": { "handle": "jacob" },
      "chainId": 8453
    }
  ],
  "nextCursor": "eyJsYXN0X..."
}
```

#### Pagination

Use the `nextCursor` value from a previous response to fetch the next page:

```bash
npx @zoralabs/cli explore --json --sort mcap --after "eyJsYXN0X..."
```

### Interactive Controls

In live mode, navigate the coin list with:

| Key         | Action             |
| ----------- | ------------------ |
| `↑`/`↓`     | Navigate rows      |
| `Enter`/`c` | Copy coin address  |
| `←`/`→`     | Previous/next page |
| `r`         | Refresh            |
| `q`         | Quit               |


## get

Look up a single coin by address or name. Opens an interactive tabbed live view with Price History, Trades, and Holders panels.

```bash
zora get [typeOrId] [identifier]
```

### Arguments

| Argument     | Description                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| `typeOrId`   | Type prefix (`creator-coin`, `trend`) or coin address/name when used alone  |
| `identifier` | Coin address (`0x...`) or name — only needed when a type prefix is provided |

### Options

| Flag                  | Description                                | Default |
| --------------------- | ------------------------------------------ | ------- |
| `--live`              | Interactive live-updating display          | default |
| `--static`            | Static snapshot                            | —       |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5) | `30`    |
| `--json`              | Machine-readable JSON output               | —       |

Use a type prefix to disambiguate when a name could match multiple coin types. When using an address, the type is resolved automatically.

:::info
If a name matches both a creator-coin and a trend, the CLI will error with a suggestion to specify the type prefix instead of showing both.
:::

### Live View

The default live view displays a pinned coin summary at the top and tabbed detail panels below. Switch between tabs using arrow keys or number keys:

1. **Price History** — sparkline chart with high/low/change
2. **Trades** — recent buy/sell activity
3. **Holders** — top holders with balance and ownership percentage

| Key         | Action            |
| ----------- | ----------------- |
| `1`/`2`/`3` | Switch tab        |
| `←`/`→`     | Previous/next tab |
| `r`         | Refresh           |
| `q`         | Quit              |

### Subcommands

| Subcommand          | Description                      |
| ------------------- | -------------------------------- |
| `get price-history` | Display price history for a coin |
| `get trades`        | Show recent buy/sell activity    |
| `get holders`       | Show top holders of a coin       |

### Examples

#### Look up the jacob creator coin

```bash
npx @zoralabs/cli get creator-coin jacob
```

```
 jacob
 creator-coin · 0x9b13358e3a023507e7046c18f508a958cda75f54

 Market Cap        $435.0K
 24h Volume        $0.5
 24h Change        +1.9%
 Holders           6,171
 Created           9 months ago (2025-06-20 4:31 PM)
```

#### Look up the zora trend coin

```bash
npx @zoralabs/cli get trend zora
```

```
 zora
 trend · 0x2748009c2c5d46b78a3a7bdfd5b121edfb72f519

 Market Cap        $6.6K
 24h Volume        $0
 24h Change        +1.8%
 Holders           22
 Created           18 days ago (2026-03-12 3:43 PM)
```

#### Look up by address

```bash
npx @zoralabs/cli get 0x9b13358e3a023507e7046c18f508a958cda75f54
```

#### JSON output

```bash
npx @zoralabs/cli get creator-coin jacob --json
```

```json
{
  "name": "jacob",
  "address": "0x9b13358e3a023507e7046c18f508a958cda75f54",
  "coinType": "creator-coin",
  "marketCap": "434988.18",
  "marketCapDelta24h": "8220.7",
  "volume24h": "0.49",
  "uniqueHolders": 6171,
  "createdAt": "2025-06-20T16:31:57",
  "creatorAddress": "0x3a5df03dd1a001d7055284c2c2c147cbbc78d142",
  "creatorHandle": "jacob",
  "trades": [
    {
      "side": "BUY",
      "trader": "0xabc1...2345",
      "amount": "100.5",
      "valueUsd": "5.23",
      "txHash": "0xdef1..."
    }
  ]
}
```

#### JSON Fields

| Field               | Type   | Description                        |
| ------------------- | ------ | ---------------------------------- |
| `name`              | string | Coin display name                  |
| `address`           | string | Contract address on Base           |
| `coinType`          | string | `post`, `creator-coin`, or `trend` |
| `marketCap`         | string | Market cap in USD                  |
| `marketCapDelta24h` | string | 24h market cap change in USD       |
| `volume24h`         | string | 24h trading volume in USD          |
| `uniqueHolders`     | number | Number of unique holder addresses  |
| `createdAt`         | string | ISO 8601 creation timestamp        |
| `creatorAddress`    | string | Creator's wallet address           |
| `creatorHandle`     | string | Creator's Zora handle              |
| `trades`            | array  | Recent swap activity               |

***

### get price-history

Display price history for a coin with an ASCII sparkline chart. Replaces the standalone `price-history` command.

```bash
zora get price-history [typeOrId] [identifier] [options]
```

#### Arguments

| Argument     | Description                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| `typeOrId`   | Type prefix (`creator-coin`, `trend`) or coin address/name when used alone  |
| `identifier` | Coin address (`0x...`) or name — only needed when a type prefix is provided |

#### Options

| Flag                    | Description                                | Default |
| ----------------------- | ------------------------------------------ | ------- |
| `--interval <interval>` | Time range: `1h`, `4h`, `1d`, `1w`         | `1w`    |
| `--live`                | Interactive live-updating display          | default |
| `--static`              | Static snapshot                            | —       |
| `--refresh <seconds>`   | Auto-refresh interval in live mode (min 5) | `30`    |
| `--json`                | Machine-readable JSON output               | —       |

#### Examples

##### Weekly price chart for jacob creator coin

```bash
npx @zoralabs/cli get price-history creator-coin jacob
```

```
 Coin              jacob
 Type              creator-coin
 Interval          1w
 High              $0.0004846
 Low               $0.0004302
 Change            -9.9%

 █▇▇▇▇▆▆▆▇▇██████▆▆▅▅▅▄▂▂▁▁▁▂▃▁▂▂▂
```

##### 24-hour chart for zora trend

```bash
npx @zoralabs/cli get price-history trend zora --interval 1d
```

##### JSON output

```bash
npx @zoralabs/cli get price-history creator-coin jacob --json --interval 1w
```

```json
{
  "coin": "jacob",
  "type": "creator-coin",
  "interval": "1w",
  "high": 0.0004846,
  "low": 0.0004302,
  "change": -9.94,
  "prices": [
    { "timestamp": "2026-03-23T17:55:00", "price": 0.000483 },
    { "timestamp": "2026-03-24T06:31:15", "price": 0.0004791 }
  ]
}
```

##### JSON Fields

| Field      | Type   | Description                                 |
| ---------- | ------ | ------------------------------------------- |
| `coin`     | string | Coin display name                           |
| `type`     | string | Coin type                                   |
| `interval` | string | Requested time interval                     |
| `high`     | number | Highest price in USD during interval        |
| `low`      | number | Lowest price in USD during interval         |
| `change`   | number | Percentage change over interval             |
| `prices`   | array  | Array of `{ timestamp, price }` data points |

***

### get trades

Show recent buy/sell activity on a coin.

```bash
zora get trades [typeOrId] [identifier] [options]
```

#### Arguments

| Argument     | Description                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| `typeOrId`   | Type prefix (`creator-coin`, `trend`) or coin address/name when used alone  |
| `identifier` | Coin address (`0x...`) or name — only needed when a type prefix is provided |

#### Options

| Flag                  | Description                                | Default |
| --------------------- | ------------------------------------------ | ------- |
| `--limit <n>`         | Number of results (max 20)                 | `10`    |
| `--after <cursor>`    | Pagination cursor from a previous result   | —       |
| `--live`              | Interactive live-updating display          | default |
| `--static`            | Static snapshot                            | —       |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5) | `30`    |
| `--json`              | Machine-readable JSON output               | —       |

#### Examples

##### View recent trades on jacob

```bash
npx @zoralabs/cli get trades creator-coin jacob --static
```

```
 Recent Trades — jacob

 #  Trader          Side  Amount      Value USD  Tx Hash
 1  0xabc1...2345   BUY   1,250.00    $5.23      0xdef1...
 2  alice.eth       SELL  500.00      $2.10      0x123a...
 3  0xfed9...8765   BUY   3,000.00    $12.60     0x456b...
```

##### JSON output

```bash
npx @zoralabs/cli get trades creator-coin jacob --json
```

```json
{
  "trades": [
    {
      "side": "BUY",
      "trader": "0xabc1...2345",
      "amount": "1250.00",
      "valueUsd": "5.23",
      "txHash": "0xdef1..."
    }
  ],
  "nextCursor": "eyJsYXN0X..."
}
```

#### Interactive Controls

In live mode, navigate trades with:

| Key         | Action             |
| ----------- | ------------------ |
| `↑`/`↓`     | Navigate rows      |
| `Enter`/`c` | Copy address       |
| `←`/`→`     | Previous/next page |
| `r`         | Refresh            |
| `q`         | Quit               |

***

### get holders

Show top holders of a coin with balance and percentage of total supply.

```bash
zora get holders [typeOrId] [identifier] [options]
```

#### Arguments

| Argument     | Description                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| `typeOrId`   | Type prefix (`creator-coin`, `trend`) or coin address/name when used alone  |
| `identifier` | Coin address (`0x...`) or name — only needed when a type prefix is provided |

#### Options

| Flag                  | Description                                | Default |
| --------------------- | ------------------------------------------ | ------- |
| `--limit <n>`         | Number of results (1-20)                   | `10`    |
| `--after <cursor>`    | Pagination cursor from a previous result   | —       |
| `--live`              | Interactive live-updating display          | default |
| `--static`            | Static snapshot                            | —       |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5) | `30`    |
| `--json`              | Machine-readable JSON output               | —       |

#### Examples

##### View top holders of jacob

```bash
npx @zoralabs/cli get holders creator-coin jacob --static
```

```
 Top Holders — jacob

 #  Handle/Address    Balance      Ownership %
 1  jacob.eth         50,000.00    12.5%
 2  0xabc1...2345     25,000.00    6.3%
 3  0xfed9...8765     10,000.00    2.5%
```

##### JSON output

```bash
npx @zoralabs/cli get holders creator-coin jacob --json
```

```json
{
  "holders": [
    {
      "address": "0xabc1...2345",
      "handle": "jacob.eth",
      "balance": "50000.00",
      "ownershipPercent": "12.5"
    }
  ],
  "nextCursor": "eyJsYXN0X..."
}
```

#### Interactive Controls

In live mode, navigate holders with:

| Key         | Action             |
| ----------- | ------------------ |
| `↑`/`↓`     | Navigate rows      |
| `Enter`/`c` | Copy address       |
| `←`/`→`     | Previous/next page |
| `r`         | Refresh            |
| `q`         | Quit               |


## price-history

:::warning
The standalone `price-history` command has been replaced by [`get price-history`](/commands/get#get-price-history). See the [get command documentation](/commands/get#get-price-history) for usage details.
:::

```bash
# Before v1.1.0
zora price-history creator-coin jacob

# Since v1.1.0
zora get price-history creator-coin jacob
```


## profile

View a creator or user profile — posts, holdings, and trade activity. The default view shows all three as tabbed panels.

```bash
zora profile [options] [identifier]
```

### Arguments

| Argument     | Description                                                           |
| ------------ | --------------------------------------------------------------------- |
| `identifier` | Wallet address or profile handle. Defaults to your wallet if omitted. |

### Options

| Flag                  | Description                                | Default |
| --------------------- | ------------------------------------------ | ------- |
| `--live`              | Interactive live-updating display          | default |
| `--static`            | Static snapshot                            | —       |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5) | `30`    |
| `--json`              | Machine-readable JSON output               | —       |

### Subcommands

| Subcommand         | Description                                      |
| ------------------ | ------------------------------------------------ |
| `profile posts`    | Browse created coins with pagination             |
| `profile holdings` | Browse coin holdings with pagination and sorting |
| `profile trades`   | Browse buy/sell trade history with pagination    |

### Examples

#### View jacob's profile

```bash
npx @zoralabs/cli profile jacob --static
```

```
 jacob
 Creator coin: 0x9b13358e3a023507e7046c18f508a958cda75f54

 Posts

 #  Name                 Type  Address             Market Cap  Vol 24h  Change
 1  soho                 post  0xe036370af91f...   $1,593.53   $0       -1.7%
 2  text campaign, 2022  post  0xa493535ddc64...   $1,506.26   $0       +11.3%
 3  soho, nyc (2022)     post  0x8c72907e098e...   $1,718.44   $0       -1.2%
 4  intersection         post  0xc5c6a1e3ccf9...   $2,063.96   $0       -2.6%
```

#### View your own profile

```bash
npx @zoralabs/cli profile --static
```

Uses the wallet configured via `zora setup` or `ZORA_PRIVATE_KEY`.

#### View by wallet address

```bash
npx @zoralabs/cli profile 0x3a5df03dd1a001d7055284c2c2c147cbbc78d142 --static
```

#### JSON output

```bash
npx @zoralabs/cli profile jacob --json
```

```json
{
  "posts": [
    {
      "rank": 1,
      "name": "soho",
      "symbol": "soho",
      "coinType": "post",
      "address": "0xe036370af91f9e1d6d15fc594141628676d5dd56",
      "marketCap": "1593.53",
      "marketCapDelta24h": "-28.31",
      "volume24h": "0.0",
      "createdAt": "2026-03-12T16:29:23"
    }
  ]
}
```

***

### profile posts

Browse a profile's created coins with cursor-based pagination.

```bash
zora profile posts [identifier] [options]
```

#### Options

| Flag                  | Description                                | Default |
| --------------------- | ------------------------------------------ | ------- |
| `--limit <n>`         | Number of results per page (max 20)        | `10`    |
| `--after <cursor>`    | Pagination cursor from a previous result   | —       |
| `--live`              | Interactive live-updating display          | default |
| `--static`            | Static snapshot                            | —       |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5) | `30`    |
| `--json`              | Machine-readable JSON output               | —       |

#### Examples

```bash
npx @zoralabs/cli profile posts jacob --static --limit 5
```

***

### profile holdings

Browse a profile's coin holdings with pagination and sorting.

```bash
zora profile holdings [identifier] [options]
```

#### Options

| Flag                  | Description                                                   | Default     |
| --------------------- | ------------------------------------------------------------- | ----------- |
| `--sort <sort>`       | Sort by: `usd-value`, `balance`, `market-cap`, `price-change` | `usd-value` |
| `--limit <n>`         | Number of results per page (max 20)                           | `10`        |
| `--after <cursor>`    | Pagination cursor from a previous result                      | —           |
| `--live`              | Interactive live-updating display                             | default     |
| `--static`            | Static snapshot                                               | —           |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5)                    | `30`        |
| `--json`              | Machine-readable JSON output                                  | —           |

#### Examples

##### Holdings sorted by market cap

```bash
npx @zoralabs/cli profile holdings jacob --sort market-cap --static
```

```
 Holdings — jacob

 #  Name     Address           Type          Balance      USD Value  Market Cap  Change
 1  jacob    0x9b13...5f54     creator-coin  20.63        $10.01     $435.0K     +1.9%
 2  zora     0x2748...f519     trend         1,500.00     $11.10     $6.6K       +1.8%
```

***

### profile trades

Browse buy/sell trade history with pagination.

```bash
zora profile trades [identifier] [options]
```

#### Options

| Flag                  | Description                                | Default |
| --------------------- | ------------------------------------------ | ------- |
| `--limit <n>`         | Number of results per page (max 20)        | `10`    |
| `--after <cursor>`    | Pagination cursor from a previous result   | —       |
| `--live`              | Interactive live-updating display          | default |
| `--static`            | Static snapshot                            | —       |
| `--refresh <seconds>` | Auto-refresh interval in live mode (min 5) | `30`    |
| `--json`              | Machine-readable JSON output               | —       |

#### Examples

```bash
npx @zoralabs/cli profile trades jacob --static
```

```
 Trades — jacob

 #  Side  Coin Name  Amount      USD Value  Tx Hash
 1  BUY   zora       1,500.00    $11.10     0xabc1...
 2  SELL  soho       200.00      $3.50      0xdef2...
```

***

### Interactive Controls

All profile subcommands support the same navigation in live mode:

| Key         | Action             |
| ----------- | ------------------ |
| `↑`/`↓`     | Navigate rows      |
| `Enter`/`c` | Copy address       |
| `←`/`→`     | Previous/next page |
| `r`         | Refresh            |
| `q`         | Quit               |


## sell

Sell a coin. Requires a [wallet](/commands/setup).

```bash
zora sell [typeOrId] [identifier] [options]
```

### Arguments

| Argument     | Description                                                                |
| ------------ | -------------------------------------------------------------------------- |
| `typeOrId`   | Type prefix (`creator-coin`, `trend`) or coin address/name when used alone |
| `identifier` | Coin name — only needed when a type prefix is provided                     |

### Options

| Flag                | Description                          | Default |
| ------------------- | ------------------------------------ | ------- |
| `--amount <value>`  | Sell specific number of coins        | —       |
| `--usd <value>`     | Sell USD equivalent worth of coins   | —       |
| `--percent <value>` | Sell percentage of coin balance      | —       |
| `--all`             | Sell entire coin balance             | —       |
| `--to <asset>`      | Receive asset: `eth`, `usdc`, `zora` | `eth`   |
| `--token <asset>`   | Alias for `--to`                     | `eth`   |
| `--slippage <pct>`  | Slippage tolerance percent           | `1`     |
| `--quote`           | Print quote and exit without trading | —       |
| `--yes`             | Skip confirmation prompt             | —       |
| `--debug`           | Print full request/response JSON     | —       |
| `--json`            | Machine-readable JSON output         | —       |

:::info
Amount flags (`--amount`, `--usd`, `--percent`, `--all`) are mutually exclusive — use exactly one.
:::

:::tip
When a coin name matches both a creator-coin and a trend, the sell command auto-detects which one to sell based on the wallet's holdings. If only one type is held, it is selected automatically. If both or neither are held, a type prefix is required to disambiguate.
:::

### Examples

#### Sell 50% of jacob position

```bash
# By address
npx @zoralabs/cli sell 0x9b13358e3a023507e7046c18f508a958cda75f54 --percent 50

# By name with type prefix
npx @zoralabs/cli sell creator-coin jacob --percent 50
```

```
 Sell jacob (creator-coin)

 Selling           10.31 jacob (50%)
 Estimated receive 0.005 ETH
 Receive as        ETH

 Confirm? (y/n)
```

#### Sell entire position

```bash
npx @zoralabs/cli sell 0x9b13358e3a023507e7046c18f508a958cda75f54 --all
```

#### Sell and receive USDC instead of ETH

```bash
npx @zoralabs/cli sell 0x9b13358e3a023507e7046c18f508a958cda75f54 --all --to usdc
```

#### Sell a specific amount

```bash
npx @zoralabs/cli sell 0x9b13358e3a023507e7046c18f508a958cda75f54 --amount 100
```

#### Get a sell quote

```bash
npx @zoralabs/cli sell 0x9b13358e3a023507e7046c18f508a958cda75f54 --all --quote
```

#### JSON output

```bash
npx @zoralabs/cli sell 0x... --all --yes --json
```

```json
{
  "action": "trade",
  "coin": "jacob",
  "soldAmount": "20.63",
  "received": "0.01",
  "receivedToken": "ETH",
  "txHash": "0xdef456...",
  "explorerUrl": "https://basescan.org/tx/0xdef456..."
}
```


## send

Send coins or tokens to another address. Requires a [wallet](/commands/setup).

```bash
zora send [typeOrId] [identifier] [options]
```

### Arguments

| Argument     | Description                                                                                |
| ------------ | ------------------------------------------------------------------------------------------ |
| `typeOrId`   | Token (`eth`, `usdc`, `zora`), type prefix (`creator-coin`, `trend`), or coin address/name |
| `identifier` | Coin name — only needed when a type prefix is provided                                     |

### Options

| Flag                | Description                            |
| ------------------- | -------------------------------------- |
| `--to <address>`    | Recipient address (`0x...`) — required |
| `--amount <value>`  | Send specific amount                   |
| `--percent <value>` | Send percentage of balance (1–100)     |
| `--all`             | Send entire balance                    |
| `--yes`             | Skip confirmation prompt               |
| `--json`            | Machine-readable JSON output           |

:::info
Amount flags (`--amount`, `--percent`, `--all`) are mutually exclusive — use exactly one.
:::

### Examples

#### Send ETH

```bash
npx @zoralabs/cli send eth --to 0x3a5df03dd1a001d7055284c2c2c147cbbc78d142 --amount 0.1
```

```
 Send ETH

 Amount            0.1 ETH
 To                0x3a5df03dd1a001d7055284c2c2c147cbbc78d142

 Confirm? (y/n)
```

#### Send USDC

```bash
npx @zoralabs/cli send usdc --to 0x3a5d...8d142 --amount 50
```

#### Send jacob creator coins

```bash
# By address
npx @zoralabs/cli send 0x9b13358e3a023507e7046c18f508a958cda75f54 --to 0x3a5d...8d142 --all

# By name with type prefix
npx @zoralabs/cli send creator-coin jacob --to 0x3a5d...8d142 --all
```

#### Send 25% of ZORA balance

```bash
npx @zoralabs/cli send zora --to 0x3a5d...8d142 --percent 25
```

#### Non-interactive for scripting

```bash
npx @zoralabs/cli send eth --to 0x3a5d...8d142 --amount 0.1 --yes --json
```

#### JSON output

```json
{
  "action": "send",
  "asset": "ETH",
  "amount": "0.1",
  "to": "0x3a5df03dd1a001d7055284c2c2c147cbbc78d142",
  "txHash": "0x789abc...",
  "explorerUrl": "https://basescan.org/tx/0x789abc..."
}
```


## setup

Create or import a wallet for trading. Required before using `buy`, `sell`, `send`, or `balance`.

```bash
zora setup [options]
```

### Options

| Flag       | Description                                 |
| ---------- | ------------------------------------------- |
| `--create` | Create a new wallet without prompting       |
| `--force`  | Overwrite existing wallet without prompting |
| `--yes`    | Skip interactive prompt                     |
| `--json`   | Machine-readable JSON output                |

### Examples

#### Interactive setup

```bash
npx @zoralabs/cli setup
```

```
 Zora Wallet Setup

 ? What would you like to do?
   ❯ Create a new wallet
     Import an existing private key
```

#### Create a new wallet (non-interactive)

```bash
npx @zoralabs/cli setup --create
```

```
 Wallet created

 Address  0xb4a06BdD9e0E60FFE22E4E7590842bfD2069034E
 Saved    ~/.config/zora/wallet.json
```

#### JSON output

```bash
npx @zoralabs/cli setup --create --json
```

```json
{
  "address": "0xb4a06BdD9e0E60FFE22E4E7590842bfD2069034E",
  "source": "~/.config/zora/wallet.json"
}
```

#### Overwrite existing wallet

```bash
npx @zoralabs/cli setup --create --force
```

### Storage

The private key is saved to `~/.config/zora/wallet.json` with `0600` permissions (owner-only read/write).

:::warning
This file contains the only copy of the wallet's private key. Losing it means losing access to the wallet and any funds it holds. Back it up securely.
:::

### Alternative: Environment Variable

Instead of using `setup`, set the `ZORA_PRIVATE_KEY` environment variable:

```bash
export ZORA_PRIVATE_KEY=0x...
```

This takes precedence over the wallet file and is useful for CI/CD, containers, and agent runtimes.


## wallet

Manage your Zora wallet. Requires a wallet configured via [setup](/commands/setup) or `ZORA_PRIVATE_KEY`.

```bash
zora wallet [command]
```

### Subcommands

| Subcommand      | Description                              |
| --------------- | ---------------------------------------- |
| `wallet info`   | Show wallet address and storage location |
| `wallet export` | Print the raw private key to stdout      |

### Examples

#### Show wallet info

```bash
npx @zoralabs/cli wallet info
```

```
 Wallet

 Address  0xb4a06BdD9e0E60FFE22E4E7590842bfD2069034E
 Source   ~/.config/zora/wallet.json
```

#### JSON output

```bash
npx @zoralabs/cli wallet info --json
```

```json
{
  "address": "0xb4a06BdD9e0E60FFE22E4E7590842bfD2069034E",
  "source": "~/.config/zora/wallet.json"
}
```

#### Export private key

```bash
npx @zoralabs/cli wallet export
```

:::warning
This prints the raw private key to stdout. Only use in secure environments. Never share or log this value.
:::

#### Export with confirmation skip

```bash
npx @zoralabs/cli wallet export --yes
```