> 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/tokens.md).

# Tokens

Tokens, their metrics, types and historical data

## Token groups

> List token groups.

```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.TokenGroup":{"type":"object","properties":{"group_description":{"type":"string"},"group_name":{"type":"string"},"logo_url":{"type":"string"},"token_group":{"description":"TODO: add constraints eth, usd, euro, btc, other","type":"string"}}},"core.Msg":{"type":"object","properties":{"message":{"type":"string"}}}}},"paths":{"/groups":{"get":{"description":"List token groups.","tags":["Tokens"],"summary":"Token groups","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/rest.Response"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/common.TokenGroup"}}}}]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/core.Msg"}}}}}}}}}
```

## Token tags

> List available token tags.

```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.TokenTag":{"type":"object","properties":{"description":{"type":"string"},"name":{"type":"string"},"tag_id":{"type":"string"}}},"core.Msg":{"type":"object","properties":{"message":{"type":"string"}}}}},"paths":{"/tags":{"get":{"description":"List available token tags.","tags":["Tokens"],"summary":"Token tags","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/rest.Response"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/common.TokenTag"}}}}]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/core.Msg"}}}}}}}}}
```

## 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"}}}}}}}}}
```

## Token group by token id

> Get token group for a token.

```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.TokenGroup":{"type":"object","properties":{"group_description":{"type":"string"},"group_name":{"type":"string"},"logo_url":{"type":"string"},"token_group":{"description":"TODO: add constraints eth, usd, euro, btc, other","type":"string"}}},"core.Msg":{"type":"object","properties":{"message":{"type":"string"}}}}},"paths":{"/tokens/{token_id}/group":{"get":{"description":"Get token group for a token.","tags":["Tokens"],"summary":"Token group by token id","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.TokenGroup"}}}]}}}},"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"}}}}}}}}}
```

## Token history metrics

> Get token historical metrics (time range). \`from\` limited to 1 year back.

```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.TokenStatsHistory":{"type":"object","properties":{"history":{"type":"array","items":{"$ref":"#/components/schemas/common.TokenHistory"}},"token_id":{"type":"string"}}},"common.TokenHistory":{"type":"object","properties":{"metrics":{"$ref":"#/components/schemas/common.TokenStats"},"timestamp":{"type":"string"}}},"common.TokenStats":{"type":"object","properties":{"circulating_supply":{"type":"string"},"fdv":{"type":"string"},"holders":{"type":"string"},"market_cap":{"type":"string"},"price_usd":{"type":"string"},"volume_24h_usd":{"type":"string"}}},"core.Msg":{"type":"object","properties":{"message":{"type":"string"}}}}},"paths":{"/tokens/{token_id}/metrics":{"get":{"description":"Get token historical metrics (time range). `from` limited to 1 year back.","tags":["Tokens"],"summary":"Token history metrics","parameters":[{"schema":{"type":"string"},"description":"token id","name":"token_id","in":"path","required":true},{"schema":{"type":"string"},"description":"start time RFC3339","name":"from","in":"query"},{"schema":{"type":"string"},"description":"end time RFC3339","name":"to","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/rest.Response"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/common.TokenStatsHistory"}}}]}}}},"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"}}}}}}}}}
```