@tokenomist-ai/tokenomist-cli 0.1.0

package/skills/tokenomist-allocation-breakdown/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: tokenomist-allocation-breakdown
+description: Get the full allocation distribution for a token — who owns what and how much is locked vs unlocked. Use when analyzing supply distribution across team, investors, community, etc.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - TOKENOMIST_API_KEY
+      bins:
+        - tokenomist
+    primaryEnv: TOKENOMIST_API_KEY
+    install:
+      - kind: node
+        package: "@tokenomist-ai/tokenomist-cli"
+        bins: [tokenomist]
+allowed-tools: Bash(tokenomist:*)
+---
+
+# Skill: Allocation Breakdown
+
+Get the full allocation distribution for a token — who owns what and how much is locked vs unlocked.
+
+## When to use
+
+When you need to understand a token's supply distribution across allocations (team, investors, community, ecosystem, etc.).
+
+## Command
+
+```bash
+tokenomist allocation <tokenSlug> --output json
+```
+
+## Example
+
+```bash
+tokenomist allocation solana --output json
+```
+
+## Key output fields
+
+**Top-level:**
+- `name`, `symbol` — token identification
+- `maxSupply` — maximum token supply (null if unlimited)
+- `totalUnlockedAmount` — total tokens currently unlocked
+- `totalLockedAmount` — total tokens still locked
+- `totalUntrackedAmount` — tokens not tracked by Tokenomist
+- `totalTBDLockedAmount` — tokens locked with no defined unlock schedule
+
+**Per allocation (`allocations[]`):**
+- `allocationName` — project-specific allocation name
+- `standardAllocationName` — Tokenomist's standardized category (comparable across projects)
+- `allocationType` — allocation classification
+- `allocationAmount` — total tokens in this allocation
+- `allocationUnlockedAmount` — tokens unlocked from this allocation
+- `allocationLockedAmount` — tokens still locked in this allocation
+- `trackedAllocationPercentage` — % of total tracked supply
+
+## Analysis workflow
+
+1. Get allocation: `tokenomist allocation <slug> --output json`
+2. Check `totalLockedAmount` vs `totalUnlockedAmount` for overall supply status
+3. Look at individual allocations — high locked amounts in "Investor" or "Team" allocations signal future sell pressure
+4. Compare `standardAllocationName` across different tokens for apples-to-apples comparison
+5. Cross-reference with `tokenomist unlock upcoming` to see when locked tokens will release
+
+## Domain Context
+
+- Allocations are **point-in-time analyses**. They reflect the current understanding of token distribution and may be updated as new information becomes available.
+- `standardAllocationName` enables cross-project comparison — different projects may use different names for similar allocations (e.g., "Core Contributors" vs "Team"), but the standard name normalizes this.
+- `totalTBDLockedAmount` represents tokens that are known to be locked but have no defined unlock schedule. Their classification may change as the project releases more information.
+
+## Workflow
+
+- Use allocation data as context for unlock analysis — understanding allocations helps interpret **who** is receiving unlocked tokens and why it matters.
+- Chain with `tokenomist fundraising <slug>` to see investor-specific allocation details and funding round information.
+- Compare `allocationLockedAmount` vs `allocationUnlockedAmount` per allocation to identify which groups still have significant locked positions.

