Getting Started - Tokenomist

Requires Node.js 18+ and a Tokenomist API key. Get one at tokenomist.ai.

Tokenomist-cli brings the Tokenomist platform to your terminal. Query token unlocks, supply allocations, emission schedules, fundraising history, and buyback activity — response comes back in a structured, machine-readable format, so it drops straight into agents, notebooks, and research scripts.

Installation

npm (recommended)
npx (no install)

npm install -g @tokenomist-ai/tokenomist-cli

Verify the installation:

tok --version
# 0.1.0

Run any command without installing globally:

npx @tokenomist-ai/tokenomist-cli token list

Source code : https://github.com/tokenomist-ai/tokenomist-cli

Authentication

Get your API key

Sign up or log in at tokenomist.ai
Navigate to the API section of your dashboard (Request API Trial Here)
Generate a new API key and copy it

tok auth login
# Enter your Tokenomist API key: ****

tok auth login --api-key tk-your-api-key

Your key is stored in ~/.tokenomist/config.json with restricted file permissions (0600).

Verify

tok auth status
# Source:  ~/.tokenomist/config.json
# Key:    tk-t****ab2f

Run Your First Command

tok token list --token-id ethena,solana

You should see a formatted table with market data, supply, and unlock information:

+--------+--------+--------+----------------+------------------+------------------+------------------+----------------------+
| ID     | Name   | Symbol |     Market Cap |     Circ. Supply |           Locked |         Unlocked | Updated              |
+--------+--------+--------+----------------+------------------+------------------+------------------+----------------------+
| ethena | Ethena | ENA    |    976,183,624 |    8,759,375,000 |    4,928,125,000 |    8,048,437,500 | 2025-09-17T05:49:03Z |
| solana | Solana | SOL    | 49,279,843,463 | 575,499,265.8197 | 142,169,244.1616 | 644,999,130.1059 | 2025-08-07T08:37:39Z |
+--------+--------+--------+----------------+------------------+------------------+------------------+----------------------+

AI Skills

Install 6 pre-built skills for Claude Code, Cursor, Windsurf, and other AI agents that can run shell commands.

npx skills add tokenomist-ai/tokenomist-cli

Skill	What it does
`tokenomist-token-overview`	Browse tokens, compare market caps
`tokenomist-allocation-breakdown`	Supply distribution across stakeholders
`tokenomist-unlock-analysis`	Analyze unlock schedules and impact
`tokenomist-emission-report`	Daily/weekly emission breakdowns
`tokenomist-burn-buyback`	Burn and buyback activity
`tokenomist-fundraising-lookup`	Funding rounds, investors, valuations

Once installed, your AI agent can query tokenomics data directly — just ask it to “check Solana’s upcoming unlocks” or “compare Arbitrum’s emissions this month.”

Authentication Methods

The CLI resolves your API key in this order (first match wins):

Priority	Method	Example
1	`--api-key` flag	`tok token list --api-key tk-...`
2	`TOKENOMIST_API_KEY` env var	`export TOKENOMIST_API_KEY=tk-...`
3	Config file	`~/.tokenomist/config.json` (set by `auth login`)

Use auth login for day-to-day work. Use env vars for CI/CD pipelines and Docker containers. Use the --api-key flag for one-off commands or testing with a different key.

Environment variable

export TOKENOMIST_API_KEY=tk-your-api-key
tok token list

`.env` file

Create a .env file in your project directory:

TOKENOMIST_API_KEY=tk-your-api-key

Output Formats

Every command supports three output formats via the -o / --output flag:

Table (default)
JSON
CSV

Human-readable formatted table with colored headers and right-aligned numbers.

tok token list

Structured output for scripts and AI agents.

tok token list --output json

Spreadsheet-ready output for Excel, Google Sheets, or data pipelines.

tok token list --output csv > tokens.csv

Caching

The CLI caches API responses for 10 minutes to reduce redundant requests and speed up repeated queries. Cache files are stored in ~/.tokenomist/cache/. To bypass the cache and fetch fresh data:

tok token list --no-cache

Uninstalling

npm uninstall -g tokenomist-cli

To also remove stored credentials and cache, run rm -rf ~/.tokenomist. This cannot be undone.

​Installation

​Authentication

​Run Your First Command

​AI Skills

​Authentication Methods

​Environment variable

​.env file

​Output Formats

​Caching

​Uninstalling

Installation

Authentication

Run Your First Command

AI Skills

Authentication Methods

Environment variable

`.env` file

Output Formats

Caching

Uninstalling