DOCSEARCHbyAlgolia
Submit Docs

TzKT Tezos Blockchain Indexer and API

repository·master·Indexed 41 days ago

https://github.com/baking-bad/tzkt

An advanced Tezos blockchain indexer and API provider that processes raw blockchain data into a PostgreSQL database. It offers a REST-like API, WebSocket (SignalR) for real-time subscriptions, and dedicated TypeScript SDKs (@tzkt/sdk-api and @tzkt/sdk-events). TzKT also provides a Taquito extension (@tzkt/ext-taquito) to route specific requests to its API for improved performance. Available as a self-hosted solution via Docker or as a managed service with Free and Pro tiers.

Tokens
10.7K
Snippets
39
Records
42
Agent score
52%

What's inside TzKT

  1. Understand TzKT WebSocket message types

    master

    Once a client connects and subscribes via the WebSocket, the server sends three distinct types of messages. Understanding these is critical for maintaining data consistency and handling chain reorganizations.

    1. State Message (type: 0)

    This is the first message received after opening a subscription. It serves as a confirmation that the subscription was successful. The state field indicates the current progress of the subscription.

    • Usage: Use the state value to fetch historical data from the REST API to bridge the gap between your last known state and the real-time stream, ensuring no data is missed or duplicated.
    • Example: If subscribing to blocks and you receive state: 1300123, the next expected block is 1300124.

    2. Data Message (type: 1)

    Sent after the state message. The data field contains the actual blockchain information (blocks, operations, etc.).

    • Format: data can be an object or an array. Receiving multiple items in a single message is common for performance optimization.
    • Consistency: The data models used in WebSocket messages are identical to those used in the TzKT REST API.

    3. Reorg Message (type: 2)

    Signals a chain reorganization where blocks and operations are rolled back in favor of a different chain branch.

    • Criticality: You must handle these messages to avoid accumulating duplicate or invalid data.
    • Handling Logic: If you have saved blocks 10, 11, 12, 13 and receive a reorg message with state: 11, you must remove blocks 12 and 13 from your local storage as they are no longer valid.
    // State message example
{
	type: 0,
	state: 0
}

// Data message example
{
	type: 1,
	state: 0,
	data: {}
}

// Reorg message example
{
	type: 2,
	state: 0
}

  2. Install TzKT from source on Ubuntu

    master

    To install TzKT from source on Ubuntu 22.04, you must install Git, the .NET SDK, and PostgreSQL.

    Note: This process involves manual database creation and snapshot restoration.

    # Install Git
sudo apt update
sudo apt install git

# Install .NET
sudo add-apt-repository ppa:dotnet/backports
sudo apt update
sudo apt install -y dotnet-sdk-9.0

# Install PostgreSQL
sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update
sudo apt install -y postgresql-17

  4. Authorize requests for TzKT Pro

    master

    TzKT Pro requires an API key provided via your paid subscription. You can authorize requests using either a query string parameter or an HTTP header.

    Security Note: It is highly recommended to use the HTTP header method (apikey: {your_key}) because headers are encrypted in HTTPS, whereas query strings may be unintentionally exposed.

    Authorization Methods:

    1. Query String: Append ?apikey={your_key} to the URL.
    2. HTTP Header: Add the header apikey: {your_key} to your request.
    # Using HTTP header (Recommended)
curl https://pro.tzkt.io/v1/head -H 'apikey: {your_key}'