package/skills/tokenomist-burn-buyback/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: tokenomist-burn-buyback
+description: Check token burn and buyback activity. Use when analyzing deflationary mechanisms — burns, buybacks, and net inflation.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - TOKENOMIST_API_KEY
+      bins:
+        - tokenomist
+    primaryEnv: TOKENOMIST_API_KEY
+    install:
+      - kind: node
+        package: "@tokenomist-ai/tokenomist-cli"
+        bins: [tokenomist]
+allowed-tools: Bash(tokenomist:*)
+---
+
+# Skill: Burn & Buyback
+
+Check token burn and buyback activity.
+
+## When to use
+
+When you need to analyze deflationary mechanisms — how many tokens have been permanently burned or bought back from the market.
+
+## Commands
+
+### Burns
+
+List all tokens with burns:
+```bash
+tokenomist burn list --output json
+```
+
+Get burn events for a specific token:
+```bash
+tokenomist burn detail <tokenSlug> --output json
+tokenomist burn detail <tokenSlug> --start 2024-01-01 --end 2024-12-31 --output json
+```
+
+### Buybacks
+
+List all tokens with buybacks:
+```bash
+tokenomist buyback list --output json
+```
+
+Get buyback events for a specific token:
+```bash
+tokenomist buyback detail <tokenSlug> --output json
+tokenomist buyback detail <tokenSlug> --start 2024-01-01 --end 2024-12-31 --output json
+```
+
+## Key output fields
+
+**Burn list:**
+- `totalBurnAmount` — total tokens burned for this token
+
+**Burn detail:**
+- `burns[].burnDate` — when the burn happened
+- `burns[].amount` — tokens burned
+- `burns[].burnType` — type of burn event
+- `burns[].metadata.burnReasons` — why tokens were burned
+
+**Buyback list:**
+- `totalBuybackAmount` — total tokens bought back
+
+**Buyback detail:**
+- `buybacks[].buybackDate` — when the buyback happened
+- `buybacks[].tokenAmount` — tokens bought back
+- `buybacks[].value` — USD value of buyback
+- `buybacks[].spentAmount` / `spentUnit` — what was spent (e.g. USDC)
+
+## Analysis workflow
+
+1. List tokens with burns: `tokenomist burn list --output json`
+2. Compare `totalBurnAmount` across tokens to find most deflationary projects
+3. Drill into a token: `tokenomist burn detail <slug> --output json`
+4. Cross-reference with emissions from `tokenomist emission weekly <slug>` to calculate net inflation
+
+## Domain Context
+
+- A sequential buyback + burn is a **single** deflationary event, not two. Counting both would double-count the supply reduction.
+- Burns from **locked** supply don't reduce circulating supply — they reduce future potential supply instead.
+- The `startDate`/`endDate` filters on burn/buyback detail commands filter by **last activity date**, not the event date range. This is an API quirk — the filters determine which tokens to include based on when they last had activity.
+
+## Workflow
+
+- Cross-reference with `tokenomist emission weekly <slug>` to calculate net inflation: if burns exceed emissions, the token is net deflationary.
+- Use `tokenomist token list --output json` to check `hasBurn`/`hasBuyback` fields before querying detail commands (these fields are only visible in JSON output, not table mode).
+- Compare `totalBurnAmount` across tokens to find the most deflationary projects.

package/skills/tokenomist-emission-report/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: tokenomist-emission-report
+description: Get daily or weekly token emission data with allocation breakdowns. Use when analyzing token inflation, comparing emission rates, or understanding supply increases.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - TOKENOMIST_API_KEY
+      bins:
+        - tokenomist
+    primaryEnv: TOKENOMIST_API_KEY
+    install:
+      - kind: node
+        package: "@tokenomist-ai/tokenomist-cli"
+        bins: [tokenomist]
+allowed-tools: Bash(tokenomist:*)
+---
+
+# Skill: Emission Report
+
+Get daily or weekly token emission data with allocation breakdowns.
+
+## When to use
+
+When you need to analyze token inflation over time, compare emission rates across periods, or understand which allocations are contributing to supply increases.
+
+## Commands
+
+### Daily emission
+```bash
+tokenomist emission daily <tokenSlug> --output json
+tokenomist emission daily arbitrum --start 2024-08-01 --end 2024-08-31 --output json
+```
+
+### Weekly emission
+```bash
+tokenomist emission weekly <tokenSlug> --output json
+tokenomist emission weekly arbitrum --start 2024-01-01 --end 2024-06-30 --output json
+```
+
+## Key output fields
+
+| Field | Description |
+|-------|-------------|
+| `startDate` | Period start |
+| `endDate` | Period end |
+| `unlockAmount` | Tokens emitted in period |
+| `unlockValue` | USD value of emitted tokens |
+| `referencePrice` | Token price used for value calculation |
+| `allocations` | Breakdown by allocation (name, amount, value) |
+| `totalCumulativeUnlockedAmount` | Running total of all unlocked tokens |
+
+## Analysis workflow
+
+1. Get weekly emissions to see the trend: `tokenomist emission weekly <slug> --output json`
+2. Look at `unlockAmount` over time to spot acceleration or deceleration
+3. Check `allocations` to see if emissions are going to investors (sell pressure) vs community/ecosystem (growth)
+4. Compare `unlockValue` against market cap from `tokenomist token list` to assess dilution
+
+## Domain Context
+
+- Emission data shows **scheduled** releases per allocation. Actual on-chain supply may differ due to relocks, delays, or early releases.
+- Compare `unlockValue` against market cap (from `tokenomist token list`) to assess dilution impact.
+- Emissions going to "Investor" or "Team" allocations typically represent higher sell pressure than "Community" or "Ecosystem" allocations.
+
+## Workflow
+
+- Combine with `tokenomist unlock events <slug>` to distinguish between cliff unlocks (large one-time events) and continuous emissions (steady daily/weekly releases).
+- Chain with `tokenomist burn detail <slug>` to calculate net inflation: emissions minus burns = net new supply.
+- Use `tokenomist allocation <slug>` to see the full allocation picture and understand where emissions are going.

