# Tycho RPC

Tycho exposes data through two mechanisms, the RPC and the stream. The RPC provides you access to static data, like the state of a component at a given block or extended information about the tokens it has found. For streaming data, we recommend using the [tycho-client](https://docs.propellerheads.xyz/tycho/for-solvers/indexer/tycho-client "mention"). This guide documents the RPC interfaces.

### Token Information

Tycho stream provides only the token addresses that Protocol Components use. If you require more token information, you can request using [tycho-rpc](https://docs.propellerheads.xyz/tycho/for-solvers/indexer/tycho-rpc "mention")'s [#v1-tokens](#v1-tokens "mention")endpoint. This service allows filtering by both quality and activity.

#### Quality Token Quality Ratings

The quality rating system helps you quickly assess token's specific properties:

* **100**: Normal ERC-20 Token behavior
* **75**: Rebasing token
* **50**: Fee-on-transfer token
* **10**: Token analysis failed at first detection
* **5**: Token analysis failed multiple times (after creation)
* **0**: Failed to extract attributes, like Decimal or Symbol

{% hint style="info" %}
The Token Quality Analysis was developed to aid Tycho Simulation in filtering out tokens that behave differently from standard ERC-20 Tokens. The analysis is under constant improvement and can provide wrong information.
{% endhint %}

## API Documentation

This section documents Tycho's RPC API. Full swagger docs are available at: <https://tycho-beta.propellerheads.xyz/docs/>

## Health check endpoint

> This endpoint is used to check the health of the service.

```json
{"openapi":"3.0.3","info":{"title":"Tycho-Indexer RPC","version":"0.66.2"},"servers":[{"url":"https://tycho-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Ethereum"},{"url":"https://tycho-base-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Base"},{"url":"https://tycho-unichain-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Unichain"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"authorization","description":"Use 'sampletoken' as value for testing"}},"schemas":{"Health":{"oneOf":[{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["Ready"]}}},{"type":"object","required":["status","message"],"properties":{"message":{"type":"string"},"status":{"type":"string","enum":["Starting"]}}},{"type":"object","required":["status","message"],"properties":{"message":{"type":"string"},"status":{"type":"string","enum":["NotReady"]}}}],"discriminator":{"propertyName":"status"}}}},"paths":{"/v1/health":{"get":{"tags":["rpc"],"summary":"Health check endpoint","description":"This endpoint is used to check the health of the service.","operationId":"health","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}}}}
```

## Retrieve protocol components

> This endpoint retrieves components within a specific execution environment, filtered by various\
> criteria.

```json
{"openapi":"3.0.3","info":{"title":"Tycho-Indexer RPC","version":"0.66.2"},"servers":[{"url":"https://tycho-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Ethereum"},{"url":"https://tycho-base-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Base"},{"url":"https://tycho-unichain-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Unichain"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"authorization","description":"Use 'sampletoken' as value for testing"}},"schemas":{"ProtocolComponentsRequestBody":{"type":"object","required":["protocol_system"],"properties":{"chain":{"$ref":"#/components/schemas/Chain"},"component_ids":{"type":"array","items":{"type":"string"},"description":"Filter by component ids","nullable":true},"pagination":{"$ref":"#/components/schemas/PaginationParams"},"protocol_system":{"type":"string","description":"Filters by protocol, required to correctly apply unconfirmed state from\nReorgBuffers"},"tvl_gt":{"type":"number","format":"double","description":"The minimum TVL of the protocol components to return, denoted in the chain's\nnative token.","nullable":true}},"additionalProperties":false},"Chain":{"type":"string","description":"Currently supported Blockchains","enum":["ethereum","starknet","zksync","arbitrum","base","unichain"]},"PaginationParams":{"type":"object","description":"Pagination parameter","properties":{"page":{"type":"integer","format":"int64","description":"What page to retrieve"},"page_size":{"type":"integer","format":"int64","description":"How many results to return per page"}},"additionalProperties":false},"ProtocolComponentRequestResponse":{"type":"object","description":"Response from Tycho server for a protocol components request.","required":["protocol_components","pagination"],"properties":{"pagination":{"$ref":"#/components/schemas/PaginationResponse"},"protocol_components":{"type":"array","items":{"$ref":"#/components/schemas/ProtocolComponent"}}}},"PaginationResponse":{"type":"object","required":["page","page_size","total"],"properties":{"page":{"type":"integer","format":"int64"},"page_size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64","description":"The total number of items available across all pages of results"}},"additionalProperties":false},"ProtocolComponent":{"type":"object","description":"Represents the static parts of a protocol component.","required":["id","protocol_system","protocol_type_name","chain","tokens","contract_ids","static_attributes","creation_tx","created_at"],"properties":{"chain":{"$ref":"#/components/schemas/Chain"},"change":{"$ref":"#/components/schemas/ChangeType"},"contract_ids":{"type":"array","items":{"type":"string"},"description":"Contract addresses involved in the components operations (may be empty for\nnative implementations)"},"created_at":{"type":"string","format":"date-time","description":"Date time of creation in UTC time"},"creation_tx":{"type":"string","description":"Transaction hash which created this component"},"id":{"type":"string","description":"Unique identifier for this component"},"protocol_system":{"type":"string","description":"Protocol system this component is part of"},"protocol_type_name":{"type":"string","description":"Type of the protocol system"},"static_attributes":{"type":"object","description":"Constant attributes of the component","additionalProperties":{"type":"string"}},"tokens":{"type":"array","items":{"type":"string"},"description":"Token addresses the component operates on"}}},"ChangeType":{"type":"string","enum":["Update","Deletion","Creation","Unspecified"]}}},"paths":{"/v1/protocol_components":{"post":{"tags":["rpc"],"summary":"Retrieve protocol components","description":"This endpoint retrieves components within a specific execution environment, filtered by various\ncriteria.","operationId":"protocol_components","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtocolComponentsRequestBody"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtocolComponentRequestResponse"}}}}}}}}}
```

## Retrieve protocol states

> This endpoint retrieves the state of protocols within a specific execution environment.

```json
{"openapi":"3.0.3","info":{"title":"Tycho-Indexer RPC","version":"0.66.2"},"servers":[{"url":"https://tycho-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Ethereum"},{"url":"https://tycho-base-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Base"},{"url":"https://tycho-unichain-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Unichain"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"authorization","description":"Use 'sampletoken' as value for testing"}},"schemas":{"ProtocolStateRequestBody":{"type":"object","description":"Max page size supported is 100","required":["protocol_system"],"properties":{"chain":{"$ref":"#/components/schemas/Chain"},"include_balances":{"type":"boolean","description":"Whether to include account balances in the response. Defaults to true."},"pagination":{"$ref":"#/components/schemas/PaginationParams"},"protocol_ids":{"type":"array","items":{"type":"string"},"description":"Filters response by protocol components ids","nullable":true},"protocol_system":{"type":"string","description":"Filters by protocol, required to correctly apply unconfirmed state from\nReorgBuffers"},"version":{"$ref":"#/components/schemas/VersionParam"}},"additionalProperties":false},"Chain":{"type":"string","description":"Currently supported Blockchains","enum":["ethereum","starknet","zksync","arbitrum","base","unichain"]},"PaginationParams":{"type":"object","description":"Pagination parameter","properties":{"page":{"type":"integer","format":"int64","description":"What page to retrieve"},"page_size":{"type":"integer","format":"int64","description":"How many results to return per page"}},"additionalProperties":false},"VersionParam":{"type":"object","description":"The version of the requested state, given as either a timestamp or a block.\n\nIf block is provided, the state at that exact block is returned. Will error if the block\nhas not been processed yet. If timestamp is provided, the state at the latest block before\nthat timestamp is returned.\nDefaults to the current time.","properties":{"block":{"allOf":[{"$ref":"#/components/schemas/BlockParam"}],"nullable":true},"timestamp":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":false},"BlockParam":{"type":"object","properties":{"chain":{"allOf":[{"$ref":"#/components/schemas/Chain"}],"nullable":true},"hash":{"type":"string","nullable":true},"number":{"type":"integer","format":"int64","nullable":true}},"additionalProperties":false},"ProtocolStateRequestResponse":{"type":"object","required":["states","pagination"],"properties":{"pagination":{"$ref":"#/components/schemas/PaginationResponse"},"states":{"type":"array","items":{"$ref":"#/components/schemas/ResponseProtocolState"}}}},"PaginationResponse":{"type":"object","required":["page","page_size","total"],"properties":{"page":{"type":"integer","format":"int64"},"page_size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64","description":"The total number of items available across all pages of results"}},"additionalProperties":false},"ResponseProtocolState":{"type":"object","description":"Protocol State struct for the response from Tycho server for a protocol state request.","required":["component_id","attributes","balances"],"properties":{"attributes":{"type":"object","description":"Attributes of the component. If an attribute's value is a `bigint`,\nit will be encoded as a big endian signed hex string.","additionalProperties":{"type":"string"}},"balances":{"type":"object","description":"Sum aggregated balances of the component","additionalProperties":{"type":"string"}},"component_id":{"type":"string","description":"Component id this state belongs to"}}}}},"paths":{"/v1/protocol_state":{"post":{"tags":["rpc"],"summary":"Retrieve protocol states","description":"This endpoint retrieves the state of protocols within a specific execution environment.","operationId":"protocol_state","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtocolStateRequestBody"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtocolStateRequestResponse"}}}}}}}}}
```

## Retrieve protocol systems

> This endpoint retrieves the protocol systems available in the indexer.

```json
{"openapi":"3.0.3","info":{"title":"Tycho-Indexer RPC","version":"0.66.2"},"servers":[{"url":"https://tycho-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Ethereum"},{"url":"https://tycho-base-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Base"},{"url":"https://tycho-unichain-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Unichain"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"authorization","description":"Use 'sampletoken' as value for testing"}},"schemas":{"ProtocolSystemsRequestBody":{"type":"object","properties":{"chain":{"$ref":"#/components/schemas/Chain"},"pagination":{"$ref":"#/components/schemas/PaginationParams"}},"additionalProperties":false},"Chain":{"type":"string","description":"Currently supported Blockchains","enum":["ethereum","starknet","zksync","arbitrum","base","unichain"]},"PaginationParams":{"type":"object","description":"Pagination parameter","properties":{"page":{"type":"integer","format":"int64","description":"What page to retrieve"},"page_size":{"type":"integer","format":"int64","description":"How many results to return per page"}},"additionalProperties":false},"ProtocolSystemsRequestResponse":{"type":"object","required":["protocol_systems","pagination"],"properties":{"pagination":{"$ref":"#/components/schemas/PaginationResponse"},"protocol_systems":{"type":"array","items":{"type":"string"},"description":"List of currently supported protocol systems"}}},"PaginationResponse":{"type":"object","required":["page","page_size","total"],"properties":{"page":{"type":"integer","format":"int64"},"page_size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64","description":"The total number of items available across all pages of results"}},"additionalProperties":false}}},"paths":{"/v1/protocol_systems":{"post":{"tags":["rpc"],"summary":"Retrieve protocol systems","description":"This endpoint retrieves the protocol systems available in the indexer.","operationId":"protocol_systems","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtocolSystemsRequestBody"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtocolSystemsRequestResponse"}}}}}}}}}
```

## Retrieve tokens

> This endpoint retrieves tokens for a specific execution environment, filtered by various\
> criteria. The tokens are returned in a paginated format.

```json
{"openapi":"3.0.3","info":{"title":"Tycho-Indexer RPC","version":"0.66.2"},"servers":[{"url":"https://tycho-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Ethereum"},{"url":"https://tycho-base-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Base"},{"url":"https://tycho-unichain-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Unichain"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"authorization","description":"Use 'sampletoken' as value for testing"}},"schemas":{"TokensRequestBody":{"type":"object","properties":{"chain":{"$ref":"#/components/schemas/Chain"},"min_quality":{"type":"integer","format":"int32","description":"Quality is between 0-100, where:\n- 100: Normal ERC-20 Token behavior\n- 75: Rebasing token\n- 50: Fee-on-transfer token\n- 10: Token analysis failed at first detection\n- 5: Token analysis failed multiple times (after creation)\n- 0: Failed to extract attributes, like Decimal or Symbol","nullable":true},"pagination":{"$ref":"#/components/schemas/PaginationParams"},"token_addresses":{"type":"array","items":{"type":"string"},"description":"Filters tokens by addresses","nullable":true},"traded_n_days_ago":{"type":"integer","format":"int64","description":"Filters tokens by recent trade activity","nullable":true,"minimum":0}},"additionalProperties":false},"Chain":{"type":"string","description":"Currently supported Blockchains","enum":["ethereum","starknet","zksync","arbitrum","base","unichain"]},"PaginationParams":{"type":"object","description":"Pagination parameter","properties":{"page":{"type":"integer","format":"int64","description":"What page to retrieve"},"page_size":{"type":"integer","format":"int64","description":"How many results to return per page"}},"additionalProperties":false},"TokensRequestResponse":{"type":"object","description":"Response from Tycho server for a tokens request.","required":["tokens","pagination"],"properties":{"pagination":{"$ref":"#/components/schemas/PaginationResponse"},"tokens":{"type":"array","items":{"$ref":"#/components/schemas/ResponseToken"}}}},"PaginationResponse":{"type":"object","required":["page","page_size","total"],"properties":{"page":{"type":"integer","format":"int64"},"page_size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64","description":"The total number of items available across all pages of results"}},"additionalProperties":false},"ResponseToken":{"type":"object","description":"Token struct for the response from Tycho server for a tokens request.","required":["chain","address","symbol","decimals","tax","gas","quality"],"properties":{"address":{"type":"string","description":"The address of this token as hex encoded string"},"chain":{"$ref":"#/components/schemas/Chain"},"decimals":{"type":"integer","format":"int32","description":"The number of decimals used to represent token values","minimum":0},"gas":{"type":"array","items":{"type":"integer","format":"int64","nullable":true,"minimum":0},"description":"Gas usage of the token, currently is always a single averaged value"},"quality":{"type":"integer","format":"int32","description":"Quality is between 0-100, where:\n- 100: Normal ERC-20 Token behavior\n- 75: Rebasing token\n- 50: Fee-on-transfer token\n- 10: Token analysis failed at first detection\n- 5: Token analysis failed multiple times (after creation)\n- 0: Failed to extract attributes, like Decimal or Symbol","minimum":0},"symbol":{"type":"string","description":"A shorthand symbol for this token (not unique)"},"tax":{"type":"integer","format":"int64","description":"The tax this token charges on transfers in basis points","minimum":0}}}}},"paths":{"/v1/tokens":{"post":{"tags":["rpc"],"summary":"Retrieve tokens","description":"This endpoint retrieves tokens for a specific execution environment, filtered by various\ncriteria. The tokens are returned in a paginated format.","operationId":"tokens","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokensRequestBody"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokensRequestResponse"}}}}}}}}}
```

## Retrieve contract states

> This endpoint retrieves the state of contracts within a specific execution environment. If no\
> contract ids are given, all contracts are returned. Note that \`protocol\_system\` is not a filter;\
> it's a way to specify the protocol system associated with the contracts requested and is used to\
> ensure that the correct extractor's block status is used when querying the database. If omitted,\
> the block status will be determined by a random extractor, which could be risky if the extractor\
> is out of sync. Filtering by protocol system is not currently supported on this endpoint and\
> should be done client side.

```json
{"openapi":"3.0.3","info":{"title":"Tycho-Indexer RPC","version":"0.66.2"},"servers":[{"url":"https://tycho-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Ethereum"},{"url":"https://tycho-base-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Base"},{"url":"https://tycho-unichain-beta.propellerheads.xyz","description":"PropellerHeads hosted service for Unichain"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"authorization","description":"Use 'sampletoken' as value for testing"}},"schemas":{"StateRequestBody":{"type":"object","description":"Maximum page size for this endpoint is 100","properties":{"chain":{"$ref":"#/components/schemas/Chain"},"contract_ids":{"type":"array","items":{"type":"string"},"description":"Filters response by contract addresses","nullable":true},"pagination":{"$ref":"#/components/schemas/PaginationParams"},"protocol_system":{"type":"string","description":"Does not filter response, only required to correctly apply unconfirmed state\nfrom ReorgBuffers"},"version":{"$ref":"#/components/schemas/VersionParam"}},"additionalProperties":false},"Chain":{"type":"string","description":"Currently supported Blockchains","enum":["ethereum","starknet","zksync","arbitrum","base","unichain"]},"PaginationParams":{"type":"object","description":"Pagination parameter","properties":{"page":{"type":"integer","format":"int64","description":"What page to retrieve"},"page_size":{"type":"integer","format":"int64","description":"How many results to return per page"}},"additionalProperties":false},"VersionParam":{"type":"object","description":"The version of the requested state, given as either a timestamp or a block.\n\nIf block is provided, the state at that exact block is returned. Will error if the block\nhas not been processed yet. If timestamp is provided, the state at the latest block before\nthat timestamp is returned.\nDefaults to the current time.","properties":{"block":{"allOf":[{"$ref":"#/components/schemas/BlockParam"}],"nullable":true},"timestamp":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":false},"BlockParam":{"type":"object","properties":{"chain":{"allOf":[{"$ref":"#/components/schemas/Chain"}],"nullable":true},"hash":{"type":"string","nullable":true},"number":{"type":"integer","format":"int64","nullable":true}},"additionalProperties":false},"StateRequestResponse":{"type":"object","description":"Response from Tycho server for a contract state request.","required":["accounts","pagination"],"properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/ResponseAccount"}},"pagination":{"$ref":"#/components/schemas/PaginationResponse"}}},"ResponseAccount":{"type":"object","description":"Account struct for the response from Tycho server for a contract state request.\n\nCode is serialized as a hex string instead of a list of bytes.","required":["chain","address","title","slots","native_balance","token_balances","code","code_hash","balance_modify_tx","code_modify_tx"],"properties":{"address":{"type":"string","description":"The address of the account as hex encoded string"},"balance_modify_tx":{"type":"string","description":"Transaction hash which last modified native balance"},"chain":{"$ref":"#/components/schemas/Chain"},"code":{"type":"string","description":"The accounts code as hex encoded string"},"code_hash":{"type":"string","description":"The hash of above code"},"code_modify_tx":{"type":"string","description":"Transaction hash which last modified code"},"creation_tx":{"type":"string","description":"Transaction hash which created the account","nullable":true},"native_balance":{"type":"string","description":"The balance of the account in the native token"},"slots":{"type":"object","description":"Contract storage map of hex encoded string values","additionalProperties":{"type":"string"}},"title":{"type":"string","description":"The title of the account usualy specifying its function within the protocol"},"token_balances":{"type":"object","description":"Balances of this account in other tokens (only tokens balance that are\nrelevant to the protocol are returned here)","additionalProperties":{"type":"string"}}}},"PaginationResponse":{"type":"object","required":["page","page_size","total"],"properties":{"page":{"type":"integer","format":"int64"},"page_size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64","description":"The total number of items available across all pages of results"}},"additionalProperties":false}}},"paths":{"/v1/contract_state":{"post":{"tags":["rpc"],"summary":"Retrieve contract states","description":"This endpoint retrieves the state of contracts within a specific execution environment. If no\ncontract ids are given, all contracts are returned. Note that `protocol_system` is not a filter;\nit's a way to specify the protocol system associated with the contracts requested and is used to\nensure that the correct extractor's block status is used when querying the database. If omitted,\nthe block status will be determined by a random extractor, which could be risky if the extractor\nis out of sync. Filtering by protocol system is not currently supported on this endpoint and\nshould be done client side.","operationId":"contract_state","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateRequestBody"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateRequestResponse"}}}}}}}}}
```