# Polygonscan MCP

> Polygonscan (Polygon Block Explorer) MCP Server queries the MATIC blockchain directly. Use this server to check wallet balances, track every type of token transfer (ERC-20, NFT, ERC-1155), and inspect smart contract source code—all through your AI client.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** polygon, matic, block-explorer, web3, smart-contracts

## Description

You gotta connect Polygonscan to your agent when you need real visibility into the MATIC blockchain. This server lets your AI client pull on-chain data using plain language, meaning you skip jumping between tabs or writing complex API calls just to check a balance or track a token.

**Checking Balances and Network Status**

You can instantly get the current MATIC balance for one specific address using `get_balance`, or you can pull the total MATIC balance across a bunch of addresses at once with `get_balance_multi`. For network metrics, the system provides the latest recorded market price for MATIC via `get_matic_price` and calculates the total circulating supply of MATIC on Polygon by calling `get_matic_supply`. If you need to track time-based data, you can use `get_block_no_by_time` to find out which block number was active at a specific Unix timestamp. You'll also get an estimated time until the next block using `get_block_countdown`, and for historical context, it retrieves the MATIC reward amount associated with any given block number via `get_block_reward`.

**Tracking Wallet Activity and Transactions**

To audit a wallet, you can fetch all normal, user-initiated transactions on the network using `get_tx_list`, or you can pull a list of internal smart contract function calls and transfers with `get_tx_list_internal`. When checking transaction status, you've got two ways: use `get_tx_status` to confirm if a smart contract execution completed successfully, or check the final processing status—whether it succeeded or failed—of a specific transaction receipt using `get_tx_receipt_status`. For deep activity logs, you can fetch raw event logs associated with specific addresses or transactions by calling `get_logs`.

**Monitoring Token Transfers**

Tracking tokens is where this server shines. You'll get the historical transfer events specifically for ERC-721 (NFT) tokens when you use `get_token_nft_tx`. For standard, fungible assets like ERC-20 tokens, you pull the entire transaction event history using `get_token_tx`. If you’re dealing with multi-standard tokens that support both NFTs and fungibles—like ERC-1155—you can list all detected transfer events across a given period or address via `get_token_1155_tx`.

**Inspecting Smart Contracts**

When you need to dig into the code, this server gets you what you need. You pull the full Application Binary Interface (ABI) for a verified smart contract address using `get_contract_abi`. If you want to see how the contract was originally built, you can retrieve the original source code by calling `get_contract_source_code` on any verified contract address.

## Tools

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

### get_balance_multi
Gets the total MATIC balance for a list of multiple addresses at once.

### get_balance
Retrieves the current MATIC balance for one specific blockchain address.

### get_block_countdown
Calculates and returns an estimated time until the next block, based on a given block number.

### get_block_no_by_time
Determines which block number was active at a specific Unix timestamp.

### get_block_reward
Retrieves the MATIC reward amount associated with a given block number.

### get_logs
Fetches raw event logs associated with specific transactions or addresses.

### get_matic_price
Retrieves the latest recorded market price for MATIC.

### get_matic_supply
Calculates and returns the total circulating supply of MATIC on Polygon.

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

### get_token_1155_tx
Lists all detected transfer events for ERC-1155 tokens across a given period or address.

### get_token_nft_tx
Gets the list of historical transfer events specifically for ERC-721 (NFT) tokens.

### get_token_tx
Retrieves the transaction event history for standard ERC-20 tokens.

### get_tx_list_internal
Retrieves a list of internal smart contract function calls and transfers.

### get_tx_list
Fetches a list of all normal, user-initiated transactions on the network.

### get_tx_receipt_status
Checks the final processing status (success or failure) of a specific transaction receipt.

### get_tx_status
Confirms if a smart contract execution, triggered by a transaction, completed successfully.

## Prompt Examples

**Prompt:** 
```
What is the current MATIC balance of address 0x0000000000000000000000000000000000001010?
```

**Response:** 
```
I've checked the address. The current MATIC balance for 0x000...1010 is 15,240.45 MATIC.
```

**Prompt:** 
```
List the last 5 normal transactions for address 0x123...
```

**Response:** 
```
Fetching transaction history... I found the 5 most recent transactions for that address. The latest one was a transfer of 50 MATIC to 0xabc... on block 62451203.
```

**Prompt:** 
```
Get the ERC-20 token transfer events for address 0x456...
```

**Response:** 
```
I've retrieved the ERC-20 transfer events. There are several recent transfers, including 100 USDC and 500 LINK tokens moving through this address.
```

## Capabilities

### Check Balances
Get the current MATIC balance for one or many Polygon addresses.

### Audit Transactions
List a wallet’s normal and internal transaction history, and check their final execution status.

