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,
)

# 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")

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.

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

tokenomist

NPX Install

Tags

SKILL.md Content

Script Usage

Tokenomist (Tokenomist API)

Function Reference (full signatures + return shapes)

⚠️ Field naming convention (READ THIS FIRST)

Function Signatures

Response Schemas

Version Policy (hard rule)

Auth + Proxy

Tool Map

`tokenomist_token_list`

`tokenomist_resolve_token`

`tokenomist_allocations`

`tokenomist_allocations_summary`

`tokenomist_daily_emission`

`tokenomist_unlock_events`

`tokenomist_token_overview`

Recommended workflow

Notes