--- 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 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`. | Intent | Trigger keywords (any match) | Tool | โ›” NOT | |--------|------------------------------|------|--------| | Broad overview | "tokenomics overview", "ๅ…จ้ขๅˆ†ๆž", "็ปผๅˆๅˆ†ๆž", "ๅ‘Š่ฏ‰ๆˆ‘ๆ‰€ๆœ‰" | `tokenomist_token_overview` | 4 tools separately | | Allocation summary | "allocation", "ๅˆ†้…", "who holds", "่ฐๆŒๆœ‰", "top holders", "team allocation" | `tokenomist_allocations_summary` | `tokenomist_allocations` | | Allocation raw | "full breakdown", "raw allocation", "complete allocation data" | `tokenomist_allocations` | โ€” | | **Unlock/Cliff** โšก | "unlock", "่งฃ้”", "cliff", "vesting", "lockup", "token release" | `tokenomist_unlock_events` | โ›” `token_overview` | | **Unlock/Cliff** โšก | "unlock schedule", "่งฃ้”ๆ—ถ้—ด่กจ", "่งฃ้”่ฎกๅˆ’", "vesting schedule" | `tokenomist_unlock_events` | โ›” `token_overview` | | **Unlock/Cliff** โšก | "next unlock", "when unlock", "ไป€ไนˆๆ—ถๅ€™่งฃ้”", "ไธ‹ไธ€ๆฌก่งฃ้”", "ๅณๅฐ†่งฃ้”" | `tokenomist_unlock_events` | โ›” `token_overview` | | **Unlock/Cliff** โšก | "lockup expiry", "้”ๅฎšๅˆฐๆœŸ", "ไปฃๅธ้‡Šๆ”พๆ—ถ้—ด", "upcoming unlock" | `tokenomist_unlock_events` | โ›” `token_overview` | | Daily emission | "daily emission", "ๆฏๆ—ฅ้‡Šๆ”พ", "emission rate", "daily release" | `tokenomist_daily_emission` | โ€” | | Token lookup | "find token", "which token id", "token id for X" | `tokenomist_resolve_token` | โ€” | | Token list | "list all tokens", "what tokens tracked" | `tokenomist_token_list` | โ€” | ## โ›” 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. --- ## MISTAKES โ€” Read Before Calling ### โŒ 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 ``` ### โŒ 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 ``` 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. ### โŒ 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. ### โŒ MISTAKE 6: Using token_overview for unlock/cliff-specific questions **Any question containing unlock/cliff intent โ†’ `tokenomist_unlock_events`, never `token_overview`** ``` 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") User: "APT ็š„่งฃ้”ๆ—ถ้—ด่กจ" โŒ WRONG: tokenomist_token_overview(query="APT") โœ… RIGHT: tokenomist_resolve_token(query="APT") โ†’ tokenomist_unlock_events(token_id=...) User: "SUI ไป€ไนˆๆ—ถๅ€™่งฃ้”๏ผŸ" โŒ WRONG: tokenomist_token_overview(query="SUI") โœ… RIGHT: tokenomist_resolve_token(query="SUI") โ†’ tokenomist_unlock_events(token_id=...) ``` 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, ่งฃ้”ๆ—ถ้—ด่กจ, ่งฃ้”่ฎกๅˆ’, ไป€ไนˆๆ—ถๅ€™่งฃ้”, ไธ‹ไธ€ๆฌก่งฃ้”, ๅณๅฐ†่งฃ้”, ้”ๅฎšๅˆฐๆœŸ, ไปฃๅธ้‡Šๆ”พๆ—ถ้—ด > **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`. ### โŒ 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. ``` ### โŒ 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. ## Tool Reference ### `tokenomist_token_overview` โญ Default choice One-call wrapper: resolve โ†’ allocations โ†’ emission โ†’ unlock events. Use when user asks broad tokenomics question. ### `tokenomist_allocations_summary` Compact allocation view with `top_allocations`, `coverage`, `quality` flags. Accepts `token_id` or `query` (auto-resolves). ### `tokenomist_allocations` Full allocation data. Use only when user needs raw detail or `include_raw=true` for debugging. ### `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). ### `tokenomist_resolve_token` Resolve symbol/name โ†’ canonical `tokenId`. Use before granular tools. ### `tokenomist_token_list` Full token list (v4). Use for browsing, not single-token lookup. ## Interpreting Results โ€” Supply Pressure When presenting unlock/emission data, help user assess **supply pressure**: | 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 | **Always contextualise**: "ARB has a $50M team unlock in 3 days" is more actionable than "ARB has an unlock event".