# Harmonyscan MCP

> Harmonyscan (Harmony One Block Explorer API) gives your AI client deep read access to the Harmony blockchain data. It lets you query things like specific wallet balances, track complex token transfers, audit smart contracts for their source code, and monitor total network supply—all without opening a browser. You get real-time insight into ONE transactions and contract activity directly from your agent.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** harmony-one, block-explorer, web3, smart-contracts, crypto-api

## Description

Harmonyscan connects your AI agent to the Harmony One network, letting you inspect everything happening on the blockchain. Instead of manually hopping between tabs and reading endless transaction hashes in a web explorer, your agent pulls all the data for you. You can check balances across multiple addresses at once or track down every internal transfer that occurred within a smart contract. Need to know how a specific contract works? Your agent fetches the full source code and the required ABI automatically. This capability means analyzing complex DeFi movements or tracking whale wallets becomes a simple conversation with your AI client, all managed through Vinkius’s catalog.

## Tools

### get_abi
Retrieves the Application Binary Interface (ABI) necessary for interacting with a specific smart contract.

### get_balance_multi
Calculates and returns the ONE balances for a list of multiple addresses simultaneously.

### get_balance
Checks the current ONE balance associated with a single crypto wallet address.

### get_block_reward
Fetches information regarding the block rewards provided by the Harmony One network.

### get_logs
Retrieves event logs emitted by smart contracts during specific transactions.

### get_one_price
Provides the most recent recorded price for one ONE token.

### get_one_supply
Determines and reports the total circulating supply of the ONE token on the network.

### get_source_code
Retrieves the verified original source code for a given smart contract address.

### get_status
Verifies whether a transaction has finished executing and what its final status was.

### get_token_tx
Lists all recorded events for HRC20 token transfers, showing who sent tokens to whom.

### get_tx_list_internal
Retrieves a record of internal transactions, which are calls made from one contract to another.

### get_tx_list
Pulls a comprehensive list of standard transactions that occurred on the network.

### get_tx_receipt_status
Checks the detailed receipt status for a transaction hash, providing granular execution details.

### proxy_request
Executes standard JSON-RPC calls against the blockchain using a generic proxy method.

## Prompt Examples

**Prompt:** 
```
What is the current ONE balance for address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e?
```

**Response:** 
```
The current balance for that address is 1,250.45 ONE.
```

**Prompt:** 
```
List the last 5 HRC20 token transfers for address 0x123...
```

**Response:** 
```
I've found the 5 most recent HRC20 transfers. They include 100 VIPER tokens received yesterday and 50 FOX tokens sent 2 hours ago. Would you like the full details for any of these?
```

**Prompt:** 
```
Get the ABI and source code for the contract at 0x0809D4A52411430218Af7a6d8f17513E99770059.
```

**Response:** 
```
I have retrieved the verified source code and ABI for the contract. It is a 'ViperSwap' liquidity pool contract compiled with Solidity 0.6.12. I can now help you analyze its functions or events.
```

## Capabilities

### Check account balances
Determine the current ONE balance for one or many specific addresses.

### Analyze transaction history
Retrieve a detailed list of all normal, internal, and token-specific transfers connected to an address.

### Audit smart contracts
Get the full source code and Application Binary Interface (ABI) for any contract deployed on the network.

### Monitor network metrics
Fetch critical data points like the total ONE supply, current block rewards, or real-time price feeds.

### Verify transaction status
Check if a specific transaction has been executed successfully or is still pending confirmation.

## Use Cases

### Auditing a DeFi Protocol
A security analyst needs to understand how a liquidity pool works. They ask their agent to run `get_abi` and `get_source_code` on the contract address, then cross-reference that with recent transfers using `get_token_tx`. This pinpoints exactly which functions control the pooled assets.

### Tracking Corporate Wallet Movements
A finance team wants to monitor a set of 50 corporate wallets. They use `get_balance_multi` first, then request all historical activities for those addresses using `get_tx_list` and `get_logs` to catch any unusual outgoing transfers.

