# TzKT MCP

> TzKT (Tezos Indexer & Explorer API) connects your AI agent directly to the live Tezos blockchain ledger. Use it to query account details, inspect smart contract code (Michelson/Micheline), and trace complex transaction histories across Mainnet and testnets. It lets you analyze asset holdings, monitor operations by hash, and generate JSON reports on specific addresses without leaving your chat client.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** tezos, blockchain-explorer, indexer, smart-contracts, web3

## Description

Listen up. The `TzKT Tezos Indexer API` hooks your agent right into the live Tezos blockchain ledger. You're talking deep reads here—we’re talking everything from raw block headers to complex smart contract storage, and you can analyze it all without leaving your chat client.

**Tracing Account Activity Flow.** If you wanna know what happened with an account, you got a couple of tools for that. Use `get_account` to pull detailed information on any specific account address. To see the full money trail, run `get_account_balance_history`; it gives you a chronological list of every balance change over time. You can summarize everything into a neat JSON report using `get_account_report`. If you're just trying to get a snapshot of what accounts are floating around, use `list_accounts`, and you can filter those results by activity level or account type.

**Monitoring Asset Transfers.** Wanna track tokens? You've got options. Use `list_token_transfers` to list every token transfer event—it handles both the old FA1.2 format and the newer FA2 format, so you don't lose anything. For a specific account, use `list_token_balances` to get its current token balance, or if you need metadata on what tokens are even floating around, check out `list_token_definitions`. You can also get a list of all available 'big maps' with `list_bigmaps`, and track changes by running `list_bigmap_updates` for any specific big map key.

**Auditing Smart Contract Logic.** Need to poke at some smart contract code? You got this. Use `get_contract_code` to fetch the raw Michelson or Micheline code used by a contract, and `get_contract_entrypoints` lists every function—every entrypoint—that can actually be called on that contract. If you want to know what data it's keeping track of internally, use `get_contract_storage` to grab the current or historical key-value storage for a contract. You can also look at how contracts were first created using `list_originations`, and get a list of all existing smart contracts via `list_contracts`, letting you filter by creation parameters.

**Analyzing Network State.** Want to know what's going on network-wide? Use `get_statistics` to pull metrics like total transactions per second (TPS) or the overall volume. To check the latest indexer status, hit up `get_head`. You can also get a detailed breakdown of any single block using `get_block`, specifying it by either its hash or level number. If you're digging into specific transactions, `get_operations_by_hash` retrieves all operations and data tied to that transaction hash. To see everything that moved around the network in terms of staking, run `list_staking`. You can also get a list of all recorded delegation operations using `list_delegations`, or view every single operation by listing all transactions with `list_transactions`, where you can filter results based on sender, target, or amount.

**Deep Dive Data Retrieval.** If you're dealing with core ledger data, use `get_baker_rewards` to get the reward amount calculated for a specific cycle period, or calculate delegator payouts using `get_delegator_rewards`. You can list all recorded account creations and monitoring staking operations by running `list_deposits` and `list_originations`, respectively. Finally, if you just want a broad overview of what's happening with the ledger, you can run `get_head` to get the indexer’s current head block details.

## Tools

### get_account_balance_history
Retrieves a chronological list of balance changes for an account over time.

### get_account_report
Generates a structured JSON report summarizing all activity related to a single account.

### get_account
Fetches detailed information for a single, specified account address.

### get_baker_rewards
Retrieves the baker rewards amount calculated for a specific cycle period.

### get_block
Gets detailed information about a block, using either its hash or level number.

### get_contract_code
Fetches the raw Michelson or Micheline code used by a smart contract.

### get_contract_entrypoints
Lists all available functions (entrypoints) that can be called on a smart contract.

### get_contract_storage
Retrieves the current or historical key-value storage data for a contract.

### get_delegator_rewards
Calculates and returns the delegator rewards amount for a given cycle.

### get_head
Gets the latest state information, including the indexer's current head block details.

### get_operations_by_hash
Retrieves all operations and data associated with a specific transaction hash.

### get_statistics
Pulls network-wide metrics like total transactions per second (TPS) or volume.

### list_accounts
Lists multiple accounts, allowing you to filter results by balance, activity level, or account type.

### list_bigmap_keys
Retrieves all keys stored within a specific big map on the blockchain.

### list_bigmap_updates
Gets the historical record of updates made to a particular big map.

### list_bigmaps
Lists all available 'big maps' accessible on the network.

### list_blocks
Retrieves lists of blocks, supporting filters by time range or other criteria.

### list_contracts
Lists smart contracts, allowing filtering based on contract creation parameters.

### list_delegations
Fetches a list of all recorded delegation operations.

### list_originations
Retrieves records detailing how and when contracts were originally created (origination). 

### list_staking
Lists and summarizes staking-related operations that occurred on the network.

### list_token_balances
Gets the current token balance for one or more specific accounts.

### list_token_definitions
Retrieves metadata, standards, and definitions for tokens used on Tezos.

### list_token_transfers
Lists all token transfer events (both FA1.2 and FA2 formats) between accounts.

### list_transactions
Provides a comprehensive list of transactions, with advanced filters for sender, target, or amount.

## Prompt Examples

**Prompt:** 
```
List the top 5 accounts on Tezos mainnet with a balance greater than 1000 XTZ.
```

**Response:** 
```
I've queried the mainnet accounts. Here are 5 accounts with balances over 1000 XTZ, including tz1... (Balance: 1500 XTZ) and tz1... (Balance: 1200 XTZ). Would you like to see the full report for any of these?
```

