TokensAPI

Lists

Discover, read, compose and manage community token lists, and search for mints to add to them.

All endpoints below use https://api.tokens.xyz/v2 with an x-api-key header; see Authentication. The model (curated vs community, ownership, statuses, caps and budgets, composition) is on Token lists; error codes are on Errors & limits.

Curated slugs: majors, currencies, lsts, rwas, etfs, metals, stocks. The aliases stables (currencies) and xstocks (etfs) are accepted wherever a slug is, on {slug} paths and in lists=.

GET /v2/lists

The list catalog: every curated list plus every published community list, metadata only.

Auth: x-api-key, scope assets:read.

Query params

  • limit (1–500, default 100), offset: pagination applies to community lists only. The curated set is prepended to page one (offset=0) and absent from later pages; total is the curated count plus the published community count.
  • mine=true: your project's own lists instead of the public catalog, in every status (draft, unlisted, published, archived), each row carrying status, no curated rows, and total equal to the page length.

Response

interface ListsResponse {
    lists: Array<{
        slug: string;
        name: string;
        description: string | null; // curated lists only; null for community lists
        curated: boolean;
        owner: { name: string } | { projectId: string };
        tokenCount: number;
        updatedAt: number | null; // unix ms
        status?: 'draft' | 'unlisted' | 'published' | 'archived'; // only with mine=true
    }>;
    total: number;
}

Example

curl -sS "$API_BASE_URL/v2/lists?limit=50" -H "x-api-key: $API_KEY"

# Your own lists, every status
curl -sS "$API_BASE_URL/v2/lists?mine=true" -H "x-api-key: $API_KEY"

Notes

  • Cached for 300 s; falls back to a last-good copy (up to 10 minutes old) when the list backend is unavailable. mine=true is never served from the fallback.

GET /v2/lists/{slug}

One list with hydrated tokens.

Auth: x-api-key, scope assets:read.

Path params

  • {slug}: a curated slug or alias, or a community slug. Curated slugs serve the effective curated membership; community slugs serve published and unlisted lists (unlisted is hidden from the catalog only). draft and archived lists are 404 ("List not found").

Query params

  • limit (1–2000, default 500), offset.

Response

type VariantAdvisory = {
    status: 'caution' | 'compromised' | 'blocked';
    reason: string;
    url: string | null;
    since: number; // unix ms
} | null;

interface V2ListToken {
    mint: string;
    symbol: string | null;
    name: string | null;
    decimals: number | null;
    logoURI: string | null;
    verified: boolean; // an active registry variant exists for this mint
    rank: number;
    advisory: VariantAdvisory; // always present; null when not flagged
    note?: string;
    addedAt?: number;
}

interface ListDetailResponse {
    slug: string;
    name: string;
    description: string | null; // curated lists only; null for community lists
    curated: boolean;
    owner: { name: string } | { projectId: string };
    tokenCount: number;
    updatedAt: number | null;
    tokens: V2ListToken[];
}

Example

curl -sS "$API_BASE_URL/v2/lists/majors?limit=100" -H "x-api-key: $API_KEY"

Notes

  • Mints flagged blocked are omitted from tokens during hydration (rank stays dense) and tokenCount reflects the visible tokens, not the raw membership. caution and compromised members are returned with advisory populated; treat compromised as do-not-trade. See Advisories.
  • Cached for 60 s; last-good copy up to 10 minutes old when the list backend is unavailable.

GET /v2/lists/tokens

The composition call: the union of the named lists, deduped by mint, each token annotated with which of the requested lists contains it.

Auth: x-api-key, scope assets:read.

Query params

  • lists (required): comma-separated slugs, max 10. Curated and community slugs mix freely. There is no "all lists" value; apps must name the curators they trust.
  • limit (1–2000, default 500), offset: pagination over the deduped union.

Response

interface ComposeResponse {
    lists: Array<ListsResponse['lists'][number] & {
        truncated?: true; // membership exceeded the 5000-per-list compose ceiling; the union omits the tail
    }>;
    notFound: string[];
    total: number; // size of the deduped union
    tokens: Array<
        Omit<V2ListToken, 'note' | 'addedAt'> & {
            lists: string[]; // requested slugs containing this mint
        }
    >;
}

Example

curl -sS "$API_BASE_URL/v2/lists/tokens?lists=majors,currencies,acme-core" -H "x-api-key: $API_KEY"

Notes

  • Unknown, draft or archived slugs are reported in notFound instead of failing the call. Unlisted lists compose by slug like published ones.
  • blocked mints are omitted here too, so total counts visible tokens only.
  • Cached for 60 s; last-good copy up to 10 minutes old when the list backend is unavailable.