### Debugging Failed Transactions
A user's transaction failed. Instead of guessing, they tell their agent to run `get_status` followed by `get_tx_receipt_status`. This confirms if the failure was due to contract logic or a simple network issue.

### Calculating Network Value
A researcher needs market context. They ask their agent for the total ONE supply (`get_one_supply`) and the current price (`get_one_price`) in one go, giving them an immediate valuation metric.

## Benefits

- Stop manually reading block explorer pages. You can get a list of normal transactions using `get_tx_list` or internal calls with `get_tx_list_internal`, making tracing token flows easy.
- Audit contracts fast. Using `get_source_code` and `get_abi` lets you pull the full contract blueprint right into your workflow, speeding up development immensely.
- See exactly where money moved. Instead of just seeing a transaction hash, use `get_token_tx` to see every recorded HRC20 token transfer event.
- Validate complex movements instantly. Need to know if an action finished? Use `get_status` or `get_tx_receipt_status` to confirm execution results without guessing.
- Get the big picture data points—like total supply via `get_one_supply` or current market prices using `get_one_price`—with a single request.

## How It Works

The bottom line is that your AI client acts as a dedicated blockchain analyst, giving you immediate answers without needing to manually navigate block explorer pages.

1. Subscribe to the MCP and input your Harmonyscan API Key.
2. Direct your AI agent (Claude, Cursor, etc.) to query specific data points, like 'What is the balance at 0x...' or 'List all transactions for this address.'
3. Your agent executes the necessary calls and returns structured data on addresses, contracts, and network health.

## Frequently Asked Questions

**How do I find out if a transaction succeeded? (Using get_status)**
You check execution status using `get_status`. This tells you whether the network accepted and completed the transaction for that hash.

**What is the difference between get_tx_list and get_tx_list_internal?**
`get_tx_list` shows transactions initiated by wallets, while `get_tx_list_internal` reveals calls made from one smart contract to another—crucial for understanding complex DeFi flows.

**How do I audit a contract's logic? (Using get_source_code)**
To audit, use `get_source_code` to pull the verified original code. You can then pair this with `get_abi` to understand exactly which functions are available for interaction.

**Can I check multiple wallet balances at once? (Using get_balance_multi)**
Yes, use `get_balance_multi`. It takes a list of addresses and returns the ONE balance for every single one in that list efficiently.

**I need to know how to get the ABI using `get_abi` for a contract.**
You request the specific Application Binary Interface (ABI) needed to interact with that contract. The ABI is essentially a roadmap; it tells your AI client exactly which functions the contract supports and what inputs they require.

**What kind of information can I pull using `get_logs`?**
`get_logs` retrieves event logs, showing specific actions or signals emitted by a smart contract. These are often critical internal events that aren't visible in the main transaction list but confirm business logic execution.

**Does `get_token_tx` track token movements differently than general transactions?**
Yes, `get_token_tx` focuses specifically on HRC20 token transfers. It isolates the movement of fungible tokens, making it much easier to audit pure asset flow separate from other contract interactions.

**How do I find out what block rewards are using `get_block_reward`?**
`get_block_reward` provides the current distribution of block rewards. This tells you what incentives or tokens are paid out to validators and miners for processing new blocks on the Harmony One network.

**Can I check the balance of multiple Harmony addresses at once?**
Yes! Use the `get_balance_multi` tool and provide a comma-separated list of addresses (up to 20). The agent will return the ONE balance for each address in a single response.

**How do I verify if a specific transaction was successful or failed?**
You can use the `get_status` tool with the transaction hash. It returns a status code where '1' indicates success and '0' indicates failure, along with any available error messages.

**Is it possible to retrieve the source code of a smart contract?**
Yes, provided the contract is verified on Harmonyscan. Use the `get_source_code` tool with the contract address to get the Solidity source code, compiler version, and optimization settings.