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 #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/

Health check endpoint

get

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

Authorizations

Responses

200

OK

application/json

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

or

or

get

HTTPcURLJavaScriptPython

GET /v1/health HTTP/1.1
Host: tycho-beta.propellerheads.xyz
authorization: YOUR_API_KEY
Accept: */*

200

OK

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

Retrieve protocol components

post

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

Authorizations

Body

chainstring · enumOptional

Currently supported Blockchains

Possible values:

component_idsstring[] | nullableOptional

Filter by component ids

protocol_systemstringRequired

Filters by protocol, required to correctly apply unconfirmed state from ReorgBuffers

tvl_gtnumber · double | nullableOptional

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

Responses

200

OK

application/json

post

HTTPcURLJavaScriptPython

POST /v1/protocol_components HTTP/1.1
Host: tycho-beta.propellerheads.xyz
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 119

{
  "chain": "ethereum",
  "component_ids": [
    "text"
  ],
  "pagination": {
    "page": 1,
    "page_size": 1
  },
  "protocol_system": "text",
  "tvl_gt": 1
}

200

OK

{
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1
  },
  "protocol_components": [
    {
      "chain": "ethereum",
      "change": "Update",
      "contract_ids": [
        "text"
      ],
      "created_at": "2025-05-09T02:33:54.841Z",
      "creation_tx": "text",
      "id": "text",
      "protocol_system": "text",
      "protocol_type_name": "text",
      "static_attributes": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "tokens": [
        "text"
      ]
    }
  ]
}

Retrieve protocol states

post

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

Authorizations

Body

Max page size supported is 100

chainstring · enumOptional

Currently supported Blockchains

Possible values:

include_balancesbooleanOptional

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

protocol_idsstring[] | nullableOptional

Filters response by protocol components ids

protocol_systemstringRequired

Filters by protocol, required to correctly apply unconfirmed state from ReorgBuffers

Responses

200

OK

application/json

post

HTTPcURLJavaScriptPython

POST /v1/protocol_state HTTP/1.1
Host: tycho-beta.propellerheads.xyz
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "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-05-09T02:33:54.841Z"
  }
}

200

OK

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

Retrieve protocol systems

post

This endpoint retrieves the protocol systems available in the indexer.

Authorizations

Body

chainstring · enumOptional

Currently supported Blockchains

Possible values:

Responses

200

OK

application/json

post

HTTPcURLJavaScriptPython

POST /v1/protocol_systems HTTP/1.1
Host: tycho-beta.propellerheads.xyz
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "chain": "ethereum",
  "pagination": {
    "page": 1,
    "page_size": 1
  }
}

200

OK

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

Retrieve tokens

post

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

Authorizations

Body

chainstring · enumOptional

Currently supported Blockchains

Possible values:

min_qualityinteger · int32 | nullableOptional

Quality is between 0-100, where:

• 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

token_addressesstring[] | nullableOptional

Filters tokens by addresses

traded_n_days_agointeger · int64 | nullableOptional

Filters tokens by recent trade activity

Responses

200

OK

application/json

post

HTTPcURLJavaScriptPython

POST /v1/tokens HTTP/1.1
Host: tycho-beta.propellerheads.xyz
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 123

{
  "chain": "ethereum",
  "min_quality": 1,
  "pagination": {
    "page": 1,
    "page_size": 1
  },
  "token_addresses": [
    "text"
  ],
  "traded_n_days_ago": 1
}

200

OK

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

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.

Authorizations

Body

Maximum page size for this endpoint is 100

chainstring · enumOptional

Currently supported Blockchains

Possible values:

contract_idsstring[] | nullableOptional

Filters response by contract addresses

protocol_systemstringOptional

Does not filter response, only required to correctly apply unconfirmed state from ReorgBuffers

Responses

200

OK

application/json

post

HTTPcURLJavaScriptPython

POST /v1/contract_state HTTP/1.1
Host: tycho-beta.propellerheads.xyz
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 212

{
  "chain": "ethereum",
  "contract_ids": [
    "text"
  ],
  "pagination": {
    "page": 1,
    "page_size": 1
  },
  "protocol_system": "text",
  "version": {
    "block": {
      "chain": "ethereum",
      "hash": "text",
      "number": 1
    },
    "timestamp": "2025-05-09T02:33:54.841Z"
  }
}

200

OK

{
  "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",
      "token_balances": {
        "0x....": "0x...."
      }
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 1,
    "total": 1
  }
}