Managing lists

Any API key can create lists; project ownership is the security boundary. Every key on a project may manage that project's lists, and keys from other projects get 403 on writes. For POST, PATCH and PUT send Content-Type: application/json. Caps, the hold-down window for released slugs, and the recommended automation flow are on Token lists; the Quickstart walks through check, create, load, publish with curl.

Every mutation returns the affected record so you can update local state without a follow-up read:

interface ListRecord {
    id: string;
    slug: string;
    ownerProjectId: string;
    name: string;
    status: 'draft' | 'unlisted' | 'published' | 'archived';
    createdAt: number; // unix ms
    updatedAt: number;
}

GET /v2/lists/check-slug

Is this slug claimable right now? Lets a curator UI validate before submitting instead of surfacing a 400 from POST /v2/lists.

Auth: x-api-key, scope assets:read.

Query params

  • slug (required): lower-cased before checking.

Response

type CheckSlugResponse =
    | { slug: string; available: true }
    | { slug: string; available: false; reason: 'invalid' | 'reserved' | 'taken' | 'held' };

Example

curl -sS "$API_BASE_URL/v2/lists/check-slug?slug=acme-core" -H "x-api-key: $API_KEY"

Notes

  • taken covers lists in any status; a draft or archived list still holds its slug. held means the slug was released recently and only its previous owner can reclaim it during the hold-down window; that owner sees available: true.
  • The answer is advisory: it can go stale between check and create, and the create path stays authoritative.
  • Never cached, so a slug freed by a delete reads as available immediately.

POST /v2/lists

Create a list.

Auth: x-api-key, scope assets:read. The list is owned by the caller's project.

Body

  • slug (required): globally unique, ^[a-z][a-z0-9-]{2,62}$. Curated ids, their aliases and route words (all, lists, curated, tokens, search-tokens, check-slug) are reserved. Prefix by convention: ownership-core.
  • name (required): max 80 characters.
  • status (optional): draft, unlisted or published (default published). unlisted hides the list from the catalog and from inLists annotations while GET /v2/lists/{slug} stays readable by anyone with the link.

Response

{ list: ListRecord }

Example

curl -sS -X POST "$API_BASE_URL/v2/lists" \
  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"slug":"acme-core","name":"Acme Core","status":"draft"}'

Notes

  • Errors (400 with details.code): invalid_slug, reserved_slug, slug_conflict, slug_held, project_lists_limit.

PATCH /v2/lists/{slug}

Update a list's name, slug or status.

Auth: x-api-key, scope assets:read. Owner project only.

Body

  • slug (optional): rename. The old path stops resolving and is held for this owner for a 30-day window.
  • name (optional): max 80 characters.
  • status (optional): draft, unlisted, published or archived. archived is the reversible hide-it option.

Response

{ list: ListRecord }

Example

curl -sS -X PATCH "$API_BASE_URL/v2/lists/acme-core" \
  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"status":"published"}'

Notes

  • 403 when your project does not own the list or it is moderator-locked; slug errors as for POST /v2/lists.

DELETE /v2/lists/{slug}

Permanently delete the list and its members, releasing the slug (subject to the owner hold-down window). Irreversible; use PATCH { status: 'archived' } to hide a list reversibly.

Auth: x-api-key, scope assets:read. Owner project only.

Response

{ list: ListRecord } // the deleted record

Example

curl -sS -X DELETE "$API_BASE_URL/v2/lists/acme-core" -H "x-api-key: $API_KEY"

Notes

  • 403 when your project does not own the list; 404 when it does not exist.

POST /v2/lists/{slug}/members

Bulk add, up to 250 items per call, deduped.

Auth: x-api-key, scope assets:read. Owner project only. Draws from the batch provider budget.

Body

Two shapes, usable together; a body with neither key is a 400:

  • { mints: string[] }: bare addresses, appended in order.
  • { members: Array<{ mint: string; note?: string }> }: the CSV shape. Row order becomes rank order and note (max 500 characters) lands on the member.

Response

interface BatchAddResponse {
    added: Array<{ mint: string; verified: boolean; snapshot: object | null }>;
    failed: Array<{
        mint: string;
        // Same codes as details.code on single-mint writes; in practice
        // invalid_mint | unknown_mint | list_full.
        error: string;
    }>;
}

Example

curl -sS -X POST "$API_BASE_URL/v2/lists/acme-core/members" \
  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"members":[{"mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","note":"Treasury"},{"mint":"So11111111111111111111111111111111111111112"}]}'