### Track Tokens
Get lists of specific token transfers, including ERC-20, NFTs (ERC-721), and multi-standard tokens (ERC-1155).

### Inspect Contracts
Retrieve the full ABI or source code for verified smart contracts.

### Monitor Network Metrics
Access real-time MATIC price, total supply, and block timing data.

## Use Cases

### Checking for Smart Contract Failures
A user sees a transaction but isn't sure if it completed. They prompt: 'Check the status of TX hash X.' The agent runs `get_tx_receipt_status` and tells them immediately if the contract execution failed, saving them from wasting time on dead-end data.

### Forensic Token Tracking
An analyst needs to track a specific asset type. They ask: 'Show me all ERC-721 transfers for this wallet.' The agent uses `get_token_nft_tx`, providing the exact history of unique digital assets without manual filtering.

### Quick Multi-Wallet Audit
A developer needs to verify collateral across five different accounts. They use `get_balance_multi` with a list of addresses, getting all MATIC balances in one single API call instead of running five individual checks.

### Verifying Token Distribution
A team needs to know the total supply and current market value. They ask for 'MATIC total supply and price.' The agent runs `get_matic_supply` and `get_matic_price`, giving them immediate macro data.

## Benefits

- Get balance data fast. Instead of opening a separate block explorer, you simply ask for the MATIC amount using `get_balance` or `get_balance_multi`. Done in one prompt.
- Audit complex activity. You can list both normal transactions (`get_tx_list`) and internal contract calls (`get_tx_list_internal`), giving you a complete view of wallet usage.
- Track all token types. Don't just look at MATIC. Use `get_token_tx` for USDC, `get_token_nft_tx` for art NFTs, or `get_token_1155_tx` for multi-standard assets—all from one chat window.
- Understand contract logic. Need to know *how* a token moves? Use `get_contract_abi` and `get_contract_source_code` before you write the integration code.
- Check execution status instantly. Before trusting a transfer, use `get_tx_receipt_status` or `get_tx_status` to confirm if the contract actually finished running as expected.

## How It Works

The bottom line is: your AI client handles the API calls; you just ask questions about Polygon's state.

1. Subscribe to the server and provide your Polygonscan API Key.
2. Ask your AI client a question using natural language (e.g., 'What's the MATIC balance for this address?').
3. The agent selects the correct tool (`get_balance`) and executes the query, returning structured data directly to you.

## Frequently Asked Questions

**How do I check multiple MATIC balances using get_balance_multi?**
You pass a list of addresses (e.g., ['addr1', 'addr2', 'addr3']) to the `get_balance_multi` tool. It returns the current MATIC balance for every address in that batch.

**What's the difference between get_logs and get_token_tx?**
`get_logs` gets all raw event data tied to a transaction, which is messy. `get_token_tx` specifically filters those logs down to show only standard ERC-20 token transfers, making it much cleaner.

**Can I check if a smart contract call succeeded? Use get_tx_status.**
Yes. `get_tx_status` checks the final execution status of a specific contract function call. This is better than just checking the raw transaction list because it confirms successful state change.

**Which tool do I use to find out what kind of tokens are involved?**
Use `get_token_1155_tx` for multi-standard assets, `get_token_nft_tx` for unique NFTs (ERC-721), and `get_token_tx` for standard ERC-20 tokens.

**What do I need to authenticate when using any of the blockchain data query tools?**
You must provide your Polygonscan API Key. This key authorizes your AI client to pull data from the blockchain, making it mandatory for every call you execute. Don't forget this step; without it, none of the tools will run.

**When should I use get_tx_list_internal instead of get_tx_list?**
Use `get_tx_list_internal` when you need to trace funds moved *within* a contract's execution. The standard list (`get_tx_list`) only shows the top-level transactions, but internal logs give you the deeper activity.

**How do I find out what block number corresponds to a specific date?**
Use the `get_block_no_by_time` tool. You pass in the timestamp, and it returns the associated block number. This lets you map historical dates directly to the blockchain ledger structure.

**Are there limits if I use a tool like get_token_tx repeatedly?**
Yes, external API usage often has rate limits. If your agent hits a limit, it will receive an error code. You'll need to handle that specific error in your workflow or wait before trying again.

**Can I check the MATIC balance of multiple addresses at once?**
Yes! Use the `get_balance_multi` tool by providing a comma-separated list of addresses. The agent will return the balance for each one in a single response.

**How do I see the NFT transfers for a specific wallet?**
You can use the `get_token_nft_tx` tool. Just provide the wallet address, and the agent will list the ERC-721 token transfer events associated with it.

**Is it possible to retrieve the ABI of a smart contract?**
Absolutely. Use the `get_contract_abi` tool with the contract's address. If the source code is verified on Polygonscan, the agent will return the full ABI.