Tycho
  • Quickstart
  • Overview
  • Motivation
  • Concepts
  • How to Contribute
    • Bounties
  • For Solvers
    • Indexer
      • Tycho RPC
      • Tycho Client
        • Binary / CLI
        • Rust Client
        • Python Client
    • Simulation
    • Execution
      • Encoding
      • Executing
      • Contract Addresses
      • Execution Venues
    • Hosted Endpoints
    • Supported Protocols
  • For DEXs
    • Protocol Integration
      • Indexing
        • 1. Setup
        • 2. Implementation
        • 3. Testing
          • How to Run
        • Common Problems & Patterns
          • Tracking Components
          • Tracking Contract Storage
          • Normalizing relative ERC20 Balances
          • Tracking Contract Balances
          • Custom protobuf models
        • Best Practices
        • Reserved Attributes
      • Simulation
        • Ethereum: Solidity
      • Execution
        • Code Architecture
      • Contributing guidelines
Powered by GitBook
On this page
Export as PDF
  1. For Solvers
  2. Indexer

Tycho RPC

PreviousIndexerNextTycho Client

Last updated 1 month ago

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
GET /v1/health HTTP/1.1
Host: tycho-beta.propellerheads.xyz
authorization: YOUR_API_KEY
Accept: */*
200

OK

{
  "message": "No db connection",
  "status": "NotReady"
}
  • Token Information
  • API Documentation
  • GETHealth check endpoint
  • POSTRetrieve protocol components
  • POSTRetrieve protocol states
  • POSTRetrieve protocol systems
  • POSTRetrieve tokens
  • POSTRetrieve contract states

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
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-06-01T11:01:26.979Z",
      "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
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-06-01T11:01:26.979Z"
  }
}
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
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
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
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-06-01T11:01:26.979Z"
  }
}
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
  }
}