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;totalis 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 carryingstatus, no curated rows, andtotalequal 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=trueis 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 servepublishedandunlistedlists (unlisted is hidden from the catalog only).draftandarchivedlists are404("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
blockedare omitted fromtokensduring hydration (rankstays dense) andtokenCountreflects the visible tokens, not the raw membership.cautionandcompromisedmembers are returned withadvisorypopulated; treatcompromisedas 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
notFoundinstead of failing the call. Unlisted lists compose by slug like published ones. blockedmints are omitted here too, sototalcounts 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
takencovers lists in any status; a draft or archived list still holds its slug.heldmeans the slug was released recently and only its previous owner can reclaim it during the hold-down window; that owner seesavailable: 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,unlistedorpublished(defaultpublished).unlistedhides the list from the catalog and frominListsannotations whileGET /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 (
400withdetails.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,publishedorarchived.archivedis 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
403when your project does not own the list or it is moderator-locked; slug errors as forPOST /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 recordExample
curl -sS -X DELETE "$API_BASE_URL/v2/lists/acme-core" -H "x-api-key: $API_KEY"Notes
403when your project does not own the list;404when 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 andnote(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 asunknown_mintand 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 is400 unknown_mint; a malformed address is400 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
404when 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),defaultordegen.- Gate overrides: the same
minLiquidityUsd,minAgeDays,minMarketScore,requireMarketData,suppressImpersonationandverifiedOnlyasGET /v2/search.policyin the response stays the preset id;suppressedis 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,warningsandsuppressedByuse the same vocabularies as/v2/search; see Explanation codes.- Advisory gates fire under every policy, including
degen: mints carrying ablockedorcompromisedadvisory land insuppressed[]withgate_advisory_blockedorgate_advisory_compromised, so a curator sees that the mint was rejected and why. See Advisories. inListsexcludesunlistedlists.- Shares the search candidate cache with
/v2/searchand/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.