> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepmako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# On-Chain Tools

> 16 tools for reading blockchain state, decoding transactions, and sleuthing wallets across 8 EVM networks.

All on-chain tools use [viem](https://viem.sh) to interact with public RPC endpoints. Forensics tools additionally use Etherscan-family APIs for transaction history, internal traces, and contract source. Every tool that accepts a `chain` parameter defaults to `base` if omitted.

## `get_eth_balance`

Returns the native token balance (ETH, MATIC, AVAX, BNB, etc.) for an address.

**Parameters:** `address` (required), `chain` (optional)

```json theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "balance_wei": "5688914350696581971",
  "balance_eth": "5.688914350696581971",
  "chain": "Ethereum"
}
```

***

## `is_contract`

Checks whether an address is a smart contract, a regular EOA, or an EOA with [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) delegation.

**Parameters:** `address` (required), `chain` (optional)

```json theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "is_contract": false,
  "is_eip7702": true,
  "type": "EOA with EIP-7702 delegation (has delegated code but is still an EOA)",
  "chain": "Ethereum"
}
```

The tool uses `getBytecode()` to check for deployed code. If the bytecode starts with `0xef0100`, it's identified as an EIP-7702 delegated EOA rather than a traditional contract.

***

## `get_token_balance`

Returns an ERC-20 token balance for a wallet. Automatically resolves the token's name, symbol, and decimals.

**Parameters:** `address` (required), `token_address` (required), `chain` (optional)

```json theme={null}
{
  "address": "0x1234...",
  "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "token_name": "USD Coin",
  "token_symbol": "USDC",
  "balance_raw": "1000000000",
  "balance_formatted": "1000.0",
  "decimals": 6,
  "chain": "Ethereum"
}
```

***

## `get_token_info`

Returns metadata for an ERC-20 token contract: name, symbol, decimals, and total supply.

**Parameters:** `token_address` (required), `chain` (optional)

```json theme={null}
{
  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "name": "USD Coin",
  "symbol": "USDC",
  "decimals": 6,
  "total_supply_raw": "25000000000000",
  "total_supply_formatted": "25000000.0",
  "chain": "Ethereum"
}
```

***

## `get_gas_price`

Returns the current gas price in wei and Gwei.

**Parameters:** `chain` (optional)

```json theme={null}
{
  "gas_price_wei": "12000000",
  "gas_price_gwei": "0.0120",
  "chain": "Base"
}
```

***

## `get_block`

Returns the latest block info, including number, timestamp, transaction count, and base fee.

**Parameters:** `chain` (optional)

```json theme={null}
{
  "number": 20145832,
  "timestamp": 1718464968,
  "time_iso": "2025-06-15T20:02:48.000Z",
  "hash": "0xabc123...",
  "tx_count": 142,
  "gas_used": "15000000",
  "base_fee_gwei": "0.012000",
  "chain": "Ethereum"
}
```

***

## `get_tx_count`

Returns the transaction count (nonce) for an address — the total number of transactions sent.

**Parameters:** `address` (required), `chain` (optional)

```json theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "nonce": 1423,
  "chain": "Ethereum"
}
```

***

## `resolve_ens`

Resolves an ENS name to an Ethereum address. Always uses Ethereum mainnet regardless of the `chain` parameter.

**Parameters:** `name` (required)

```json theme={null}
{
  "name": "vitalik.eth",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "resolved": true
}
```

If the name doesn't resolve:

```json theme={null}
{
  "name": "doesntexist.eth",
  "resolved": false,
  "error": "Name not found"
}
```

***

## `get_transaction`

Retrieves transaction details by hash, including from/to, value, gas, and status.

**Parameters:** `hash` (required), `chain` (optional)

```json theme={null}
{
  "hash": "0xabc123...",
  "from": "0x1234...",
  "to": "0x5678...",
  "value_eth": "1.5",
  "gas": "21000",
  "block_number": 20145832,
  "status": "mined",
  "chain": "Ethereum"
}
```

***

## Blockchain sleuthing tools

The following tools transform Mako from a basic chain reader into a full blockchain forensics agent. When you send Mako a transaction hash, she automatically fires `get_transaction`, `get_transaction_receipt`, and `decode_tx_logs` in parallel to give you the complete picture.

***

## `get_transaction_receipt`

Returns the **actual outcome** of a transaction — not just the intent. Includes execution status, gas consumed, log count, and whether a new contract was deployed.

**Parameters:** `hash` (required), `chain` (optional)

**Auto-triggered:** Yes — fires automatically when a tx hash is detected.

```json theme={null}
{
  "hash": "0xabc123...",
  "status": "success",
  "from": "0x1234...",
  "to": "0x5678...",
  "contract_created": null,
  "gas_used": "152847",
  "effective_gas_price_gwei": "0.012345",
  "cumulative_gas_used": "4521903",
  "logs_count": 7,
  "block_number": 20145832,
  "block_hash": "0xdef456...",
  "tx_index": 42,
  "tx_type": "eip1559",
  "chain": "Ethereum"
}
```

***

## `decode_tx_logs`

Decodes event logs from a transaction receipt. Recognizes ERC-20 `Transfer` events, `Approval` events, and Uniswap V2/V3 `Swap` events. For each token transfer, resolves the token's name, symbol, and decimals automatically.

**Parameters:** `hash` (required), `chain` (optional)

**Auto-triggered:** Yes — fires automatically when a tx hash is detected.

```json theme={null}
{
  "hash": "0xabc123...",
  "total_logs": 7,
  "decoded_events": [
    {
      "event": "Transfer",
      "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "token_name": "USD Coin",
      "token_symbol": "USDC",
      "from": "0x1234...",
      "to": "0x5678...",
      "value_raw": "1500000000",
      "value_formatted": "1500.0",
      "log_index": 3
    },
    {
      "event": "Approval",
      "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "token_symbol": "USDC",
      "owner": "0x1234...",
      "spender": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
      "allowance_raw": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
      "allowance_formatted": "UNLIMITED",
      "log_index": 1
    }
  ],
  "decoded_count": 2,
  "unrecognized_count": 5,
  "chain": "Ethereum"
}
```

***

## `get_internal_transactions`

Surfaces **internal (trace-level) transactions** — contract-to-contract value transfers that are invisible in basic transaction data. Uses Etherscan-family APIs.

**Parameters:** `hash` (required), `chain` (optional)

**Auto-triggered:** Only when the user mentions keywords like "internal", "trace", "sleuth", "investigate", or "what happened".

```json theme={null}
{
  "hash": "0xabc123...",
  "internal_tx_count": 3,
  "internal_transactions": [
    {
      "from": "0xRouter...",
      "to": "0xPool...",
      "value_eth": "1.5",
      "gas_used": "45000",
      "type": "call",
      "is_error": false,
      "error_code": null,
      "trace_id": "0"
    }
  ],
  "chain": "Ethereum"
}
```

***

## `get_address_history`

Pulls the last 25 transactions for a wallet address from block explorer APIs. Returns a summary with directional flow (IN/OUT), timing, method names, and aggregate statistics.

**Parameters:** `address` (required), `chain` (optional)

**Auto-triggered:** When an address is detected and the user mentions "history", "activity", "transactions", "investigate", or "trace".

```json theme={null}
{
  "address": "0x1234...",
  "recent_tx_count": 25,
  "summary": {
    "outgoing_count": 14,
    "incoming_count": 11,
    "total_eth_out": "3.450000",
    "total_eth_in": "5.200000",
    "first_seen": "2024-01-15T08:30:00.000Z",
    "last_active": "2025-06-15T19:45:00.000Z"
  },
  "transactions": [
    {
      "hash": "0xabc...",
      "from": "0x1234...",
      "to": "0x5678...",
      "value_eth": "0.5",
      "gas_used": "21000",
      "gas_price_gwei": "0.0120",
      "timestamp": 1718480700,
      "time_iso": "2025-06-15T19:45:00.000Z",
      "block_number": 20145900,
      "is_error": false,
      "method_id": "0xa9059cbb",
      "function_name": "transfer",
      "direction": "OUT"
    }
  ],
  "chain": "Base"
}
```

***

## `read_contract`

Reads any public `view` or `pure` function on a deployed smart contract. You provide the Solidity function signature and optional arguments — Mako handles the ABI encoding and calls the chain directly.

**Parameters:** `address` (required), `function_signature` (required), `args` (optional), `chain` (optional)

Example call: `function_signature = "function getReserves() view returns (uint112, uint112, uint32)"`

```json theme={null}
{
  "address": "0xPoolAddress...",
  "function": "getReserves",
  "args": [],
  "result": ["1500000000000000000000", "3200000000", "1718480700"],
  "chain": "Base"
}
```

***

## `get_contract_source`

Fetches verified contract source code and ABI from block explorer APIs. Returns the contract name, compiler version, optimization settings, proxy status, and a parsed list of all functions and events.

**Parameters:** `address` (required), `chain` (optional)

**Auto-triggered:** When an address is detected and the user mentions "source", "code", "abi", or "verified".

```json theme={null}
{
  "address": "0xContractAddress...",
  "verified": true,
  "contract_name": "UniswapV3Pool",
  "compiler_version": "v0.7.6+commit.7338295f",
  "optimization": true,
  "license": "GPL-2.0",
  "proxy": false,
  "implementation": null,
  "functions_count": 24,
  "events_count": 8,
  "functions": [
    {
      "name": "swap",
      "state_mutability": "nonpayable",
      "inputs": "address recipient, bool zeroForOne, int256 amountSpecified, uint160 sqrtPriceLimitX96, bytes data",
      "outputs": "int256, int256"
    }
  ],
  "events": [
    {
      "name": "Swap",
      "inputs": "address sender (indexed), address recipient (indexed), int256 amount0, int256 amount1, uint160 sqrtPriceX96, uint128 liquidity, int24 tick"
    }
  ],
  "source_preview": "// SPDX-License-Identifier: GPL-2.0\npragma solidity =0.7.6;\n...",
  "chain": "Ethereum"
}
```

If the contract is not verified:

```json theme={null}
{
  "address": "0xContractAddress...",
  "verified": false,
  "chain": "Ethereum"
}
```

***

## `lookup_address`

Resolves an address to a human-readable identity. Performs reverse ENS lookup, checks against a database of known protocol addresses (Uniswap routers, major tokens, burn addresses, etc.), and returns basic profiling data.

**Parameters:** `address` (required), `chain` (optional)

**Auto-triggered:** Yes — fires automatically when any address is detected.

```json theme={null}
{
  "address": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
  "label": "Uniswap V2 Router",
  "ens_name": null,
  "is_contract": true,
  "balance_eth": "0.0",
  "tx_count": 0,
  "type": "Contract",
  "chain": "Ethereum"
}
```