Command Reference - Tokenomist

Global Options

These options are available on all commands:

Flag	Description	Default
`-k, --api-key <key>`	API key (overrides env var and config file)	—
`-o, --output <format>`	Output format: `table`, `json`, `csv`	`table`
`--base-url <url>`	Override API base URL	`https://api.tokenomist.ai`
`--no-cache`	Bypass the 10-minute response cache	—
`-V, --version`	Print CLI version	—
`-h, --help`	Show help for any command	—

Output formats: table is best for terminal use, json for scripts and AI agents, csv for spreadsheets and data pipelines. Array values in CSV are joined with "; ".

Authentication

Store your API key securely in ~/.tokenomist/config.json.

# Interactive — prompts for key
tok auth login

# Non-interactive — pass key directly
tok auth login --api-key tk-your-api-key

Option	Description
`--api-key <key>`	API key (prompts interactively if not provided)

The config file is created with restricted permissions (0600).

`tok auth status`

Show the current authentication status including key source and masked key value.

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

`tok auth logout`

Remove the stored API key from ~/.tokenomist/config.json.

tok auth logout

Tokens

`tok token list`

List all tracked tokens with market data and supply information.

tok token list
tok token list --token-id 1,2,3
tok token list --output json

Option	Description
`--token-id <ids>`	Filter by token IDs (comma-separated)

Response fields: id, name, symbol, marketCap, circulatingSupply, maxSupply, totalLockedAmount, tbdLockedAmount, unlockedAmount, untrackedAmount, listedMethod, hasStandardAllocation, hasFundraising, latestFundraisingRound, hasBurn, hasBuyback, hasAnnouncedClaim, websiteUrl, lastUpdatedDate

`tok token search <query>`

Search for tokens by name, symbol, or slug.

tok token search bitcoin
tok token search sol --output json

Argument	Required	Description
`query`	Yes	Search query string

Response fields: tokenId, tokenName, tokenSymbol

Unlocks

`tok unlock list`

List unlock events grouped by token. Supports extensive filtering.

tok unlock list
tok unlock list --min-market-cap 1000000
tok unlock list --standard-allocation founderTeam,privateInvestors
tok unlock list --min-value-to-market-cap 0.05 --page 1 --page-size 10

Option	Description
`--min-market-cap <value>`	Minimum market cap filter
`--min-released-percentage <value>`	Minimum released percentage
`--min-unlock-date <date>`	Min unlock date (`YYYY-MM-DD`)
`--max-unlock-date <date>`	Max unlock date (`YYYY-MM-DD`)
`--min-total-unlock-amount <value>`	Minimum total unlock amount
`--min-value-to-market-cap <value>`	Min value-to-market-cap ratio
`--standard-allocation <names>`	Filter by allocation (comma-separated)
`--page <number>`	Page number
`--page-size <number>`	Items per page

Allocation values: community, founderTeam, privateInvestors, publicInvestors, reserve, others

`tok unlock upcoming`

List the next upcoming unlock event per token.

tok unlock upcoming
tok unlock upcoming --min-market-cap 100000000 --output json
tok unlock upcoming --start 2024-08-01 --end 2024-08-31

Option	Description
`--start <date>`	Start date (`YYYY-MM-DD`)
`--end <date>`	End date (`YYYY-MM-DD`)
`--standard-allocation <names>`	Filter by allocation (comma-separated)
`--min-market-cap <value>`	Minimum market cap
`--min-released-percentage <value>`	Minimum released percentage
`--min-total-unlock-amount <value>`	Minimum total unlock amount
`--min-value-to-market-cap <value>`	Min value-to-market-cap ratio
`--page <number>`	Page number
`--page-size <number>`	Items per page

`tok unlock events <tokenId>`

Get unlock events for a specific token with optional date range and allocation filters.

tok unlock events solana
tok unlock events solana --start 2024-01-01 --end 2024-12-31
tok unlock events arbitrum --standard-allocation founderTeam --output json

Argument	Required	Description
`tokenId`	Yes	Token ID or slug (e.g. `solana`, `arbitrum`)

Option	Description
`--start <date>`	Start date (`YYYY-MM-DD`)
`--end <date>`	End date (`YYYY-MM-DD`)
`--standard-allocation <names>`	Filter by allocation (comma-separated)
`--page <number>`	Page number
`--page-size <number>`	Items per page