package/skills/tokenomist-fundraising-lookup/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: tokenomist-fundraising-lookup
+description: Look up fundraising rounds, investors, and valuation data for tokens. Use when finding who invested, at what valuation, or analyzing investor portfolios.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - TOKENOMIST_API_KEY
+      bins:
+        - tokenomist
+    primaryEnv: TOKENOMIST_API_KEY
+    install:
+      - kind: node
+        package: "@tokenomist-ai/tokenomist-cli"
+        bins: [tokenomist]
+allowed-tools: Bash(tokenomist:*)
+---
+
+# Skill: Fundraising Lookup
+
+Look up fundraising rounds, investors, and valuation data for tokens.
+
+## When to use
+
+When you need to find out who invested in a token, what valuation rounds were raised at, or what an investor's portfolio looks like.
+
+## Commands
+
+### Get fundraising data for a token
+```bash
+tokenomist fundraising <tokenSlug> --output json
+tokenomist fundraising uniswap --output json
+```
+
+Filter by date or amount:
+```bash
+tokenomist fundraising uniswap --funding-date-min 2020-01-01 --raised-amount-min 1000000 --output json
+```
+
+### List all investors
+```bash
+tokenomist investor list --output json
+```
+
+### Get investor detail with portfolio
+```bash
+tokenomist investor detail <investorId> --output json
+tokenomist investor detail <investorId> --is-lead-investor --output json
+```
+
+Filter by date or amount:
+```bash
+tokenomist investor detail <investorId> --funding-date-min 2023-01-01 --raised-amount-min 5000000 --output json
+```
+
+## Key output fields
+
+**Token fundraising:**
+- `totalAmountRaised` — total USD raised across all rounds
+- `investorReleasedPercentage` — how much investor allocation has unlocked
+- `fundingRounds[].fundingRound` — round name (Seed, Series A, etc.)
+- `fundingRounds[].amountRaised` — USD raised in that round
+- `fundingRounds[].valuation` — token valuation at that round
+- `fundingRounds[].pricePerToken` — price investors paid
+- `fundingRounds[].investors` — list of investors in the round
+
+**Investor detail:**
+- `fundingRounds[].tokenId` — which token they invested in
+- `fundingRounds[].isLeadInvestor` — whether they led the round
+- `fundingRounds[].totalAmountRaisedinThatRound` — round size
+
+## Analysis workflow
+
+1. Look up a token: `tokenomist fundraising <slug> --output json`
+2. Compare `pricePerToken` across rounds to see valuation progression
+3. Check `investorReleasedPercentage` — high % means most investor tokens are already unlocked (less future sell pressure)
+4. Look at individual investors: `tokenomist investor detail <id> --output json` to see their full portfolio
+
+## Domain Context
+
+- `pricePerToken` in early rounds vs current market price shows investor ROI — large multiples may indicate sell pressure as investors take profits.
+- `investorReleasedPercentage` indicates future sell pressure — a high percentage means most investor tokens have already unlocked (less remaining overhang).
+- Valuation at each round shows the project's funding trajectory.
+
+## Workflow
+
+- Chain with `tokenomist investor detail <investorId>` to see an investor's full portfolio across multiple tokens.
+- Cross-reference `pricePerToken` with current market data from `tokenomist token list` to calculate investor ROI.
+- Use `tokenomist unlock events <slug>` to see when remaining investor allocations will unlock.

package/skills/tokenomist-token-overview/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: tokenomist-token-overview
+description: Get a summary list of all tracked tokens with market data and supply info. Use when browsing tokens, comparing market caps, or finding which tokens have fundraising/burn/buyback data.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - TOKENOMIST_API_KEY
+      bins:
+        - tokenomist
+    primaryEnv: TOKENOMIST_API_KEY
+    install:
+      - kind: node
+        package: "@tokenomist-ai/tokenomist-cli"
+        bins: [tokenomist]
+allowed-tools: Bash(tokenomist:*)
+---
+
+# Skill: Token Overview
+
+Get a summary list of all tracked tokens with market data and supply info.
+
+## When to use
+
+When you need to browse all available tokens, compare market caps, or find which tokens have fundraising/burn/buyback data.
+
+## Command
+
+```bash
+tokenomist token list --output json
+```
+
+## Output fields
+
+| Field | Description |
+|-------|-------------|
+| `id` | Token slug (use in other commands) |
+| `name` | Token name |
+| `symbol` | Ticker symbol |
+| `marketCap` | Current market cap (USD), null if unavailable |
+| `circulatingSupply` | Circulating supply |
+| `totalLockedAmount` | Tokens still locked |
+| `unlockedAmount` | Tokens already unlocked |
+| `hasStandardAllocation` | Whether allocation data exists |
+| `hasFundraising` | Whether fundraising data exists |
+| `hasBurn` | Whether burn data exists |
+| `hasBuyback` | Whether buyback data exists |
+
+## Examples
+
+List all tokens as a table:
+```bash
+tokenomist token list
+```
+
+Get JSON for programmatic use:
+```bash
+tokenomist token list --output json
+```
+
+Export to CSV:
+```bash
+tokenomist token list --output csv > tokens.csv
+```
+
+## Domain Context
+
+- Token slugs (the `id` field) are the primary identifier used across all commands. Use `token list` to discover slugs.
+- `circulatingSupply` and `unlockedAmount` are different concepts — unlocked tokens may not be circulating (they could be held by the team, locked in DeFi protocols, or otherwise not trading on exchanges).
+- Fields like `hasStandardAllocation`, `hasFundraising`, `hasBurn`, `hasBuyback` indicate which data types are available. Check these before querying detail commands to avoid empty results.
+
+## Workflow
+
+- **Start here** to find token slugs before using other commands.
+- Use the slug in: `tokenomist unlock events <slug>`, `tokenomist emission daily <slug>`, `tokenomist allocation <slug>`, etc.
+- Check `has*` boolean fields (visible in `--output json`) to know which data types exist for a token before querying.
+
+## Output Size
+
+The `token list` command returns all tracked tokens (~200+). Use `--output json` and filter programmatically for large datasets.

