# Celoscan MCP

> Celoscan (Celo Network Explorer) MCP gives your AI client direct access to the Celo blockchain data. You can check account balances, track all token transfers (ERC20 and NFT), audit smart contract source code, or review internal transaction flows—all through natural language prompts.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** celo, block-explorer, smart-contracts, crypto-wallet, web3

## Description

The complexity of on-chain data is a major blocker for rapid analysis. Normally, figuring out what happened to an address means jumping between multiple explorer tabs, tracking down specific contract ABIs, and manually correlating transfer logs for every asset class. This MCP changes that. It connects your AI client directly to the Celo network’s core data streams. You don't write complex RPC calls or juggle dozens of endpoints; you just ask the question. Your agent handles the logic, retrieving everything from current CELO holdings to deep internal transaction details and even the contract source code itself. This is how Vinkius makes connecting specialized blockchain services simple. You get actionable data—structured lists of transfers, specific balances, or block numbers—all without leaving your chat window.

## Tools

### get_erc20_token_balance
Checks the balance of a specific ERC20 token held by an account, identified by its contract address.

### get_erc20_token_supply
Finds out the total circulating supply for any given ERC20 token contract.

### get_account_balance
Retrieves the current CELO balance for one specific blockchain address.

### get_block_countdown
Estimates how long it will be until the next block is mined, based on the target block number.

### get_block_number_by_time
Finds out which block number was active at a specific date and time stamp.

### get_block_reward
Determines the reward amount for mining a particular block number.

### get_contract_abi
Fetches the Application Binary Interface (ABI) definition for any verified smart contract address.

### get_contract_source_code
Retrieves the original source code written for a verified smart contract.

### get_account_balance_multi
Calculates and returns the CELO balances for a list of multiple addresses at once.

### get_erc20_transfers
Lists all historical transfer events for a specific ERC20 token associated with an address.

### get_erc721_transfers
Provides a list of ownership transfers for unique NFTs (ERC721) involving an address.

### get_internal_transactions
Retrieves complex, internal transactions that might not show up in standard history views.

### get_last_celo_price
Gets the most recent market price for CELO against a fiat or stablecoin pairing.

### get_mined_blocks
Lists all blocks that have been mined by an address over time.

### get_normal_transactions
Gets a standard list of public transactions associated with an address.

### get_total_celo_supply
Calculates the total number of CELO tokens currently in existence on the network.

### get_transaction_execution_status
Verifies whether a smart contract transaction executed successfully according to its internal logic.

### get_transaction_receipt_status
Checks the overall receipt status of a transaction hash on the blockchain.

## Prompt Examples

**Prompt:** 
```
What is the CELO balance for the address 0x1234567890abcdef1234567890abcdef12345678?
```

**Response:** 
```
The account balance for that address is 150.25 CELO.
```

**Prompt:** 
```
List the recent ERC20 token transfers for address 0xabcdef...
```

**Response:** 
```
I found 5 recent ERC20 transfer events for that address. The most recent was a transfer of 50 cUSD from 0x789... to 0xabc... at block 12345678.
```

**Prompt:** 
```
Get the ABI for the smart contract at 0x1234...
```

**Response:** 
```
I've retrieved the ABI for the contract. It contains functions such as `transfer`, `balanceOf`, and `approve`. Would you like me to explain any specific function?
```

## Capabilities

### Check Account Holdings
Instantly fetch the CELO balance for a single address or calculate total holdings across multiple addresses.

### Audit Smart Contracts
Retrieve verified contract ABIs and full source code, letting you inspect exactly how a smart contract is built.

### Trace Token Movements
Get detailed lists of ERC20 token transfers or track specific NFT (ERC721) movements associated with any address.

### Review Transaction History
Query both normal, public transactions and internal, complex system transactions for a complete audit trail.

### Monitor Network State
Determine the last known price of CELO or check estimated block countdown times by querying specific block numbers.

## Use Cases

### Validating an Asset Sale
A crypto auditor asks their agent: 'What was the full flow of funds for this sale?' The agent runs `get_account_balance`, then checks both `get_erc20_transfers` and `get_internal_transactions` to confirm that all expected tokens moved correctly, validating the entire event chain.

