Listed vs. all
When to use each token-listing variant
Both live at the same URL - GET /api/tokens/. The difference is which filter you pass. Picking right keeps scam contracts out of your UI.
| Use case | Filter | Why |
|---|---|---|
| Token picker / swap UI | ?common=true | Curated list of mainstream tokens. Almost no noise. |
| Wallet showing "verified tokens you hold" | ?verified=true (combined with the user's holdings) | Filters out spam airdrops. |
| Block-explorer-style "what is this contract?" page | ?address=0x... | Direct lookup. One result or zero. |
| Search bar | ?search=USDC&verified=true | Substring search, restricted to safe tokens. |
| Deep research / data export | no verified filter, page through | Includes everything. Slower, noisier. |
| ERC721 / NFT collection list | ?is_erc721=true&public=true | Limits to NFTs that opted into public discovery. |
Tip
Start strict, loosen if needed. Default to verified=true or common=true in user-facing UIs. Only fall back to the unfiltered listing if the strict filter returns nothing.
Concrete example: token picker autocomplete
This three-tier fallback gives users fast, trustworthy results for known tokens, and still lets them find long-tail tokens by exact address.