package/skills/tokenomist-unlock-analysis/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: tokenomist-unlock-analysis
+description: Analyze token unlock events — upcoming unlocks, historical events, and allocation breakdowns. Use when checking unlock impact on market cap or reviewing unlock schedules.
+metadata:
+  openclaw:
+    requires:
+      env:
+        - TOKENOMIST_API_KEY
+      bins:
+        - tokenomist
+    primaryEnv: TOKENOMIST_API_KEY
+    install:
+      - kind: node
+        package: "@tokenomist-ai/tokenomist-cli"
+        bins: [tokenomist]
+allowed-tools: Bash(tokenomist:*)
+---
+
+# Skill: Unlock Analysis
+
+Analyze token unlock events — upcoming unlocks, historical events, and allocation breakdowns.
+
+## When to use
+
+When you need to check upcoming token unlocks, assess unlock impact on market cap, or review historical unlock events for a specific token.
+
+## Commands
+
+### List all unlock events (grouped by token)
+```bash
+tokenomist unlock list --output json
+```
+
+Filter options:
+```bash
+tokenomist unlock list --min-market-cap 1000000 --min-unlock-date 2024-01-01 --max-unlock-date 2024-12-31
+tokenomist unlock list --min-value-to-market-cap 0.01 --standard-allocation "Investor,Team"
+```
+
+### Get upcoming unlocks (next event per token)
+```bash
+tokenomist unlock upcoming --output json
+```
+
+### Get unlock events for a specific token
+```bash
+tokenomist unlock events <tokenSlug> --output json
+tokenomist unlock events solana --start 2024-01-01 --end 2024-12-31 --output json
+```
+
+## Key output fields
+
+**unlock list / upcoming:**
+- `tokenName`, `tokenSymbol` — token identification
+- `marketCap` — current market cap
+- `releasedPercentage` — how much of total supply has been released
+
+**unlock events:**
+- `unlockDate` — when the unlock happens
+- `cliffUnlocks.cliffAmount` — number of tokens unlocking
+- `cliffUnlocks.cliffValue` — USD value of the unlock
+- `cliffUnlocks.valueToMarketCap` — unlock value as % of market cap
+- `cliffUnlocks.allocationBreakdown` — which allocations are unlocking
+
+## Analysis workflow
+
+1. Run `tokenomist unlock upcoming --output json` to find tokens with large upcoming unlocks
+2. Filter by `valueToMarketCap` to identify potentially market-moving events
+3. Drill into specific tokens with `tokenomist unlock events <slug> --output json`
+4. Check allocation breakdown to understand who is receiving tokens (investors, team, community, etc.)
+
+## Domain Context
+
+- **Unlocked does not mean circulating.** Tokenomist tracks release schedules (when tokens become available), not on-chain transfers. Tokens can be unlocked but still held by the team, locked in DeFi, or otherwise not on the open market.
+- Schedules may include assumptions — the allocation breakdown can help assess confidence in the schedule.
+- `valueToMarketCap` is a key metric: unlocks representing >1% of market cap may be market-moving events.
+
+## Workflow
+
+- Use `tokenomist token list --output json` first to find the token slug if you don't know it.
+- Chain with `tokenomist emission daily <slug>` for a complete unlock + emission picture.
+- Cross-reference with `tokenomist allocation <slug>` to understand which groups (team, investors, community) are unlocking.
+- Use `tokenomist fundraising <slug>` to see what price investors paid — compare with current price to assess sell pressure.
+
+## Output Size
+
+The `unlock list` command can return hundreds of events. Use date and market cap filters to narrow results: `--min-market-cap`, `--min-unlock-date`, `--max-unlock-date`.