### Debugging a Smart Contract
A developer needs to validate if a contract function is working. They use `get_contract_source_code` and then run `get_transaction_execution_status` on recent data, allowing them to pinpoint exactly where the logic failed.

### Tracking Portfolio Changes
A user wants to audit their total assets across five different wallets. Instead of running five separate checks, they use `get_account_balance_multi` to get all CELO balances in a single query.

### Forensic Analysis
Data analysts need historical evidence. They use `get_normal_transactions` and cross-reference that data with `get_mined_blocks` to build a comprehensive timeline of activity for reporting purposes.

## Benefits

- Stop guessing balances. Use `get_account_balance` or `get_account_balance_multi` to instantly know an address's current CELO holdings, whether you're checking one wallet or a portfolio of ten.
- Need to understand the code? Run `get_contract_source_code` and pull the full ABI using `get_contract_abi`. You get the raw logic needed for deep protocol validation right in your chat session.
- Don’t trust just the main transaction history. Use `get_internal_transactions` to see the complex, underlying movements that often determine the true flow of funds on the network.
- Track every piece of value. You can get lists of ERC20 token transfers via `get_erc20_transfers` and specifically track unique NFT ownership changes using `get_erc721_transfers`.
- Get a full picture of time and state by checking the current market rate with `get_last_celo_price`, or mapping historical data points using `get_block_number_by_time`.

## How It Works

The bottom line is that your agent handles all the messy API calls, giving you clean, actionable blockchain data in one go.

1. Subscribe to this MCP and provide your Celoscan API key.
2. Your AI client sends a natural language prompt, specifying the addresses or contracts you need to check.
3. The MCP executes the necessary data queries and returns structured JSON containing the requested balances, transfer lists, or contract code.

## Frequently Asked Questions

**How do I check if a transaction succeeded using get_transaction_receipt_status?**
You pass the transaction hash to `get_transaction_receipt_status`. It returns whether the overall blockchain receipt confirms execution success or failure, which is key for basic validation.

**Can I check multiple balances at once using get_account_balance_multi?**
Yes. You provide a list of addresses to `get_account_balance_multi`, and it returns the CELO balance for every single address in that batch response.

**What is the difference between get_normal_transactions and get_internal_transactions?**
Normal transactions are the visible, public records of asset movement. Internal transactions capture the complex system logic or fund flows that happen *behind* those public movements.

**Do I need to run get_erc20_token_supply for every token?**
Yes. To confirm the total supply, you must use `get_erc20_token_supply` and specify the contract address for each individual ERC20 token.

**What if I want to see NFT transfers? Do I use get_erc721_transfers?**
Yes, that's right. Use `get_erc721_transfers` when you need a list of ownership changes for unique NFTs (ERC721 tokens). It handles those specific transfer events.

**If I run many calls using get_normal_transactions, how do I handle rate limits?**
The MCP adheres to standard API rate limits, providing a clear error response when the limit is hit. Your agent needs to implement exponential backoff logic in your workflow when fetching large volumes of transaction data.

**How do I find out what block number corresponds to a specific timestamp using get_block_number_by_time?**
This function takes an Epoch timestamp and returns the exact corresponding block number on the Celo network. It allows you to map historical events precisely without needing manual lookups.

**What should my agent do if get_transaction_receipt_status fails for a transaction?**
If the function returns an error, it usually means the transaction hash is invalid or the block isn't mined yet. Your agent must check for specific failure codes before assuming a network connectivity issue.

**Can I check the CELO balance of multiple addresses in a single request?**
Yes! Use the `get_account_balance_multi` tool and provide a comma-separated list of Celo addresses to retrieve all balances at once.

**How can I view the source code of a verified smart contract on Celo?**
You can use the `get_contract_source_code` tool with the contract's address. If the contract is verified on Celoscan, the agent will return the full source code.

**Is it possible to check if a specific transaction was successful?**
Yes, the `get_transaction_receipt_status` tool allows you to check the status of a transaction receipt to confirm if it was processed successfully on the network.