**Prompt:** 
```
What are the available entrypoints for the smart contract KT1PWx2mnDuep3UMCcAgST9SetSjSEu7RZK1?
```

**Response:** 
```
I've retrieved the entrypoints for that contract. It features several callable functions including 'transfer', 'mint', 'burn', and 'set_metadata'. Which one would you like to inspect further?
```

**Prompt:** 
```
Get the details for the Tezos transaction with hash ooVp... on Ghostnet.
```

**Response:** 
```
Searching Ghostnet for operation ooVp... Found it! This was a transaction of 50 XTZ from tz1... to tz1... confirmed at block level 1,234,567. The status is 'applied'.
```

## Capabilities

### Trace Account Activity Flow
Get detailed profiles and full balance change history for any Tezos account using `get_account` and `get_account_balance_history`.

### Audit Smart Contract Logic
Inspect the underlying contract code (Michelson/Micheline) and list all callable entrypoints or current storage states for a specific KT1 address.

### Monitor Asset Transfers
List token transfers, supporting both FA1.2 and FA2 formats, or get granular details on token balances for specified accounts using `list_token_transfers`.

### Generate Financial Reports
Produce structured JSON reports detailing account activity and transaction flows across defined Tezos addresses via `get_account_report`.

### Analyze Network State
Retrieve network-wide statistics like TPS or total volume using `get_statistics`, or check the current indexer head status with `get_head`.

## Use Cases

### Auditing an Investment Pool
A DeFi auditor needs to confirm every movement of a pooled asset. Instead of cross-referencing multiple block explorer tabs, the agent runs `list_transactions` filtered by the pool's contract address, then uses `get_operations_by_hash` on key transactions to verify all associated actions.

### Debugging a New Contract
A developer wrote a new smart contract that isn't storing data correctly. They first run `get_contract_code` to check the logic, then call `list_bigmaps` and examine specific keys using `list_bigmap_keys` to isolate where the state change failed.

### Tracking an Individual User's Wealth
A data analyst needs a full picture of one wallet. They start by running `get_account` for the address, then follow up with `get_account_balance_history` and finally `list_token_transfers` to build a complete financial timeline.

### Checking Network Capacity
A product manager needs to report on recent network usage. They ask the agent for network statistics, triggering `get_statistics`, which provides current TPS and volume data instantly, perfect for reports or dashboards.

## Benefits

- Pinpoint every asset movement by running `list_token_transfers` to track both FA1.2 and FA2 transfers across the ledger.
- Get a complete financial picture of an address using `get_account_report`, which bundles balance history and activity into one JSON output.
- Debug smart contract behavior immediately. Use `get_contract_code` to pull the raw Michelson/Micheline code, and then check state via `get_contract_storage`.
- Analyze network health on demand. Call `get_statistics` for real-time metrics (like TPS) or use `list_blocks` to review historical block data by specific filters.
- Track complex ownership paths using the combined power of `list_token_transfers` and `list_accounts`, making it easy to audit asset flow without leaving your chat interface.

## How It Works

The bottom line is that it turns complex blockchain calls into simple chat commands, letting you read live state data directly from your AI client.

1. Subscribe to this server. You'll connect it via your preferred AI client (Claude, Cursor, etc.).
2. (Optional) Input your TzKT API Key if you need higher rate limits for heavy querying.
3. Ask your agent to perform a specific query, like 'list all transactions involving address X', and the tool runs the necessary lookup against the Tezos ledger.

## Frequently Asked Questions

**How do I find out what tokens an account holds?**
Use the `list_token_balances` tool. This function retrieves the current token balance for specific accounts, providing clearer data than general transaction listings alone.

**What is the difference between `list_transactions` and `get_operations_by_hash`?**
`list_transactions` gives you a broad list of operations across many hashes. Use `get_operations_by_hash` when you know the exact transaction hash and need all associated data for that single operation.

**Can I see how much reward was earned by stakers?**
Yes, use the dedicated functions like `list_staking` or `get_delegator_rewards`. These tools calculate and report specific rewards based on delegation cycles.

**Do I need to know Michelson vs Micheline code for debugging?**
The tool handles it. Use `get_contract_code` and it will return the contract's underlying language (Michelson or Micheline) so you can debug based on what was deployed.

**If I run a large query using `list_transactions`, how do I handle rate limits?**
You must enter your TzKT API Key to increase the rate limit. Without it, repeated queries will hit default restrictions and fail. The key allows your agent to send more requests in a shorter time frame.

**When I use `list_accounts`, does the network I query affect the results?**
Yes, you must specify which blockchain network you are targeting (Mainnet, Ghostnet, or Shadownet). Running a list command without defining the network will result in an error because the data is isolated by chain.

**What should I do if `get_operations_by_hash` fails because the hash doesn't exist?**
The API returns a specific error code indicating no matching operation was found. You can then adjust your query or confirm the transaction hash with other sources.

**How do I filter results when using `list_contracts` beyond just name?**
You pass advanced parameters like contract type, minimum balance, or creation date into the function call. This narrows down millions of entries to only the relevant subset you need.

**Can I see how an account's balance has changed over time?**
Yes! Use the `get_account_balance_history` tool with the account address. It will return a historical record of balance changes for that specific Tezos address.

**How do I check the current state or storage of a smart contract?**
You can use the `get_contract_storage` tool by providing the contract's KT1 address. This will retrieve the current data stored in the contract's state.

**Is it possible to list transactions for a specific sender or target?**
Absolutely. Use the `list_transactions` tool and apply filters like `sender` or `target` to narrow down the results to specific addresses or interaction flows.