tokenomist

Q: How do I install tokenomist?

Run npx skills add https://github.com/starchild-ai-agent/official-skills --skill tokenomist in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tokenomist/ (personal) or .claude/skills/tokenomist/ (project).

by starchild-ai-agentAI & Agents

Token unlock schedules, cliff events, daily emissions, allocation breakdowns. Use when checking upcoming unlocks, supply pressure, or vesting cliffs before a trade (e.g. ARB unlock, ENA emission, SUI cliff).

Installs: 302
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/starchild-ai-agent/official-skills --skill tokenomist

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads tokenomist automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Script Usage

Script-mode skill — read this file, then invoke from a bash block:

python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/tokenomist")
from exports import (
    tokenomist_resolve_token,
    tokenomist_token_overview,
    tokenomist_unlock_events,
    tokenomist_daily_emission,
    tokenomist_allocations,
)

# Resolve symbol -> token id
print(tokenomist_resolve_token(query="ARB"))

# Full overview
print(json.dumps(tokenomist_token_overview(query="ARB"), indent=2))
EOF

Available functions in exports.py: tokenomist_token_list, tokenomist_resolve_token, tokenomist_allocations, tokenomist_allocations_summary, tokenomist_daily_emission, tokenomist_unlock_events, tokenomist_token_overview. Read exports.py directly for exact signatures.

Tokenomist (Tokenomist API)

Use this skill for token unlock timeline analysis.

Function Reference (full signatures + return shapes)

All functions live in exports.py.

⚠️ Field naming convention (READ THIS FIRST)

All Tokenomist response fields use camelCase, not snake_case. The most common mistake: looking for allocation_percentage when the field is actually trackedAllocationPercentage. Always inspect the dict before scripting.

Function Signatures

Function	Signature
`tokenomist_token_list()`	List all supported tokens (id + symbol + name)
`tokenomist_resolve_token(query)`	dict — `{match_type, token: {id, symbol, name, marketCap, ...}, candidates}`. Use this to convert a symbol like "ARB" into the canonical id "arbitrum" before other calls (most other endpoints accept either).
`tokenomist_allocations(query)`	Full raw allocation data (granular, includes per-recipient breakdown when known)
`tokenomist_allocations_summary(query)`	Aggregated allocation summary — recommended for analysis/charts
`tokenomist_daily_emission(query, start=None, end=None)`	Daily emission schedule (date + amount)
`tokenomist_unlock_events(query, start=None, end=None)`	Cliff unlock events list
`tokenomist_token_overview(query, start=None, end=None, include_allocations=True, include_emission=True, include_events=True)`	Composite call — bundles overview + allocations + emission + events into one response. Use this for "give me everything about token X".

start / end accept ISO 8601 dates ("2026-01-01") or unix timestamps. Omit both for "all available history".

Response Schemas

tokenomist_allocations_summary(query="ARB"):

{
  "metadata": {"queryDate": "2026-05-04T..."},
  "status": true,
  "data": {
    "name": "Arbitrum",
    "symbol": "ARB",
    "listedMethod": "INTERNAL",
    "maxSupply": 10000000000,
    "lastUpdatedDate": "2025-06-11T10:31:15Z",
    "totalUnlockedAmount": 5410170736.76,
    "totalLockedAmount": 1186004337.54,
    "totalUntrackedAmount": 0,
    "totalTBDLockedAmount": 3403750000,
    "allocations": [
      {
        "allocationName": "Arbitrum DAO Treasury",
        "allocationType": "TBD",
        "standardAllocationName": "Reserve",
        "allocationUnlockedAmount": 0,
        "allocationLockedAmount": 3403750000,
        "allocationAmount": 3403750000,
        "trackedAllocationPercentage": 34.0375
      },
      ...
    ]
  }
}

Common pitfalls in allocations items:

Percentage field: trackedAllocationPercentage (NOT allocation_percentage / percentage / pct)
Three separate amount fields: allocationAmount (total), allocationUnlockedAmount, allocationLockedAmount
Type field: allocationType — string values like "TBD", "Scheduled", "Vested"
Standard category name: standardAllocationName (e.g. "Reserve", "Founder / Team", "Private Investors")