# Using query string
curl https://pro.tzkt.io/v1/head?apikey={your_key}

  5. Use the Free TzKT API

    master

    The Free TzKT API provides anonymous access to Tezos blockchain data without requiring authorization. It is suitable for exploration and non-commercial use.

    Requirement: Attribution If you use the free tier, you must include an attribution label on your website or application, such as "Powered by TzKT API", "Built with TzKT API", or "Data provided by TzKT API", with a direct link to tzkt.io.

    Base URLs by Network:

    • Mainnet: https://api.tzkt.io/ or https://api.mainnet.tzkt.io/
    • Shadownet: https://api.shadownet.tzkt.io/
    • Ushuaianet: https://api.ushuaianet.tzkt.io/
    • Bakingnet: https://api.bakingnet.tzkt.io/
    curl https://api.tzkt.io/v1/head

  6. Configure and run the TzKT API

    master

    The API (Tzkt.Api) provides a REST-like interface to the indexed data.

    Configuration: Edit appsettings.json in the published directory. Key settings include:

    • ConnectionStrings.DefaultConnection: Must point to the same database used by the indexer.
    • ResponseCache.CacheSize: Sets the cache limit in MB (default is enabled; set to 0 to disable).
    • RpcHelpers: Enables proxying requests directly to the node RPC. The Endpoint must match the network/chain_id used by the indexer.
    • Kestrel.Endpoints.Http.Url: Configures the listening port (default is 5000).
    • MetricsOptions.Enabled: Enables Prometheus metrics at http://localhost:5000/metrics.

    Build and Run:

    1. Publish the project using dotnet publish.
    2. Run the resulting DLL using dotnet Tzkt.Api.dll.
    # Build
cd ~/tzkt/Tzkt.Api/
dotnet publish -o ~/tzkt-api

# Run
cd ~/tzkt-api
dotnet Tzkt.Api.dll

  7. Install SignalR package for C#

    master

    Install the required SignalR client package via dotnet CLI. If you are using .NET 5.0, you will also need System.Text.Encodings.Web.

    > dotnet add package Microsoft.AspNetCore.SignalR.Client
// if you use .NET 5.0 you will likely also need:
> dotnet add package System.Text.Encodings.Web

  9. Subscribe to real-time events via WebSocket

    master

    Use the EventsService from @tzkt/sdk-events to subscribe to real-time blockchain events.

    Key behaviors:

    • Lazy Connection: The connection to the WebSocket endpoint is not initiated until the first subscription request is made.
    • Automatic Reconnection: The service attempts to reconnect infinitely by default if the connection drops.
    • Unsubscribing: Calling .unsubscribe() on a subscription stops your observer from firing, but does not change the subscription state on the TzKT server.
    • Termination: Use await events.stop() to terminate the connection entirely. Note that sending a new subscription request after stopping will restart the service.
    import { EventsService } from "@tzkt/sdk-events";

// Initialize the service
const events = new EventsService({ url: "https://api.tzkt.io/v1/ws", reconnect: true });

// Subscribe to specific operations (connection starts here)
const sub = events.operations({ types: [ 'origination' ] })
    .subscribe({ next: console.log });

// Monitor connection status
events.status()
    .subscribe({ next: console.log });

// Stop receiving updates
sub.unsubscribe();

// Terminate the connection
await events.stop();

  10. Configure and run the TzKT Indexer

    master

    The indexer (Tzkt.Sync) processes raw blockchain data and saves it to PostgreSQL.

    Configuration: Edit appsettings.json in the published directory. Key settings include:

    • TezosNode.Endpoint: The RPC endpoint to fetch data from.
    • ConnectionStrings.DefaultConnection: The PostgreSQL connection string.
    • TezosNode.Lag: The number of blocks to lag behind the head to avoid chain reorgs (recommended: 1-2).
    • MetricsOptions.Enabled: Enables Prometheus metrics at http://localhost:5001/metrics.

    Build and Run:

    1. Publish the project using dotnet publish.
    2. Run the resulting DLL using dotnet Tzkt.Sync.dll.
    # Build
cd ~/tzkt/Tzkt.Sync/
dotnet publish -o ~/tzkt-sync

# Run
cd ~/tzkt-sync
dotnet Tzkt.Sync.dll

  11. Install TzKT via Docker

    master

    The fastest way to run the TzKT indexer and API is using Docker and Docker Compose. This method allows you to restore the database from a recent snapshot automatically.

    1. Clone the repository.
    2. Run make init to restore the database from the latest snapshot (skip this if you want to index the blockchain from scratch).
    3. Run make start to launch the database, indexer, and API. By default, the API is available at http://127.0.0.1:5000.
    4. Use make stop to shut down the services.
    git clone https://github.com/baking-bad/tzkt
cd tzkt/

make init  # Restores DB from the latest snapshot
make start # Starts DB, indexer, and API
make stop  # Stops DB, indexer, and API