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. 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's POST /v1/tokensendpoint. 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

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.

API Documentation

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

Retrieve contract states

post

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.

Body

chainstring · enumoptional

Options: ethereum, starknet, zksync, arbitrum, base

contract_idsstring[] | nullableoptional

paginationobjectoptional

protocol_systemstringoptional

versionobjectoptional

The version of the requested state, given as either a timestamp or a block.

If block is provided, the state at that exact block is returned. Will error if the block has not been processed yet. If timestamp is provided, the state at the latest block before that timestamp is returned. Defaults to the current time.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/v1/contract_state' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "ethereum",
    "contract_ids": [
      "text"
    ],
    "pagination": {
      "page": 1,
      "page_size": 1
    },
    "protocol_system": "text",
    "version": {
      "block": {
        "chain": "ethereum",
        "hash": "text",
        "number": 1
      },
      "timestamp": "2025-03-26T01:48:05.948Z"
    }
  }'

200

200

{
  "accounts": [
    {
      "address": "0xc9f2e6ea1637E499406986ac50ddC92401ce1f58",
      "balance_modify_tx": "0x8f1133bfb054a23aedfe5d25b1d81b96195396d8b88bd5d4bcf865fc1ae2c3f4",
      "chain": "ethereum",
      "code": "0xBADBABE",
      "code_hash": "0x123456789",
      "code_modify_tx": "0x8f1133bfb054a23aedfe5d25b1d81b96195396d8b88bd5d4bcf865fc1ae2c3f4",
      "creation_tx": "0x8f1133bfb054a23aedfe5d25b1d81b96195396d8b88bd5d4bcf865fc1ae2c3f4",
      "native_balance": "0x00",
      "slots": {
        "0x....": "0x...."
      },
      "title": "Protocol Vault"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1
  }
}

OK

Health check endpoint

get

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/health'

200

200

{
  "message": "No db connection",
  "status": "NotReady"
}

OK

Retrieve protocol components

post

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

Body

chainstring · enumoptional

Options: ethereum, starknet, zksync, arbitrum, base

component_idsstring[] | nullableoptional

paginationobjectoptional

protocol_systemstringrequired

tvl_gtnumber · double | nullableoptional

The minimum TVL of the protocol components to return, denoted in the chain's native token.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/v1/protocol_components' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "ethereum",
    "component_ids": [
      "text"
    ],
    "pagination": {
      "page": 1,
      "page_size": 1
    },
    "protocol_system": "text",
    "tvl_gt": 1
  }'

200

200

{
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1
  },
  "protocol_components": [
    {
      "chain": "ethereum",
      "change": "Update",
      "contract_ids": [
        "text"
      ],
      "created_at": "2025-03-26T01:48:05.948Z",
      "creation_tx": "text",
      "id": "text",
      "protocol_system": "text",
      "protocol_type_name": "text",
      "static_attributes": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "tokens": [
        "text"
      ]
    }
  ]
}

OK

Retrieve protocol states

post

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

Body

chainstring · enumoptional

Options: ethereum, starknet, zksync, arbitrum, base

include_balancesbooleanoptional

Whether to include account balances in the response. Defaults to true.

paginationobjectoptional

protocol_idsstring[] | nullableoptional

protocol_systemstringrequired

versionobjectoptional

The version of the requested state, given as either a timestamp or a block.

If block is provided, the state at that exact block is returned. Will error if the block has not been processed yet. If timestamp is provided, the state at the latest block before that timestamp is returned. Defaults to the current time.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/v1/protocol_state' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "ethereum",
    "include_balances": true,
    "pagination": {
      "page": 1,
      "page_size": 1
    },
    "protocol_ids": [
      "text"
    ],
    "protocol_system": "text",
    "version": {
      "block": {
        "chain": "ethereum",
        "hash": "text",
        "number": 1
      },
      "timestamp": "2025-03-26T01:48:05.948Z"
    }
  }'

200

200

{
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1
  },
  "states": [
    {
      "attributes": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "balances": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "component_id": "text"
    }
  ]
}

OK

Retrieve protocol systems

post

This endpoint retrieves the protocol systems available in the indexer.

Body

chainstring · enumoptional

Options: ethereum, starknet, zksync, arbitrum, base

paginationobjectoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/v1/protocol_systems' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "ethereum",
    "pagination": {
      "page": 1,
      "page_size": 1
    }
  }'

200

200

{
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1
  },
  "protocol_systems": [
    "text"
  ]
}

OK

Retrieve tokens

post

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

Body

chainstring · enumoptional

Options: ethereum, starknet, zksync, arbitrum, base

min_qualityinteger · int32 | nullableoptional

Quality is between 0-100, where:

• 100: Normal token
• 75: Rebase token
• 50: Fee token
• 10: Token analysis failed at creation
• 5: Token analysis failed on cronjob (after creation).
• 0: Failed to extract decimals onchain

paginationobjectoptional

token_addressesstring[] | nullableoptional

traded_n_days_agointeger · int64 | nullableoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/v1/tokens' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "ethereum",
    "min_quality": 1,
    "pagination": {
      "page": 1,
      "page_size": 1
    },
    "token_addresses": [
      "text"
    ],
    "traded_n_days_ago": 1
  }'

200

200

{
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1
  },
  "tokens": [
    {
      "address": "0xc9f2e6ea1637E499406986ac50ddC92401ce1f58",
      "chain": "ethereum",
      "decimals": 1,
      "gas": [
        1
      ],
      "quality": 1,
      "symbol": "WETH",
      "tax": 1
    }
  ]
}

OK