Notes

  • Mints are resolved in bulk: registry, then token index, then budgeted provider lookups (at most about 50 unknown mints per call). Per-mint failures land in failed[] without failing the batch; over-budget unknowns fail as unknown_mint and can be retried in a later batch.
  • More than 250 items is 400 batch_too_large; the whole call is rejected.

PUT /v2/lists/{slug}/members/{mint}

Add or update one member.

Auth: x-api-key, scope assets:read. Owner project only. Draws from the batch provider budget when the mint needs a live lookup.

Body

Optional. { rank?: number, note?: string }: rank is an integer position; omitted, the member is appended. note is max 500 characters.

Response

{ member: { mint: string; verified: boolean; snapshot: object | null } }

Example

curl -sS -X PUT "$API_BASE_URL/v2/lists/acme-core/members/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" \
  -H "x-api-key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"rank":0,"note":"Treasury"}'

Notes

  • The mint must resolve somewhere: curated registry (verified: true), then the token index, then a live provider lookup whose metadata is snapshotted onto the member. A mint unknown everywhere is 400 unknown_mint; a malformed address is 400 invalid_mint.

DELETE /v2/lists/{slug}/members/{mint}

Remove one member.

Auth: x-api-key, scope assets:read. Owner project only.

Response

{ removed: { mint: string } }

Example

curl -sS -X DELETE "$API_BASE_URL/v2/lists/acme-core/members/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" \
  -H "x-api-key: $API_KEY"

Notes

  • 404 when the mint was not in the list. The body still says "List not found"; branch on the status.

GET /v2/lists/search-tokens

Curator-assist search: decision support for a list owner choosing which mint to add. This is not a public ranking. It defaults to the strict policy and always returns the suppressed set with reasons, so the curator sees what was filtered and why. Use GET /v2/search for end-user features.

Auth: x-api-key, scope assets:read. Draws from the search provider budget.

Query params

  • q (required): symbol, name or mint address, max 100 chars.
  • policy (optional): strict (default), default or degen.
  • Gate overrides: the same minLiquidityUsd, minAgeDays, minMarketScore, requireMarketData, suppressImpersonation and verifiedOnly as GET /v2/search. policy in the response stays the preset id; suppressed is always returned here.
  • limit (1–50, default 10).

Response

interface SearchTokensResponse {
    query: string;
    interpretation: { intent: 'mint' | 'ticker' | 'name'; normalizedQuery: string; hadSuspiciousCharacters: boolean };
    policy: string; // the preset id; overrides are applied but not echoed here
    policyVersion: string;
    scoringVersion: string;
    sources: {
        provider: 'ok' | 'degraded' | 'disabled';
        db: 'ok' | 'degraded';
        registry: 'ok';
        cache: 'hit' | 'miss' | 'bypass'; // whether this query's candidate set came from the server-side cache
    };
    latencyMs: number;
    results: Array<{
        mint: string;
        claims: { symbol: string | null; name: string | null; attestations: object[] };
        market: object; // price, liquidityUsd, volume24hUsd, marketCapUsd, holderCount, …
        score: { total: number; components: object };
        reasons: string[];   // e.g. exact_symbol_match, curated_list_member, deep_liquidity
        warnings: string[];  // e.g. possible_impersonation, suspicious_characters, new_token, unverified, advisory_caution
        badges: string[];    // e.g. curated:majors, grade:A
        verified: boolean;
        inLists: string[];   // curated + community lists already containing this mint
    }>;
    suppressed: Array<{
        mint: string;
        symbol: string | null;
        name: string | null;
        liquidityUsd: number | null;
        suppressedBy: string[]; // which policy gates fired, e.g. gate_min_liquidity, gate_advisory_blocked
        warnings: string[];
    }>;
}

Example

curl -sS "$API_BASE_URL/v2/lists/search-tokens?q=bonk" -H "x-api-key: $API_KEY"

Notes

  • reasons, warnings and suppressedBy use the same vocabularies as /v2/search; see Explanation codes.
  • Advisory gates fire under every policy, including degen: mints carrying a blocked or compromised advisory land in suppressed[] with gate_advisory_blocked or gate_advisory_compromised, so a curator sees that the mint was rejected and why. See Advisories.
  • inLists excludes unlisted lists.
  • Shares the search candidate cache with /v2/search and /v2/resolve: a query any of them saw in the last ~45 seconds is a hit (sources.cache: 'hit') and does not count against the budget.