Response fields: unlockDate, tokenName, tokenSymbol, listedMethod, dataSource, cliffUnlocks (containing cliffAmount, cliffValue, valueToMarketCap, allocationBreakdown), latestUpdateDate

Emissions

`tok emission daily <tokenId>`

Get daily emission data for a token, broken down by allocation.

tok emission daily arbitrum
tok emission daily arbitrum --start 2024-08-01 --end 2024-08-31
tok emission daily solana --standard-allocation founderTeam --output csv

Argument	Required	Description
`tokenId`	Yes	Token ID

Option	Description
`--start <date>`	Start date (`YYYY-MM-DD`)
`--end <date>`	End date (`YYYY-MM-DD`)
`--standard-allocation <names>`	Filter by allocation (comma-separated)
`--page <number>`	Page number
`--page-size <number>`	Items per page

Response fields: startDate, endDate, tokenName, tokenSymbol, listedMethod, unlockAmount, unlockValue, referencePrice, totalCumulativeUnlockedAmount, allocations (containing allocationName, standardAllocationName, unlockAmount, unlockValue)

`tok emission weekly <tokenId>`

Get weekly emission data for a token, broken down by allocation.

tok emission weekly arbitrum
tok emission weekly arbitrum --start 2024-01-01 --end 2024-06-30
tok emission weekly solana --output json

Argument	Required	Description
`tokenId`	Yes	Token ID

Option	Description
`--start <date>`	Start date (`YYYY-MM-DD`)
`--end <date>`	End date (`YYYY-MM-DD`)
`--standard-allocation <names>`	Filter by allocation (comma-separated)
`--page <number>`	Page number
`--page-size <number>`	Items per page

Response fields: Same as emission daily.

Allocations

`tok allocation detail <tokenId>`

Get the standardized allocation distribution for a token — who owns what, and how much is locked vs unlocked.

tok allocation detail solana
tok allocation detail solana --output json

Argument	Required	Description
`tokenId`	Yes	Token ID

Response fields: allocationName, allocationType, standardAllocationName, allocationAmount, allocationUnlockedAmount, allocationLockedAmount, trackedAllocationPercentage Standard allocation categories:

Category	Description
`community`	Community-allocated tokens (airdrops, rewards, ecosystem)
`founderTeam`	Tokens allocated to founders and team members
`privateInvestors`	Tokens allocated to private sale investors
`publicInvestors`	Tokens allocated to public sale participants
`reserve`	Treasury or reserve allocations
`others`	Other or uncategorized allocations

Investors

`tok investor list`

List all investors with optional date filters.

tok investor list
tok investor list --start-latest-funding-date 2024-01-01
tok investor list --output json

Option	Description
`--start-latest-funding-date <date>`	Start date filter for latest funding (`YYYY-MM-DD`)
`--end-latest-funding-date <date>`	End date filter for latest funding (`YYYY-MM-DD`)
`--page <number>`	Page number
`--page-size <number>`	Items per page

`tok investor detail <investorId>`

Get an investor’s portfolio and funding round history.

tok investor detail 123
tok investor detail 123 --is-lead-investor
tok investor detail 123 --funding-date-min 2024-01-01 --output json

Argument	Required	Description
`investorId`	Yes	Investor ID

Option	Description
`--is-lead-investor`	Filter to rounds where investor was lead
`--funding-date-min <date>`	Minimum funding date
`--funding-date-max <date>`	Maximum funding date
`--raised-amount-min <amount>`	Minimum raised amount
`--raised-amount-max <amount>`	Maximum raised amount

Fundraising

`tok fundraising detail <tokenId>`

Get fundraising data for a specific token — rounds, investors, valuations.

tok fundraising detail uniswap
tok fundraising detail solana --output json
tok fundraising detail arbitrum --funding-date-min 2023-01-01

Argument	Required	Description
`tokenId`	Yes	Token ID

Option	Description
`--funding-date-min <date>`	Minimum funding date
`--funding-date-max <date>`	Maximum funding date
`--raised-amount-min <amount>`	Minimum raised amount
`--raised-amount-max <amount>`	Maximum raised amount

Response fields: fundingRound, fundingDate, raiseType, amountRaised, valuation, pricePerToken, sourceURLList, numberOfInvestors, investors (containing investorId, investorName, isLeadInvestor)

Burns

`tok burn list`

List all tokens that have burn event data.

