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: tokenomisttokenlist, tokenomistresolvetoken, tokenomistallocations, tokenomistallocationssummary, tokenomistdailyemission, tokenomistunlockevents, tokenomisttoken_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 snakecase. The most common mistake: looking for allocationpercentage when the field is actually trackedAllocationPercentage. Always inspect the dict before scripting.

Function Signatures

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

Response Schemas

tokenomistallocationssummary(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")

tokenomistunlockevents(query="ARB"):

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

tokenomistdailyemission(query="ARB"):

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

tokenomistresolvetoken(query="ARB"):

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

matchtype can be: "exactsymbol", "exactid", "exactname", "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: $TOKENMISTAPIKEY
• Base URL: https://api.tokenomist.ai
• This skill uses core/httpclient.py (proxiedget), 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

tokenomisttokenlist

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

tokenomistresolvetoken

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

tokenomistallocationssummary

Compact allocation summary wrapper (v2):

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

tokenomistdailyemission

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

tokenomistunlockevents

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

tokenomisttokenoverview

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.

Recommended workflow

1. If user query is ambiguous, call tokenomistresolvetoken first.
2. For comprehensive analysis, call tokenomisttokenoverview once.
3. For allocations-specific questions, prefer tokenomistallocationssummary (fewest fields, least ambiguity).
4. If full detail is needed, call tokenomist_allocations and read:

- normalized.topallocations - normalized.coverage.trackedpercentagesum - normalized.coverage.trackedsumcloseto_100

1. Only call granular tools when user asks one specific dataset.
2. 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).