v1.2.0 to v2.0.0

80 added, 144 removed. Audit A to A.

---

name: tokenomist

- version: 1.2.0

- description: "Token unlock schedules, cliff events, daily emissions, allocation breakdowns, and supply pressure analytics via Tokenomist API"

- tools:

- - tokenomist_token_list

- - tokenomist_resolve_token

- - tokenomist_allocations

- - tokenomist_allocations_summary

- - tokenomist_daily_emission

- - tokenomist_unlock_events

- - tokenomist_token_overview

+ version: 2.0.0

+ description: Tokenomist unlock/emission/allocation API skill. Use when users ask token unlock schedules, cliff unlock events, daily emissions, allocation breakdowns, or tokenomics supply pressure analytics.

+ delivery: script

+ protected: true

metadata:

starchild:

emoji: "🧩"

skillKey: tokenomist

requires:

env:

- TOKENMIST_API_KEY

user-invocable: false

disable-model-invocation: false

---

- # Tokenomist (Tokenomist API)

- Token unlock schedules, cliff events, daily emissions, allocation breakdowns, and supply pressure analytics.

- ## Version Policy (hard rule)

- - Token List → **v4** (`/v4/token/list`)

- - Allocations → **v2** (`/v2/allocations`)

- - Daily Emission → **v2** (`/v2/daily-emission`)

- - Unlock Events → **v4** (`/v4/unlock/events`)

- Do not downgrade unless user explicitly asks.

- ## Auth + Proxy

- - Header: `x-api-key: $TOKENMIST_API_KEY`

- - Base URL: `https://api.tokenomist.ai`

- - Uses `core/http_client.py` (`proxied_get`) — sc-proxy handles key replacement.

- - Fake key in env (e.g. `fake-tokenomist-key-12345`) is expected. Never treat as invalid.

- ## Keyword → Tool Lookup

- > **Priority rule**: Specific tool wins over `token_overview`. If an unlock/cliff/emission keyword matches, use that specific tool — do NOT fall back to `token_overview`.

- |--------|------------------------------|------|--------|

- ## ⛔ HARD LIMITS — These Rules Are Non-Negotiable

- 1. **NEVER call `bash` after any `tokenomist_*` tool** — the tools return structured data directly. No post-processing with bash needed.

- 2. **NEVER call `bash` to sum, filter, or sort emission data** — compute from the tool result in memory.

- 3. **NEVER call more than 3 `tokenomist_*` tools per question** — use `tokenomist_token_overview` for broad questions.

- 4. **NEVER pass symbol string directly to granular tools** — resolve first, or use tools that auto-resolve.

- 5. **NEVER use `token_overview` when unlock/cliff/emission keywords present** — use the specific tool instead.

+ ## Script Usage

- ---

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

- ## MISTAKES — Read Before Calling

+ ```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,

+ )

- ### ❌ MISTAKE 1: Calling 4 tools for a general tokenomics question

- ```

- User: "ARB 的 tokenomics 情况"

- ❌ WRONG: tokenomist_resolve_token → tokenomist_allocations → tokenomist_daily_emission → tokenomist_unlock_events

- ✅ RIGHT: tokenomist_token_overview(query="ARB") ← does all 4 in one call

- ```

+ # Resolve symbol -> token id

+ print(tokenomist_resolve_token(query="ARB"))

- ### ❌ MISTAKE 2: Using allocations instead of allocations_summary

- ```

- User: "ARB 的代币分配"

- ❌ WRONG: tokenomist_allocations(token_id="arb") ← returns raw verbose data

- ✅ RIGHT: tokenomist_allocations_summary(query="ARB") ← concise, auto-resolves, has quality flags

+ # Full overview

+ print(json.dumps(tokenomist_token_overview(query="ARB"), indent=2))

+ EOF

```

- Only use `tokenomist_allocations` when user explicitly asks for raw/full data or debugging.

- ### ❌ MISTAKE 3: Passing symbol directly without resolving

- ```

- ❌ WRONG: tokenomist_unlock_events(token_id="ARB") ← might not match API's internal ID

- ✅ RIGHT: tokenomist_resolve_token(query="ARB") → get canonical token_id → then call events

- ```

- Exception: `tokenomist_token_overview` and `tokenomist_allocations_summary` auto-resolve — no need to call resolve first.

+ 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.

- ### ❌ MISTAKE 4: Forgetting date format

- ```

- ❌ WRONG: tokenomist_unlock_events(token_id="arb", start="2025/01/01")

- ✅ RIGHT: tokenomist_unlock_events(token_id="arb", start="2025-01-01") ← YYYY-MM-DD only

- ```

- ### ❌ MISTAKE 5: Calling bash after tokenomist tools

- ```

- User: "ARB 本月解锁总量是多少？"

- ❌ WRONG: tokenomist_daily_emission(token_id="arb") → bash("python3 -c 'import json; ...'")

