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 Tycho RPCendpoint. 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

https://tycho-beta.propellerheads.xyzhttps://tycho-base-beta.propellerheads.xyzhttps://tycho-unichain-beta.propellerheads.xyz

/v1/health

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

Authorizations

apiKey

authorizationstringRequired

Use 'sampletoken' as value for testing

Responses

200

OK

application/json

get

/v1/health

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

https://tycho-beta.propellerheads.xyzhttps://tycho-base-beta.propellerheads.xyzhttps://tycho-unichain-beta.propellerheads.xyz

/v1/protocol_components

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

Authorizations

apiKey

authorizationstringRequired

Use 'sampletoken' as value for testing

Body

application/json

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

/v1/protocol_components

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": "2026-02-06T17:13:58.367Z",
      "creation_tx": "text",
      "id": "text",
      "protocol_system": "text",
      "protocol_type_name": "text",
      "static_attributes": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "tokens": [
        "text"
      ]
    }
  ]
}

Retrieve protocol states

post

https://tycho-beta.propellerheads.xyzhttps://tycho-base-beta.propellerheads.xyzhttps://tycho-unichain-beta.propellerheads.xyz

/v1/protocol_state

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

Authorizations

apiKey

authorizationstringRequired

Use 'sampletoken' as value for testing

Body

application/json

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

/v1/protocol_state

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": "2026-02-06T17:13:58.367Z"
  }
}

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

https://tycho-beta.propellerheads.xyzhttps://tycho-base-beta.propellerheads.xyzhttps://tycho-unichain-beta.propellerheads.xyz

/v1/protocol_systems

This endpoint retrieves the protocol systems available in the indexer.

Authorizations

apiKey

authorizationstringRequired

Use 'sampletoken' as value for testing

Body

application/json

chainstring · enumOptional

Currently supported Blockchains

Possible values:

Responses

200

OK

application/json

post

/v1/protocol_systems

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

https://tycho-beta.propellerheads.xyzhttps://tycho-base-beta.propellerheads.xyzhttps://tycho-unichain-beta.propellerheads.xyz

/v1/tokens

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

Authorizations

apiKey

authorizationstringRequired

Use 'sampletoken' as value for testing

Body

application/json

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

/v1/tokens

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

https://tycho-beta.propellerheads.xyzhttps://tycho-base-beta.propellerheads.xyzhttps://tycho-unichain-beta.propellerheads.xyz

/v1/contract_state

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

apiKey

authorizationstringRequired

Use 'sampletoken' as value for testing

Body

application/json

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

/v1/contract_state

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": "2026-02-06T17:13:58.367Z"
  }
}

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
  }
}