> For the complete documentation index, see [llms.txt](https://docs.yifi.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yifi.io/docs/earn/core-concepts/token.md).

# Token

A token is a single asset in the YiFi model – identified by its canonical address, deployed across chains, and tagged by class.

### Identity

A token is keyed by `token_id` – the **canonical contract address** of the token. It's what you pass to `GET /tokens/{token_id}`.

Per-chain deployments live in `addresses[]`, each with its own `address`, `chain_id`, and `decimals`. Read decimals from the matching `addresses[]` entry.

### Fields

| Field                              | Type   | Notes                                                |
| ---------------------------------- | ------ | ---------------------------------------------------- |
| `token_id`                         | string | Canonical contract address                           |
| `symbol` / `name`                  | string | e.g. `USDT` / `Tether USDT`                          |
| `addresses[]`                      | array  | Per-chain: `chain_id` (slug), `address`, `decimals`  |
| `chain_ids[]`                      | array  | Chain slugs the token is on                          |
| `tag_ids[]`                        | array  | Class tags                                           |
| `token_group`                      | string | Short group slug, e.g. `usd`                         |
| `group_name` / `group_description` | string | Human-readable group metadata                        |
| `image` /                          | string | Logo URL                                             |
| `logo_url`                         | string | Often empty; prefer `image`                          |
| `price_usd` … `holders`            | string | Live metrics (detail); may be `"0"` when unpopulated |

#### Tags

`tag_ids[]` classify what a token *is*. Filter with the `tags` query param on `GET /tokens`, or fetch the full reference list from `GET /tags`. A token can carry more than one tag.

| `tag_id`         | Meaning                                          |
| ---------------- | ------------------------------------------------ |
| `native`         | Native gas token (ETH, BNB, MATIC)               |
| `stablecoin`     | Fiat-pegged stablecoin                           |
| `liquid-staking` | Liquid staking derivative (LST/LSD)              |
| `staked`         | Staked or yield-bearing wrapper of another token |
| `lp`             | Liquidity provider receipt token                 |
| `reward`         | Protocol reward or incentive token               |
| `governance`     | Governance voting token                          |
| `bridged`        | Bridged cross-chain token variant                |

#### Groups

`token_group` normalizes asset display across chains and wrapped variants. Fetch the full reference list from `GET /groups`.

| `token_group` | Covers                                                         |
| ------------- | -------------------------------------------------------------- |
| `usd`         | USD-pegged stablecoins (USDC, USDT, DAI, FRAX, etc.)           |
| `eth`         | ETH and liquid staking derivatives (wstETH, rETH, stETH, etc.) |
| `btc`         | BTC and wrapped BTC variants (WBTC, cbBTC, tBTC, etc.)         |
| `euro`        | EUR-pegged stablecoins (EURS, agEUR, EURe, etc.)               |
| `other`       | Everything else                                                |

`group_name` and `group_description` on the token object are the same values `GET /groups` returns for that `token_group` .

### Try querying Token yourself!

## List tokens

> Get paginated tokens with optional filters.

```json
{"openapi":"3.1.1","info":{"title":"YiFi Yield Aggregator – Data Gateway API","version":"v1"},"tags":[{"description":"Tokens, their metrics, types and historical data","name":"Tokens"}],"servers":[{"url":"https://core-dev.yifi.io/api/v1"}],"security":[{"BearerToken":[]},{"PartnerApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"description":"Admin key for privileged operations (create/edit/delete).","type":"apiKey","name":"Authorization","in":"header"},"PartnerApiKey":{"description":"Partner API key used for B2B attribution (wallets, platforms). Requests authenticated with this key are attributed to the owning partner.","type":"apiKey","name":"X-Partner-Api-Key","in":"header"}},"schemas":{"rest.Response":{"type":"object","properties":{"code":{"type":"string"},"data":{},"isError":{"type":"boolean"},"message":{"type":"string"},"success":{"type":"boolean"}}},"common.Pagination-common_GetTokensResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/common.GetTokensResponse"}},"page":{"$ref":"#/components/schemas/common.Page"}}},"common.GetTokensResponse":{"type":"object","properties":{"chain_ids":{"type":"array","items":{"type":"string"}},"image":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"tag_ids":{"type":"array","items":{"type":"string"}},"token_group":{"type":"string"},"token_id":{"type":"string"}}},"common.Page":{"type":"object","properties":{"currentPage":{"description":"page-based pagination","type":"integer"},"id":{"description":"keyset-based pagination","type":"string"},"limit":{"description":"common","type":"integer"},"nextCursor":{"type":"string"},"offset":{"description":"offset-based pagination","type":"integer"},"pageSize":{"type":"integer"},"prevCursor":{"description":"cursor-based pagination","type":"string"},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"type":{"type":"string"}}},"core.Msg":{"type":"object","properties":{"message":{"type":"string"}}}}},"paths":{"/tokens":{"get":{"description":"Get paginated tokens with optional filters.","tags":["Tokens"],"summary":"List tokens","parameters":[{"schema":{"type":"string"},"description":"search","name":"search","in":"query"},{"schema":{"type":"string"},"description":"comma separated chain ids","name":"chains","in":"query"},{"schema":{"type":"string"},"description":"comma separated tags","name":"tags","in":"query"},{"schema":{"type":"string"},"description":"group","name":"group","in":"query"},{"schema":{"type":"integer"},"description":"limit","name":"limit","in":"query"},{"schema":{"type":"integer"},"description":"offset","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/rest.Response"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/common.Pagination-common_GetTokensResponse"}}}]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/core.Msg"}}}}}}}}}
```

## Get token

> Get token by id.

```json
{"openapi":"3.1.1","info":{"title":"YiFi Yield Aggregator – Data Gateway API","version":"v1"},"tags":[{"description":"Tokens, their metrics, types and historical data","name":"Tokens"}],"servers":[{"url":"https://core-dev.yifi.io/api/v1"}],"security":[{"BearerToken":[]},{"PartnerApiKey":[]}],"components":{"securitySchemes":{"BearerToken":{"description":"Admin key for privileged operations (create/edit/delete).","type":"apiKey","name":"Authorization","in":"header"},"PartnerApiKey":{"description":"Partner API key used for B2B attribution (wallets, platforms). Requests authenticated with this key are attributed to the owning partner.","type":"apiKey","name":"X-Partner-Api-Key","in":"header"}},"schemas":{"rest.Response":{"type":"object","properties":{"code":{"type":"string"},"data":{},"isError":{"type":"boolean"},"message":{"type":"string"},"success":{"type":"boolean"}}},"common.TokenFullCurrent":{"type":"object","properties":{"addresses":{"type":"array","items":{"$ref":"#/components/schemas/common.Address"}},"circulating_supply":{"type":"string"},"fdv":{"type":"string"},"group_description":{"type":"string"},"group_name":{"type":"string"},"holders":{"type":"string"},"image":{"type":"string"},"logo_url":{"type":"string"},"market_cap":{"type":"string"},"name":{"type":"string"},"price_usd":{"type":"string"},"symbol":{"type":"string"},"tag_ids":{"type":"array","items":{"type":"string"}},"token_group":{"description":"TODO: add constraints eth, usd, euro, btc, other","type":"string"},"token_id":{"type":"string"},"volume_24h_usd":{"type":"string"}}},"common.Address":{"type":"object","properties":{"address":{"type":"string"},"chain_id":{"type":"string"},"decimals":{"type":"integer"}}},"core.Msg":{"type":"object","properties":{"message":{"type":"string"}}}}},"paths":{"/tokens/{token_id}":{"get":{"description":"Get token by id.","tags":["Tokens"],"summary":"Get token","parameters":[{"schema":{"type":"string"},"description":"token id","name":"token_id","in":"path","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/rest.Response"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/common.TokenFullCurrent"}}}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/core.Msg"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/core.Msg"}}}}}}}}}
```