mcpField
T
tokenomist

tokenomist

github.com/starchild-ai-agent数据与数据库30302 次安装6 天前更新
代码仓库

关于 tokenomist

tokenomist 是一项脚本型技能，通过 Tokenomist API 分析代币解锁时间线。它提供代币解析、分配数据、每日排放和解锁事件查询，并支持一次调用获取综合概览。

主要功能

  1. 01列出并解析代币标识符
  2. 02获取分配数据及摘要
  3. 03查询每日排放计划
  4. 04查询悬崖式解锁事件
  5. 05通过代币概览组合多类数据

适用场景

  1. 01查找代币的标准标识符
  2. 02汇总代币分配类别
  3. 03查看指定日期范围内的排放
  4. 04检查计划中的悬崖式解锁

安装

复制下面的命令，在终端中运行。

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

安装后在 Claude Code 中输入/tokenomist确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

__init__.py
.gitignore
exports.py
scripts/
test_tokenomist_faq_extended.py
test_tokenomist_tools.py
test_tokenomist.py
tools/
__init__.py
client.py
tokenomist_tools.py

详细介绍

脚本用法

脚本模式技能 — 阅读此文件，然后从 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
print(tokenomist_resolve_token(query="ARB"))

# Full overview
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）

使用此技能分析代币解锁时间线。

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

所有函数都位于 exports.py 中。

⚠️ 字段命名约定（请先阅读）

所有 Tokenomist 响应字段都使用 camelCase，而不是 snake_case。 最常见的错误：查找 allocation_percentage，但实际字段是 trackedAllocationPercentage。编写脚本前务必先检查字典。

函数签名
函数签名
tokenomist_token_list()列出所有受支持的代币（id + symbol + name）
tokenomist_resolve_token(query)dict — {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)悬崖式解锁事件列表
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 时间戳。省略两者表示“所有可用历史数据”。

响应结构

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
      },
      ...
    ]
  }
}

allocations 项中的常见问题：

  • 百分比字段：trackedAllocationPercentage（不是 allocation_percentage / percentage / pct）
  • 三个独立的金额字段：allocationAmount（总额）、allocationUnlockedAmount、allocationLockedAmount
  • 类型字段：allocationType — 字符串值，例如 "TBD"、"Scheduled"、"Vested"
  • 标准类别名称：standardAllocationName（例如 "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 可以是："exact_symbol"、"exact_id"、"exact_name"、 "fuzzy" 或 "none"。模糊匹配时，candidates 会列出用于消除歧义的备选代币。

版本策略（硬性规则）

存在多个 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）

除非用户明确要求使用旧版行为，否则不要降级。

身份验证 + 代理

  • Header：x-api-key: $TOKENMIST_API_KEY
  • Base URL：https://api.tokenomist.ai
  • 此技能使用 core/http_client.py（proxied_get），因此请求遵循平台 sc-proxy 行为。
  • 环境中配置假密钥是预期情况（例如 fake-tokenomist-key-12345）。在此平台上，切勿将假密钥前缀视为无效。

工具映射

tokenomist_token_list

获取 Token List v4。支持可选的关键词筛选和结果数量上限。

tokenomist_resolve_token

将代币查询（id/symbol/name）解析为 v4 列表中的规范 tokenId。

tokenomist_allocations

按 token_id 获取 Allocations v2，并返回针对 Agent 使用进行优化的规范化输出：

  • 主要百分比字段：trackedAllocationPercentage
  • 计算得出的备用字段：effectivePercentage
  • 包含 top_allocations 和 coverage 质量摘要
  • 可选使用 include_raw=true 调试上游负载
tokenomist_allocations_summary

精简的 Allocation 摘要封装（v2）：

  • 接受 token_id 或 query
  • 必要时自动将查询解析为规范的 tokenId
  • 返回 top_allocations（可配置 top_n）以及 coverage / quality 标记
  • 当用户询问“主要 Allocation 类别”，且你希望得到一份简洁答复时，这是最佳默认选择
tokenomist_daily_emission

按 token_id 和可选的 start/end（YYYY-MM-DD）获取 Daily Emission v2。

tokenomist_unlock_events

按 token_id 和可选的 start/end（YYYY-MM-DD）获取 Unlock Events v4。

tokenomist_token_overview

一站式封装，可减少工具调用次数：

  1. 解析代币
  2. 获取 Allocations v2
  3. 获取 Daily Emission v2
  4. 获取 Unlock Events v4

当用户询问宽泛的代币经济学概览，且你希望尽量减少工具调用时，默认使用此工具。

推荐工作流

  1. 如果用户的查询有歧义，请先调用 tokenomist_resolve_token。
  2. 如需全面分析，请调用一次 tokenomist_token_overview。
  3. 对于 Allocation 相关问题，优先使用 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 格式。

注意事项

  • unlock-events v4 聚焦于 cliff 解锁（已移除线性开始／挖矿收益类事件）。
  • daily-emission v2 和 allocations v2 包含上架方式的相关信息（INTERNAL/AI/EXTERNAL）。

评论

支持 Markdown