Back to Details

tokenomist

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Script Usage

脚本使用方法

Script-mode skill — read this file, then invoke from a 
bash
block:
bash
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,
)
脚本模式技能 — 阅读此文件后，从
bash
块中调用：
bash
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

解析符号 -> 代币ID

print(tokenomist_resolve_token(query="ARB"))
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.
print(json.dumps(tokenomist_token_overview(query="ARB"), indent=2)) EOF

`exports.py`中的可用函数：`tokenomist_token_list`,
`tokenomist_resolve_token`, `tokenomist_allocations`,
`tokenomist_allocations_summary`, `tokenomist_daily_emission`,
`tokenomist_unlock_events`, `tokenomist_token_overview`.
直接查看`exports.py`获取确切签名。

Tokenomist (Tokenomist API)

Tokenomist（Tokenomist API）

Use this skill for token unlock timeline analysis.
使用此技能进行代币解锁时间线分析。

Function Reference (full signatures + return shapes)

函数参考（完整签名 + 返回结构）

All functions live in 
exports.py
.
所有函数都在
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.
所有Tokenomist响应字段使用camelCase，而非snake_case。 最常见的错误：寻找
allocation_percentage
，但实际字段是
trackedAllocationPercentage
。编写脚本前请务必检查字典结构。

Function Signatures

函数签名

FunctionSignature
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".
函数签名说明
tokenomist_token_list()
列出所有支持的代币（ID + 符号 + 名称）
tokenomist_resolve_token(query)
返回字典 — 
{match_type, token: {id, symbol, name, marketCap, ...}, candidates}
。用于将类似"ARB"的符号转换为标准ID"arbitrum"，再进行其他调用（大多数其他端点接受两种格式）。
tokenomist_allocations(query)
完整的原始分配数据（粒度细，已知时包含每个接收方的明细）
tokenomist_allocations_summary(query)
汇总的分配摘要 — 推荐用于分析/图表制作
tokenomist_daily_emission(query, start=None, end=None)
每日释放时间表（日期 + 数量）
tokenomist_unlock_events(query, start=None, end=None)
Cliff解锁事件列表
tokenomist_token_overview(query, start=None, end=None, include_allocations=True, include_emission=True, include_events=True)
复合调用 — 将概览 + 分配 + 释放 + 事件整合为一个响应。适用于"获取代币X的所有信息"场景。
start
/ 
end
接受ISO 8601格式日期（
"2026-01-01"
）或unix时间戳。同时省略则表示"所有可用历史数据"。

Response Schemas

响应结构

tokenomist_allocations_summary(query="ARB")
:
json
{
  "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")
:
json
{
  "data": [
    {
      "eventDate": "2026-...",
      "tokenAmount": ...,
      "tokenAmountUSD": ...,
      "allocationName": "Investors",
      "allocationType": "Scheduled"
    }
  ]
}
tokenomist_daily_emission(query="ARB")
:
json
{
  "data": [
    {"date": "2026-...", "amountEmitted": ..., "amountEmittedUSD": ...}
  ]
}
tokenomist_resolve_token(query="ARB")
:
json
{
  "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.
tokenomist_allocations_summary(query="ARB")
:
json
{
  "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
      },
      ...
    ]
  }
}
allocations
项中的常见误区：
  • 百分比字段：
    trackedAllocationPercentage
    （不是
    allocation_percentage
    / 
    percentage
    / 
    pct
    ）
  • 三个独立的数量字段：
    allocationAmount
    （总数）、
    allocationUnlockedAmount
    、
    allocationLockedAmount
  • 类型字段：
    allocationType
    — 字符串值如
    "TBD"
    、
    "Scheduled"
    、
    "Vested"
  • 标准分类名称：
    standardAllocationName
    （例如"Reserve"、"Founder / Team"、"Private Investors"）
tokenomist_unlock_events(query="ARB")
:
json
{
  "data": [
    {
      "eventDate": "2026-...",
      "tokenAmount": ...,
      "tokenAmountUSD": ...,
      "allocationName": "Investors",
      "allocationType": "Scheduled"
    }
  ]
}
tokenomist_daily_emission(query="ARB")
:
json
{
  "data": [
    {"date": "2026-...", "amountEmitted": ..., "amountEmittedUSD": ...}
  ]
}
tokenomist_resolve_token(query="ARB")
:
json
{
  "match_type": "exact_symbol",
  "token": {
    "id": "arbitrum",
    "name": "Arbitrum",
    "symbol": "ARB",
    "listedMethod": "INTERNAL",
    "marketCap": 721937871,
    "circulatingSupply": 6150718438,
    "maxSupply": 10000000000
  },
  "candidates": []
}
match_type
可以是：
"exact_symbol"
、
"exact_id"
、
"exact_name"
、
"fuzzy"
或
"none"
。当为模糊匹配时，
candidates
列出用于消歧的备选代币。

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.
当存在多个API版本时，请始终使用最新稳定版本：
  • 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
    )