- ✅ RIGHT: tokenomist_daily_emission(token_id="arb") ← sum the values directly from result, no bash

- ```

- **Rule**: tokenomist tools return structured JSON. Sum/filter/sort IN YOUR HEAD. Never spawn bash to process the result.

+ # Tokenomist (Tokenomist API)

- ### ❌ MISTAKE 6: Using token_overview for unlock/cliff-specific questions

+ Use this skill for token unlock timeline analysis.

- **Any question containing unlock/cliff intent → `tokenomist_unlock_events`, never `token_overview`**

+ ## Version Policy (hard rule)

- ```

- User: "ARB 下一个 cliff 解锁事件是什么时候？"

- ❌ WRONG: tokenomist_token_overview(query="ARB") ← ignores specific intent

- ✅ RIGHT: tokenomist_resolve_token(query="ARB") → tokenomist_unlock_events(token_id=..., start="today")

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

- User: "APT 的解锁时间表"

- ❌ WRONG: tokenomist_token_overview(query="APT")

- ✅ RIGHT: tokenomist_resolve_token(query="APT") → tokenomist_unlock_events(token_id=...)

+ - 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`)

- User: "SUI 什么时候解锁？"

- ❌ WRONG: tokenomist_token_overview(query="SUI")

- ✅ RIGHT: tokenomist_resolve_token(query="SUI") → tokenomist_unlock_events(token_id=...)

- ```

+ Do not downgrade unless user explicitly asks for legacy behavior.

- Full keyword list → always triggers `tokenomist_unlock_events`:

- - English: unlock, cliff, vesting, lockup, token release, unlock schedule, next unlock, upcoming unlock, lockup expiry, when does X unlock

- - Chinese: 解锁, cliff, 解锁时间表, 解锁计划, 什么时候解锁, 下一次解锁, 即将解锁, 锁定到期, 代币释放时间

+ ## Auth + Proxy

- > **Generalisation note**: Even if the question seems broad ("tell me about ARB unlocks"), as long as "unlock" is in the question, use `tokenomist_unlock_events` — not `token_overview`.

+ - 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.

- ### ❌ MISTAKE 7: Using token_overview then verifying with bash

- ```

- User: "给我 ARB 的 tokenomics 概览"

- ❌ WRONG: tokenomist_token_overview(query="ARB") → bash("echo checking...") → bash("python3 ...")

- ✅ RIGHT: tokenomist_token_overview(query="ARB") ← STOP. Format the result and reply. No bash verification.

- ```

+ ## Tool Map

- ### ❌ MISTAKE 8: Confusing tokenomist with coingecko for supply data

- ```

- User: "ARB 的 circulating supply"

- ❌ WRONG: tokenomist_* ← Tokenomist does unlocks/emissions, not live supply

- ✅ RIGHT: coin_price(ids="arbitrum") or cg_coin_data(id="arbitrum") ← CoinGecko has supply

- ```

- **Boundary**: Tokenomist = unlock schedules & emission pressure. CoinGecko = live supply & market cap.

+ ### `tokenomist_token_list`

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

- ## Tool Reference

+ ### `tokenomist_resolve_token`

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

- ### `tokenomist_token_overview` ⭐ Default choice

- One-call wrapper: resolve → allocations → emission → unlock events.

- Use when user asks broad tokenomics question.

+ ### `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 view with `top_allocations`, `coverage`, `quality` flags.

- Accepts `token_id` or `query` (auto-resolves).

+ 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_allocations`

- Full allocation data. Use only when user needs raw detail or `include_raw=true` for debugging.

+ ### `tokenomist_daily_emission`

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

### `tokenomist_unlock_events`

- Cliff unlock events (v4). Linear/mining-yield events excluded.

- Params: `token_id` (required), `start`/`end` (optional, YYYY-MM-DD).

- ### `tokenomist_daily_emission`

- Daily emission schedule (v2).

- Params: `token_id` (required), `start`/`end` (optional, YYYY-MM-DD).

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

- ### `tokenomist_resolve_token`

- Resolve symbol/name → canonical `tokenId`. Use before granular tools.

+ ### `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

- ### `tokenomist_token_list`

- Full token list (v4). Use for browsing, not single-token lookup.

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

- ## Interpreting Results — Supply Pressure

+ ## Recommended workflow

- When presenting unlock/emission data, help user assess **supply pressure**:

+ 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`.

- | Signal | Interpretation |

- |--------|---------------|

- | Large cliff unlock within 7 days | ⚠️ Short-term sell pressure likely |

- | Daily emission > 0.5% of circulating supply | ⚠️ Persistent dilution |

- | Unlock to team/investor wallets | Higher sell probability than ecosystem/community |

- | Multiple unlocks clustering in same week | Compounding pressure — flag explicitly |

- | No major unlocks for 30+ days | Reduced supply-side pressure |

+ ## Notes

- **Always contextualise**: "ARB has a $50M team unlock in 3 days" is more actionable than "ARB has an unlock event".

+ - `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`).