tok burn list
tok burn list --token-id 1,2,3
tok burn list --output json

Option	Description
`--token-id <ids>`	Filter by token IDs (comma-separated)
`--page <number>`	Page number
`--page-size <number>`	Items per page

`tok burn detail <tokenId>`

Get burn events for a specific token.

tok burn detail solana
tok burn detail ethereum --start 2024-01-01 --end 2024-12-31
tok burn detail bnb --output json

Argument	Required	Description
`tokenId`	Yes	Token ID

Option	Description
`--start <date>`	Start date (`YYYY-MM-DD`)
`--end <date>`	End date (`YYYY-MM-DD`)

Response fields: burnEventLabel, burnType, burnDate, amount, metadata (containing burners, burnReasons)

Buybacks

`tok buyback list`

List all tokens that have buyback event data.

tok buyback list
tok buyback list --token-id 1,2,3
tok buyback list --output json

Option	Description
`--token-id <ids>`	Filter by token IDs (comma-separated)
`--page <number>`	Page number
`--page-size <number>`	Items per page

`tok buyback detail <tokenId>`

Get buyback events for a specific token.

tok buyback detail solana
tok buyback detail bnb --start 2024-01-01 --end 2024-12-31
tok buyback detail bnb --output json

Argument	Required	Description
`tokenId`	Yes	Token ID

Option	Description
`--start <date>`	Start date (`YYYY-MM-DD`)
`--end <date>`	End date (`YYYY-MM-DD`)

Response fields: buybackEventLabel, buybackType, buybackDate, tokenAmount, value, spentAmount, spentUnit, targetAddress, buyerAddress, resolution, basis

Utilities

`tok schema`

Print the full command schema as JSON — useful for tooling, documentation generation, and AI agent discovery.

tok schema
tok schema --pretty
tok schema --pretty | jq '.commands | keys'

Option	Description
`--pretty`	Pretty-print with 2-space indent

Environment Variables

Variable	Description	Default
`TOKENOMIST_API_KEY`	API key for authentication	—
`TOKENOMIST_BASE_URL`	Custom API base URL	`https://api.tokenomist.ai`
`TOKENOMIST_NO_BANNER`	Set to `1` to suppress the welcome banner when running `tok` with no arguments	—
`NO_UPDATE_NOTIFIER`	Set to `1` to disable update check notifications	—
`CI`	Set to `1` to disable update notifier and welcome banner in CI environments	—

Error Handling

The CLI handles errors with descriptive messages and automatically retries transient failures with exponential backoff (up to 3 attempts with 1s, 2s, 4s delays plus jitter).

Error	Cause	Solution
`UNAUTHORIZED`	Missing or invalid API key	Run `tok auth login` or check your key
`RATE_LIMITED`	Too many requests	Wait and retry, or reduce request frequency
`NOT_FOUND`	Invalid token ID or resource	Check the ID with `tok token search`
`SERVER_ERROR`	API server issue	Retry after a moment — the CLI retries automatically

​Global Options

​Authentication

​tok auth login

​tok auth status

​tok auth logout

​Tokens

​tok token list

​tok token search <query>

​Unlocks

​tok unlock list

​tok unlock upcoming

​tok unlock events <tokenId>

​Emissions

​tok emission daily <tokenId>

​tok emission weekly <tokenId>

​Allocations

​tok allocation detail <tokenId>

​Investors

​tok investor list

​tok investor detail <investorId>

​Fundraising

​tok fundraising detail <tokenId>

​Burns

​tok burn list

​tok burn detail <tokenId>

​Buybacks

​tok buyback list

​tok buyback detail <tokenId>

​Utilities

​tok schema

​Environment Variables

​Error Handling

Global Options

Authentication

`tok auth login`

`tok auth status`

`tok auth logout`

Tokens

`tok token list`

`tok token search <query>`

Unlocks

`tok unlock list`

`tok unlock upcoming`

`tok unlock events <tokenId>`

Emissions

`tok emission daily <tokenId>`

`tok emission weekly <tokenId>`

Allocations

`tok allocation detail <tokenId>`

Investors

`tok investor list`

`tok investor detail <investorId>`

Fundraising

`tok fundraising detail <tokenId>`

Burns

`tok burn list`

`tok burn detail <tokenId>`

Buybacks

`tok buyback list`

`tok buyback detail <tokenId>`

Utilities

`tok schema`

Environment Variables

Error Handling