除非用户明确要求旧版行为，否则请勿降级版本。

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.
  • 请求头：
    x-api-key: $TOKENMIST_API_KEY
  • 基础URL：
    https://api.tokenomist.ai
  • 此技能使用
    core/http_client.py
    中的
    proxied_get
    ，因此请求遵循平台sc-proxy行为。
  • 环境中配置的假密钥是可接受的（例如
    fake-tokenomist-key-12345
    ）。在此平台中，请勿将假前缀视为无效。

Tool Map

工具映射

tokenomist_token_list

tokenomist_token_list

Get Token List v4. Supports optional keyword filtering and result cap.
获取Token List v4数据。支持可选的关键词过滤和结果数量限制。

tokenomist_resolve_token

tokenomist_resolve_token

Resolve a token query (id/symbol/name) to canonical 
tokenId
from v4 list.
将代币查询（ID/符号/名称）解析为v4列表中的标准
tokenId
。

tokenomist_allocations

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
通过
token_id
获取Allocations v2数据，输出已归一化以优化Agent使用：
  • 主要百分比字段：
    trackedAllocationPercentage
  • 计算的回退值：
    effectivePercentage
  • 包含
    top_allocations
    和
    coverage
    质量摘要
  • 可选
    include_raw=true
    以获取上游负载用于调试

tokenomist_allocations_summary

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
简洁的分配摘要包装器（v2）：
  • 接受
    token_id
    或
    query
    作为参数
  • 需要时自动将查询解析为标准tokenId
  • 返回
    top_allocations
    （可配置
    top_n
    ）和
    coverage
    / 
    quality
    标记
  • 当用户询问"顶级分配类别"且需要简洁响应时，这是最佳默认选择

tokenomist_daily_emission

tokenomist_daily_emission

Fetch Daily Emission v2 by 
token_id
and optional 
start/end
(
YYYY-MM-DD
).
通过
token_id
和可选的
start/end
（
YYYY-MM-DD
）获取Daily Emission v2数据。

tokenomist_unlock_events

tokenomist_unlock_events

Fetch Unlock Events v4 by 
token_id
and optional 
start/end
(
YYYY-MM-DD
).
通过
token_id
和可选的
start/end
（
YYYY-MM-DD
）获取Unlock Events v4数据。

tokenomist_token_overview

tokenomist_token_overview

One-call wrapper to reduce tool count:
  1. resolve token
  2. fetch allocations v2
  3. fetch daily emission v2
  4. fetch unlock events v4
Use this by default when user asks broad tokenomics overview and you want minimal tool calls.
一站式调用包装器以减少工具调用次数：
  1. 解析代币
  2. 获取allocations v2数据
  3. 获取daily emission v2数据
  4. 获取unlock events v4数据
当用户询问全面的代币经济概览且希望最小化工具调用时，请默认使用此函数。

Recommended workflow

推荐工作流

  1. If user query is ambiguous, call 
    tokenomist_resolve_token
    first.
  2. For comprehensive analysis, call 
    tokenomist_token_overview
    once.
  3. For allocations-specific questions, prefer 
    tokenomist_allocations_summary
    (fewest fields, least ambiguity).
  4. 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
  5. Only call granular tools when user asks one specific dataset.
  6. Keep dates UTC and use 
    YYYY-MM-DD
    .
  1. 如果用户查询存在歧义，先调用
    tokenomist_resolve_token
    。
  2. 如需全面分析，调用一次
    tokenomist_token_overview
    。
  3. 针对分配相关问题，优先使用
    tokenomist_allocations_summary
    （字段最少，歧义最少）。
  4. 如果需要完整细节，调用
    tokenomist_allocations
    并查看： 
    • normalized.top_allocations
    • normalized.coverage.tracked_percentage_sum
    • normalized.coverage.tracked_sum_close_to_100
  5. 仅当用户询问特定数据集时，才调用粒度更细的工具。
  6. 日期保持UTC格式，使用
    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
    ).
  • unlock-events v4
    专注于cliff解锁（移除了线性启动/挖矿收益类事件）。
  • daily-emission v2
    和
    allocations v2
    包含上架方式上下文（
    INTERNAL/AI/EXTERNAL
    ）。