tokenomist_unlock_events(query="ARB"):

{
  "data": [
    {
      "eventDate": "2026-...",
      "tokenAmount": ...,
      "tokenAmountUSD": ...,
      "allocationName": "Investors",
      "allocationType": "Scheduled"
    }
  ]
}

tokenomist_daily_emission(query="ARB"):

{
  "data": [
    {"date": "2026-...", "amountEmitted": ..., "amountEmittedUSD": ...}
  ]
}

tokenomist_resolve_token(query="ARB"):

{
  "match_type": "exact_symbol",
  "token": {
    "id": "arbitrum",
    "name": "Arbitrum",
    "symbol": "ARB",
    "listedMethod": "INTERNAL",
    "marketCap": 721937871,
    "circulatingSupply": 6150718438,
    "maxSupply": 10000000000
  },
  "candidates": []
}

match_type can be: "exact_symbol", "exact_id", "exact_name", "fuzzy", or "none". When fuzzy, candidates lists alternative tokens to disambiguate.

Version Policy (hard rule)

When multiple API versions exist, always use latest stable versions:

Token List API → v4 (/v4/token/list)
Allocations API → v2 (/v2/allocations)
Daily Emission API → v2 (/v2/daily-emission)
Unlock Events API → v4 (/v4/unlock/events)

Do not downgrade unless user explicitly asks for legacy behavior.

Auth + Proxy

Header: x-api-key: $TOKENMIST_API_KEY
Base URL: https://api.tokenomist.ai
This skill uses core/http_client.py (proxied_get), so requests follow platform sc-proxy behavior.
Fake key configured in environment is expected (e.g. fake-tokenomist-key-12345). Never treat fake prefix as invalid in this platform.

Tool Map

`tokenomist_token_list`

Get Token List v4. Supports optional keyword filtering and result cap.

`tokenomist_resolve_token`

Resolve a token query (id/symbol/name) to canonical tokenId from v4 list.

`tokenomist_allocations`

Fetch Allocations v2 by token_id, with normalized output optimized for agent use:

Primary percentage field: trackedAllocationPercentage
Computed fallback: effectivePercentage
top_allocations and coverage quality summary included
Optional include_raw=true for upstream payload debugging

`tokenomist_allocations_summary`

Compact allocation summary wrapper (v2):

Accepts either token_id or query
Auto-resolves query to canonical tokenId when needed
Returns top_allocations (configurable top_n) and coverage / quality flags
Best default when user asks "top allocation buckets" and you want one concise response

`tokenomist_daily_emission`

Fetch Daily Emission v2 by token_id and optional start/end (YYYY-MM-DD).

`tokenomist_unlock_events`

Fetch Unlock Events v4 by token_id and optional start/end (YYYY-MM-DD).

`tokenomist_token_overview`

One-call wrapper to reduce tool count:

resolve token
fetch allocations v2
fetch daily emission v2
fetch unlock events v4

Use this by default when user asks broad tokenomics overview and you want minimal tool calls.

Recommended workflow

If user query is ambiguous, call tokenomist_resolve_token first.
For comprehensive analysis, call tokenomist_token_overview once.
For allocations-specific questions, prefer tokenomist_allocations_summary (fewest fields, least ambiguity).
If full detail is needed, call tokenomist_allocations and read:
- normalized.top_allocations
- normalized.coverage.tracked_percentage_sum
- normalized.coverage.tracked_sum_close_to_100
Only call granular tools when user asks one specific dataset.
Keep dates UTC and use YYYY-MM-DD.

Notes

unlock-events v4 focuses on cliff unlocks (linear start/mining-yield style events removed).
daily-emission v2 and allocations v2 include listing method context (INTERNAL/AI/EXTERNAL).

FAQ

What does the tokenomist skill do?

How do I install tokenomist?

Run npx skills add https://github.com/starchild-ai-agent/official-skills --skill tokenomist in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tokenomist/ (personal) or .claude/skills/tokenomist/ (project).

Which AI agents can use tokenomist?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is tokenomist safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains tokenomist?

It is published by starchild-ai-agent in starchild-ai-agent/official-skills. It has 302 recorded installs.