> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenomist.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-listing

> List your token's tokenomics on Tokenomist directly from your AI assistant — 8 tools covering registration, drafting, vesting schedules, and submission.

Tokenomist MCP also lets your AI assistant submit a token to Tokenomist's [self-listing platform](https://listing.tokenomist.ai) on your behalf. Point your assistant at your tokenomics documentation — a whitepaper, docs site, or pasted text — and it extracts the allocation and vesting structure, shows you the result for confirmation, then creates and submits the listing.

<Note>
  These are the only **write** tools the Tokenomist MCP server exposes. Every other tool (see [Tools & prompts](/mcp/tools)) is read-only. Self-listing tools never touch on-chain state — they only create draft listing data on Tokenomist.
</Note>

## Prerequisites

* A [Tokenomist API key](/mcp/authentication) connected to your MCP client.
* Your account's email registered on the self-listing platform at [listing.tokenomist.ai](https://listing.tokenomist.ai) — this is a **separate sign-up** from your main Tokenomist account. Your assistant checks this for you and gives you the sign-up link if you aren't registered yet.
* Your tokenomics source material ready to share: a whitepaper URL, docs pages, or pasted text, plus the total token supply (needed to convert allocation percentages into token amounts).

## How the workflow works

Ask your assistant to list your token — for example, *"List my token on Tokenomist using our docs at [https://mydocs.example.com/tokenomics](https://mydocs.example.com/tokenomics)"*. It follows this sequence:

<Steps>
  <Step title="Registration check">
    The assistant calls `self_listing_check_registration`. If your email isn't registered yet, it stops and gives you the [listing.tokenomist.ai](https://listing.tokenomist.ai) sign-up link — sign up and verify your email, then ask it to continue.
  </Step>

  <Step title="Gather details">
    The assistant asks for anything it can't find in your sources: project description, status (pre-launch or launched), at least one team member, official website and X/Twitter links, token contract address and chain ID, business contact email, categories, and total supply. It also asks whether your token is listed on CoinGecko — if yes, it needs the CoinGecko ID; if no, it generates a manual token slug instead.
  </Step>

  <Step title="Extract allocations and vesting">
    The assistant reads your sources and builds an allocation/vesting table — splitting TGE unlocks from vested remainders, converting sub-percentages, and mapping terminology (e.g. "seed round" → `PRIVATE_INVESTORS`) to Tokenomist's categories. It never invents numbers — anything not in your sources is flagged as an assumption or marked to-be-decided.
  </Step>

  <Step title="Review the draft">
    The assistant shows you the full extracted data — every field, every vesting tranche with percentages, dates, and cliffs — as a table, and asks for corrections before saving anything.
  </Step>

  <Step title="Create and save">
    Once you confirm, the assistant creates the project (or updates an existing draft, if one already exists for this token) and saves the vesting schedules. If anything fails validation, it fixes exactly the reported fields and retries — you don't need to intervene unless it's stuck.
  </Step>

  <Step title="Final review and submit">
    The assistant shows you the saved draft one more time and asks for explicit confirmation before submitting. Submission is final — vesting schedules can't be edited afterwards.
  </Step>
</Steps>

<Warning>
  After every create, update, or vesting save, the assistant will give you a link to [listing.tokenomist.ai/v2](https://listing.tokenomist.ai/v2) so you can visually verify the draft yourself before it's submitted. Always check it — submission locks the vesting schedule permanently.
</Warning>

## Tools

| Tool                              | Purpose                                                                                                                                         |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `self_listing_guide`              | Returns the extraction rules, field definitions, and workflow the assistant follows. Read-only; called automatically at the start of a session. |
| `self_listing_check_registration` | Checks whether your account's email is registered on the self-listing platform.                                                                 |
| `self_listing_create_project`     | Creates a new draft listing project — requires project info, team, links, and token info.                                                       |
| `self_listing_list_projects`      | Lists your existing draft and submitted projects with their IDs.                                                                                |
| `self_listing_get_project`        | Fetches a single project, including token info and saved vesting schedules.                                                                     |
| `self_listing_update_project`     | Updates fields on an existing draft (only the fields you send change).                                                                          |
| `self_listing_upsert_vesting`     | Replaces the complete set of vesting schedules for a project.                                                                                   |
| `self_listing_submit_project`     | Submits a project for verification. Final — vesting can no longer be edited.                                                                    |

## Project fields

Required to create a project: `projectName`, `projectDescription`, `businessEmail`, `category` (e.g. `["DeFi"]`), `projectStatus` (`PRE_LAUNCH` or `LAUNCHED`), at least one team member, official links (website and X are required), and token info.

<AccordionGroup>
  <Accordion title="Token info">
    * `tokenName`, `tokenSymbol`, `tokenAddress`, `chainId` — required.
    * `tokenCreationMethod` — `coingecko` or `manual`. Defaults to `coingecko` if omitted, so always set it explicitly for tokens not on CoinGecko.
    * `coingeckoTokenId` — required when `tokenCreationMethod` is `coingecko` (the slug in the coin's CoinGecko URL, e.g. `bitcoin`).
    * `customTokenId` — required when `tokenCreationMethod` is `manual`; must match `^[a-z0-9-_]+$`.
    * `maxSupply`, `totalSupply`, `tge` — optional.

    <Warning>
      Updating `tokenInfo` replaces it entirely — the assistant always resends every token field on update, since an omitted `tokenCreationMethod` silently resets to `coingecko`.
    </Warning>
  </Accordion>

  <Accordion title="Vesting schedules">
    Each tranche needs `allocationName`, `vestingName`, `vestingPercentage` (a numeric string, e.g. `"12.5"`), `vestingAmount`, `distributionTo`, `distributionMethod`, `vestingDescription`, and `color`. Across all tranches in a project, `vestingPercentage` must sum to exactly 100, and `vestingAmount` must equal `vestingPercentage × totalSupply ÷ 100`.

    Unless a tranche is marked `TBD` (terms unknown), it also needs `startVestingDate`, `endVestingDate`, `cliffPeriod` + `cliffPeriodUnit` (`DAY`/`WEEK`/`MONTH`/`YEAR`), and `vestingFrequency` + `vestingFrequencyUnit` (`DAILY`/`WEEKLY`/`MONTHLY`/`YEARLY`).

    `distributionTo` is one of `FOUNDER_TEAM`, `ADVISORS`, `MARKETING`, `COMMUNITY`, `PRIVATE_INVESTORS`, `PUBLIC_INVESTORS`, `LIQUIDITY`, `FOUNDATION`, `OTHERS`. `distributionMethod` is one of `AIRDROP`, `AUCTIONS`, `VESTING`, `MINING`, `YIELD_FARMING`, `INITIAL_LIQUIDITY`, `ACTIVITY_BASED`, `OTHERS`.

    <Warning>
      `self_listing_upsert_vesting` **replaces the complete set** of vesting schedules every time it's called — there's no partial update.
    </Warning>
  </Accordion>
</AccordionGroup>

## Validation errors

If a create, update, or vesting call fails validation, the tool result includes the specific fields that failed (vesting errors reference a tranche by its zero-based position in the schedule list). The assistant fixes exactly those fields and retries — it doesn't need to re-ask you for information it already has.

## Example prompts

* "List my token on Tokenomist — here's our tokenomics doc: \[URL]. Total supply is 1,000,000,000."
* "Am I registered on the self-listing platform yet?"
* "Show me my draft listings."
* "Update my listing's website link to [https://mynewsite.example.com](https://mynewsite.example.com)."
* "I'm ready — submit my listing."