# HAL Expression System
Source: https://docs.herd.eco/herd-actions/overview

HAL (Herd Action Language) - JSON/DSL scripting for blockchain transactions and data reads

# HAL Expression System

<Info>
  HAL is designed to be written and executed by AI agents through the [MCP, CLI, or SDK](/herd-mcp/introduction).
</Info>

## Overview

HAL (Herd Action Language) is a JSON scripting language for generating calldata for batches of on-chain actions and saving durable transaction records after submission. Herd does not take an opinion on the wallet or method of execution — HAL produces the calldata, and you choose how to sign and submit it.

HAL is used to create simplified write and read functions as "adapters" that can be reused across each other and also "actions" for transactions.

***

## Actions vs Adapters

These are the two types of HAL expressions we let you create in Herd. Both use the same underlying language, and are meant to be composed together through imports/exports.

**Actions** are executable batches of write functions that:

* Have a `main` function as the entry point
* Have batches and steps, where each batch can contain many "step" write function that get their calldata calculated together. They can be signed/sent through 7702, 5792, 4337, or just normal single sign transactions.
* Accept user parameters once, no matter how many steps/batches
* Can be executed in the Herd executor to produce onchain transactions
* Transactions are saved for when you need to reference or audit them
* Transactions can be simulated for security/previews

**Example**:

```json theme={null}
[
  "do",
  ["import", "herd", ["write-function"]],
  ["import", "action:abc123:v1", ["transferERC20"]],
  [
    "export",
    [
      "define",
      {
        "name": "main",
        "parameters": [
          { "name": "recipient", "type": "address" },
          { "name": "amount", "type": "uint256" }
        ],
        "body": [
          [
            "define",
            {
              "name": "batch0",
              "meta": { "isBatch": true },
              "value": [["write-function", ["transferERC20", "recipient", "amount"]]]
            }
          ]
        ]
      }
    ]
  ]
]
```

**Adapters** are reusable functions that:

* Specifically wrap a write function, read function, or code block
* For write functions, it outputs calldata which can be used in action batches for transactions or as encoded calldata for multicall/bytes fields
* For read functions, it returns the read outputs defined in the ABI
* For code blocks, it runs the typescript code to return the code outputs. We use valtown/deno for code blocks. These can be created from the import/create adapter views.
* Adapters can be imported into other adapter or actions for composable re-use.
* The exported function body must be one of: coerce (write batch), coerce wrapping read-function, or coerce wrapping code. The rest of the expression (imports, defines) can have any structure.

**Example: Write adapter** (coerce with batch call format)

```json theme={null}
[
  "do",
  ["import", "herd", ["encode-calldata", "decimals"]],
  [
    "export",
    [
      "define",
      {
        "name": "transfer",
        "parameters": [
          { "name": "to", "type": "address" },
          { "name": "amount", "type": "uint256" }
        ],
        "body": [
          "coerce",
          {
            "type": {
              "payable": "bool",
              "payableAmount": "uint256",
              "encodedCalldata": {
                "blockchain": "string",
                "contractAddress": "address",
                "functionSignature": "bytes4",
                "calldata": "bytes"
              }
            },
            "value": {
              "payable": false,
              "payableAmount": "0",
              "encodedCalldata": [
                "encode-calldata",
                {
                  "blockchain": "base",
                  "contractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
                  "functionSignature": "0xa9059cbb",
                  "args": {
                    "recipient": "to",
                    "value": [
                      "coerce",
                      { "type": "uint256", "value": ["decimals", { "value": "amount", "decimals": 18 }] }
                    ]
                  },
                  "inputAbi": [
                    "quote",
                    [
                      { "name": "recipient", "type": "address" },
                      { "name": "value", "type": "uint256" }
                    ]
                  ],
                  "functionName": "transfer"
                }
              ]
            }
          }
        ],
        "meta": {
          "description": "Transfer ERC20 tokens",
          "originContract": {
            "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "blockchain": "base",
            "contractName": "USDC",
            "functionName": "transfer"
          }
        }
      }
    ]
  ]
]
```

**Example: Read adapter** (coerce wrapping read-function)

```json theme={null}
[
  "do",
  ["import", "herd", ["read-function", "encode-calldata"]],
  [
    "export",
    [
      "define",
      {
        "name": "getBalance",
        "parameters": [{ "name": "token", "type": "address" }, { "name": "account", "type": "address" }],
        "body": [
          "coerce",
          {
            "type": { "balance": "uint256" },
            "value": [
              "read-function",
              {
                "calldata": [
                  "encode-calldata",
                  {
                    "blockchain": "ethereum",
                    "contractAddress": "token",
                    "functionSignature": "0x70a08231",
                    "args": { "account": "account" },
                    "inputAbi": ["quote", [{ "name": "account", "type": "address" }]],
                    "functionName": ["quote", "balanceOf"]
                  }
                ],
                "outputAbi": ["quote", [{ "name": "", "type": "uint256" }]]
              }
            ]
          }
        ]
      }
    ]
  ]
]
```

**Example: Code adapter** (coerce wrapping code)

```json theme={null}
[
  "do",
  ["import", "herd", ["code"]],
  [
    "export",
    [
      "define",
      {
        "name": "sumCalculator",
        "parameters": [
          { "name": "a", "type": "uint256" },
          { "name": "b", "type": "uint256" }
        ],
        "body": [
          "coerce",
          {
            "type": { "sum": "uint256" },
            "value": ["code", { "args": { "a": "a", "b": "b" }, "id": "definitionId:codeVersionId" }]
          }
        ]
      }
    ]
  ]
]
```

## HAL "Define" and User Parameters

The `define` statement creates named functions with typed parameters - this is what is exported as the action/adapter. This is the core mechanism for **simplifying complex onchain interactions** - turning a contract function with 10+ inputs into a user-friendly function with just 2-3 inputs.

**Fields**:

* **name**: Function name (used for calls and exports)
* **parameters**: Array of `{ name, type }` objects defining user inputs (can include optional `meta` field for parameter-level metadata)
* **body**: The expression to evaluate when the function is called
* **meta** (optional): Metadata for UI display and documentation (see Metadata section below)

### Metadata

The optional `meta` field on define functions provides UI hints and documentation. Metadata schemas:

**Batch metadata** (`meta` on batch `define` with `isBatch: true`):

```json theme={null}
{
  "isBatch": true,
  "batchLabel": "string (shown on the user execute button)"
}
```

**Parameter metadata** (`meta` on parameter objects):

```json theme={null}
{
  "description": "string (intent for user)",
  "placeholder": "string (default value)"
}
```

**Example with originContract and originTransaction for any defined write/read function**:

```json theme={null}
["define", {
  "name": "transfer",
  "parameters": [
    { "name": "to", "type": "address", "meta": { "label": "Recipient Address" } },
    { "name": "amount", "type": "uint256", "meta": { "decimals": 18 } }
  ],
  "body": ["..."],
  "meta": {
    "description": "Transfer 1000 USDC to recipient",
    "originContract": {
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "blockchain": "base",
      "contractName": "FiatTokenV2_2",
      "functionName": "transfer"
    },
    "originTransaction": {
      "txHash": "0x1234567890abcdef...",
      "blockchain": "base"
    }
  }
}]
```

### How Parameters Work Through Functions

When a user calls a defined function, parameters are bound in the evaluation context and can be referenced by name:

```json theme={null}
[
  "define",
  {
    "name": "transfer",
    "parameters": [
      { "name": "to", "type": "address" },
      { "name": "amount", "type": "uint256" }
    ],
    "body": [
      "encode-calldata",
      {
        "blockchain": "base",
        "contractAddress": "0x...",
        "functionSignature": "0xa9059cbb",
        "args": {
          "recipient": "to",
          "value": ["decimals", { "value": "amount", "decimals": 18 }]
        }
      }
    ]
  }
]
```

Here, `"to"` and `"amount"` in the body reference the parameter values passed by the user. When you reference another define/import, only its parameters are used. And when evaluating, the parameters top level are passed once and then down through any referenced functions as well.

### The Key Value of HAL: Simplifying Complex Contract Calls

A key value of HAL is turning complex contract functions into simple user-facing adapters. For example, a contract's `register` function might require 10 arguments:

**Complex contract function** (10 inputs):

* `name`, `owner`, `duration`, `resolver`, `data[]`, `coinTypes[]`, `reverseRecord`, `signature`, `signatureExpiry`, `expires`

**Simplified HAL adapter** (2 inputs):

```json theme={null}
["define", {
  "name": "simpleRegister",
  "parameters": [
    { "name": "name", "type": "string" },
    { "name": "years", "type": "int256" }
  ],
  "body": "<expression that computes all 10 args from just name and years>"
}]
```

## Setting Values in a HAL Expression

Any variable can be set to a value with hardcoded values or function references (from defines and imports). The most common pattern you will see in HAL is wrapping a function call with a `getPath` and then a `coerce`. You can create a parameter and reference it in the value too (if in a define).

```json theme={null}
["do",
  ["import", "herd", ["decimals", "encode-calldata"]],
  ["import", "action:abc123:v1", ["calculate_years_to_seconds"]],

  ["define", {
    "name": "simpleRegister",
    "parameters": [{ "name": "years", "type": "int256" }],
    "body": [
      "let", { "duration": ["calculate_years_to_seconds", "years"] },
      ["encode-calldata", { "...": "...", "duration": ["getPath", { "object": "duration", "path": ["seconds"] }] }]
    ]
  }]
]
```

In this example:

* `"duration"` is set by calling the imported function `calculate_years_to_seconds` with the user parameter `"years"`
* The result is then extracted using `getPath` to get the `"seconds"` field from the `"duration"` object

In the Herd editor, we make dropdown suggestions that auto create/set parameters, wrap functions/outputs, and check types.

## Standard Library Functions

HAL provides standard library functions imported from the `herd`, `object`, and `math` modules. Import them using:

```json theme={null}
["import", "herd", ["function-name"]]
["import", "object", ["getPath"]]
["import", "math", ["add", "eq", "lt", "gt", "lte", "gte"]]
```

### Math Module (Arithmetic and Comparison)

Import from `math`: `["import", "math", ["add", "sub", "mul", "div", "pow", "eq", "neq", "lt", "gt", "lte", "gte"]]`

**Arithmetic**: `add`, `sub`, `mul`, `div`, `pow` — operate on numeric values (bigint, number, or numeric strings).

**Comparison** (return `bool`):

* `eq(a, b)` — equality (numeric or primitive `===`)
* `neq(a, b)` — inequality (negation of eq)
* `lt(a, b)` — less than
* `gt(a, b)` — greater than
* `lte(a, b)` — less than or equal
* `gte(a, b)` — greater than or equal

**Example** (conditional with gt):

```json theme={null}
["do",
  ["import", "math", ["gt"]],
  ["define", { "name": "x", "value": 42 }],
  ["if", ["gt", "x", 0], "positive", "non-positive"]
]
```

### write-function

Executes a state-changing contract call. **Only used within batch steps in the `main` function of actions.**

```json theme={null}
["write-function", {
  "encodedCalldata": "<EncodeCalldataResult>",
  "payable": "<boolean>",
  "payableAmount": "<uint256>"
}]
```

**Input**: Accepts batch call data format from user-defined write adapter functions:

* `encodedCalldata`: Result from `encode-calldata`
* `payable`: boolean
* `payableAmount`: uint256 (in wei)

**Returns**: `{ blockchain, toAddress, functionSignature, transactionHash, transactionStatus }`

This is the only function that submits/takes a transaction hash.

### Batch Call Data Format (Use for Write Function Adapters)

User-defined write functions return a standardized format for use in action batches:

```json theme={null}
{
  "payable": false,
  "payableAmount": "0",
  "encodedCalldata": {
    "blockchain": "base",
    "contractAddress": "0x...",
    "functionSignature": "0x...",
    "calldata": "0x..."
  }
}
```

This format is consumed directly by `write-function` in batch steps. This format does NOT produce a transaction, only the write-function does.

### read-function

Executes a read-only contract call (view/pure functions).

```json theme={null}
["coerce", {
  "type": { "balance": "uint256" },
  "value": ["read-function", {
    "calldata": [
      "encode-calldata",
      {
        "blockchain": "base",
        "contractAddress": "0x...",
        "functionSignature": "0x...",
        "args": { "...": "..." },
        "inputAbi": ["quote", ["<AbiParameter[]>"]],
        "functionName": "transfer"
      }
    ],
    "outputAbi": ["quote", ["<AbiParameter[]>"]]
  }]
}]
```

**Input**: `{ calldata: EncodeCalldataExpression, outputAbi: ["quote", AbiParameter[]] }`

**Returns**: Object with decoded output values keyed by ABI output names (e.g., `{ balance: "1000000" }`)

### encode-calldata

Encodes function arguments into calldata for contract calls. Used internally by read/write functions.

**Returns**: `{ blockchain, contractAddress, functionSignature, calldata }`

### encode-parameters

Encodes function parameters using ABI encoding. Similar to `encode-calldata` but only encodes the parameters without blockchain context or function signature.

**Input**: `{ inputs: { [paramName]: value }, inputAbi: ["quote", AbiParameter[]] }`

**Returns**: `bytes` (hex string like `"0x..."`)

**Example**:

```json theme={null}
["encode-parameters", {
  "inputs": { "to": "0x1234567890123456789012345678901234567890", "amount": "1000" },
  "inputAbi": ["quote", [
    { "name": "to", "type": "address" },
    { "name": "amount", "type": "uint256" }
  ]]
}]
```

### code

Executes a TypeScript code block. Code blocks are created/managed in the Code Blocks view and run on Valtown/Deno.

```json theme={null}
[
  "coerce",
  {
    "type": { "result": "string" },
    "value": ["code", { "args": { "inputArg": "value" }, "id": "definitionId:codeVersionId" }]
  }
]
```

We always create one auto-synced adapter for each code block, which can't be edited but is kept up to date by each saved/publish of the underlying code block. You can test the code block in the code editor too. For adapters that aren't auto-synced you will need to update the "import" of the code block each time you update the code.

Keep in mind:

* `id` format: `<definitionId>:<codeVersionId>` - combines the definition UUID with the specific code version
* Each code block has a single auto-synced adapter that updates when the code is published
* Input/output args are typed using HAL types

### getPath

Gets a value at a nested path within an object. Imported from the `object` module.

**Expression format**:

```json theme={null}
["import", "object", ["getPath"]]
["getPath", { "object": "<result>", "path": ["field", "nested"] }]
```

**Input**: `{ object: any, path: string[] }`

**Returns**: Value at the specified path

### coerce

Runtime type coercion and validation. Wraps a value to declare its expected type for the type inference system.

```json theme={null}
["coerce", { "type": { "sum": "uint256" }, "value": "<expression>" }]
```

Used to declare return types for type inference. Commonly used with `code`, `read-function`, `decimals`, and write adapters returning batch call data (see examples above).

**Available scalar types for `"type"`**: `uint256`, `int256`, `address`, `bool`, `string`, `bytes`, `float64`, and fixed-size variants (`uint8`…`uint256`, `bytes1`…`bytes32`).

Use **`float64`** when the adapter returns a decimal value — for example, a USD price computed by dividing a raw 1e18-scaled on-chain integer by `pow(10, 18)`. HAL's `div` is float division and produces a decimal result; coercing to `float64` preserves it:

```json theme={null}
["coerce", {
  "type": "float64",
  "value": ["div",
    ["getPath", { "path": ["quote", ["arg0"]], "object": ["read-function", { ... }] }],
    ["pow", 10, 18]
  ]
}]
```

### decimals

Multiplies a value by 10^decimals. Converts human-readable values to raw integers (e.g., for wei).

```json theme={null}
[
  "coerce",
  {
    "type": "uint256",
    "value": ["decimals", { "value": "1.5", "decimals": 18 }]
  }
]
```

**Input**: `{ value: uint256|int256|float64, decimals: uint8 }`

**Returns**: String representation of the scaled integer

### user-wallet

Returns the current user's wallet address. No arguments required.

**Returns**: `address` (e.g., `"0x1234..."`)

### swap

<Warning>
  This function should ONLY be used within action batches, not within adapters or values.
</Warning>

Fetches swap quote and execute data from the **0x API**. The approval step is optional — it is only required when the wallet has not already approved the spender. Use `swapSteps.approval.approvalRequired` to conditionally include the approval step in a batch.

`sellTokenAmount` is the actual amount, not the raw bigint. If you're passing values from a read function or something onchain into this field, toggle `divideDecimals` on so we can automatically convert using the token's decimals.

**Input**: `{ blockchain, sellTokenAddress, sellTokenAmount, buyTokenAddress, walletAddress, divideDecimals }`

**Returns**: `{ swapSteps: { approval: { approvalRequired: boolean, ... }, swap: EncodeCalldataResult }, quote: ... }`

**Example** (approve-then-execute with conditional approval):

```json theme={null}
[
  "do",
  ["import", "herd", ["swap", "write-function", "user-wallet"]],
  ["import", "object", ["getPath"]],
  [
    "define",
    {
      "name": "main",
      "parameters": [],
      "body": [
        [
          "define",
          {
            "name": "batch0",
            "meta": { "isBatch": true, "batchLabel": "Swap Tokens" },
            "value": [
              [
                "if",
                [
                  "getPath",
                  {
                    "object": [
                      "swap",
                      {
                        "blockchain": "base",
                        "sellTokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
                        "sellTokenAmount": 1,
                        "buyTokenAddress": "0x0000000000000000000000000000000000000000",
                        "walletAddress": ["user-wallet"],
                        "divideDecimals": false
                      }
                    ],
                    "path": ["quote", ["swapSteps", "approval", "approvalRequired"]]
                  }
                ],
                [
                  "write-function",
                  [
                    "getPath",
                    {
                      "object": [
                        "swap",
                        {
                          "blockchain": "base",
                          "sellTokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
                          "sellTokenAmount": 1,
                          "buyTokenAddress": "0x0000000000000000000000000000000000000000",
                          "walletAddress": ["user-wallet"],
                          "divideDecimals": false
                        }
                      ],
                      "path": ["quote", ["swapSteps", "approval"]]
                    }
                  ]
                ],
                null
              ],
              [
                "write-function",
                [
                  "getPath",
                  {
                    "object": [
                      "swap",
                      {
                        "blockchain": "base",
                        "sellTokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
                        "sellTokenAmount": 1,
                        "buyTokenAddress": "0x0000000000000000000000000000000000000000",
                        "walletAddress": ["user-wallet"],
                        "divideDecimals": false
                      }
                    ],
                    "path": ["quote", ["swapSteps", "swap"]]
                  }
                ]
              ]
            ]
          }
        ]
      ]
    }
  ]
]
```

### lookup-transaction-function

Retrieves function inputs or outputs from a committed transaction trace. **Only used in step outputs within `main`** to extract values from previous transaction results.

```json theme={null}
[
  "lookup-transaction-function",
  {
    "blockchain": "base",
    "contractAddress": "0x...",
    "functionSignature": "0xa9059cbb",
    "transactionHash": "transactionHash",
    "direction": "outputs",
    "abi": ["quote", [{ "name": "success", "type": "bool" }]]
  }
]
```

**Input**:

* `direction`: `"inputs"` or `"outputs"`
* `abi`: Quoted array of ABI parameters for decoding

**Returns**: Object with decoded values keyed by ABI param names

### lookup-transaction-event

Retrieves event outputs from a committed transaction's logs. **Only used in step outputs within `main`** to extract event data from previous transactions.

```json theme={null}
[
  "lookup-transaction-event",
  {
    "blockchain": "base",
    "contractAddress": "0x...",
    "eventSignature": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
    "transactionHash": "transactionHash",
    "outputAbi": [
      "quote",
      [
        { "name": "from", "type": "address", "indexed": true },
        { "name": "to", "type": "address", "indexed": true },
        { "name": "value", "type": "uint256", "indexed": false }
      ]
    ]
  }
]
```

**Returns**: Object with decoded event data keyed by input names

***

## Import/Export and Versioning

### Import Syntax

Import functions from other adapters/actions or stdlib modules:

```json theme={null}
["import", "herd", ["write-function", "encode-calldata"]]
["import", "action:actionId:versionId", ["functionName"]]
["import", "action:actionId:versionId", [["exportName", "localAlias"]]]
```

**Action import format**: `action:<actionId>:<versionId>`

* `actionId`: UUID of the action/adapter
* `versionId`: UUID of the specific version to import

### Export Syntax

Export functions for use by other expressions:

```json theme={null}
["export", ["define", { "name": "myFunction", "parameters": ["..."], "body": ["..."] }]]
```

Each action/adapter only exports ONE defined function right now. This keeps expressions simpler and more composable. For actions, that function is "main" always. For adapters that can be any defined "write" batch call data, read-function, or code block.

### Versioning

**Critical**: When you publish a new version of an adapter, any actions/adapters that import it will continue using the **old version** until updated.

**To update imports**:

1. Importers must explicitly update the `versionId` in their import statement
2. The HAL editor shows stale import warnings when newer versions are available
3. Update the import to use the new version ID: `action:actionId:newVersionId`

This ensures stability - consumers control when they adopt breaking changes.

## Evaluation and Operation Logs (Oplogs)

You can test any HAL expression by clicking "Test" mode in the action editor, entering user parameters, and clicking run. The evaluation produces an **operation log (oplog)** - a detailed trace of every function call during execution.

### Oplog Structure

Each entry represents a single function call:

* **operationId**: Unique ID for this operation
* **functionName**: Name of the function called (e.g., `code`, `read-function`, `getPath`, user-defined functions)
* **status**: `"success"` or `"error"`
* **timestamp/timestampIso**: When the operation executed
* **args**: Arguments passed to the function
* **result**: Return value (or error message if failed)

### Example Oplog Walkthrough

Here's a condensed example showing how operations chain together:

```json theme={null}
{
  "executionStatus": "completed",
  "entries": [
    {
      "functionName": "code",
      "args": [{ "id": "...:...", "args": { "years": "5n" } }],
      "result": { "seconds": "157680000" }
    },
    {
      "functionName": "calculate_years_to_seconds",
      "args": ["5n"],
      "result": { "seconds": "157680000n" }
    },
    {
      "functionName": "getPath",
      "args": [{ "path": ["seconds"], "object": { "seconds": "157680000n" } }],
      "result": "157680000n"
    },
    {
      "functionName": "encode-calldata",
      "args": [{ "blockchain": "base", "contractAddress": "0x508...", "functionSignature": "0x50e9a715", "args": { "name": "ilemi", "duration": "157680000n" } }],
      "result": { "blockchain": "base", "contractAddress": "0x508...", "calldata": "0x50e9a715..." }
    },
    {
      "functionName": "read-function",
      "args": [{ "calldata": { "blockchain": "base", "contractAddress": "0x508...", "calldata": "0x50e9a715..." } }],
      "result": { "0": { "base": "4995440843040000n", "premium": "0n" } }
    },
    {
      "functionName": "simpleRegister",
      "args": ["ilemi", "5n"],
      "result": { "payable": true, "payableAmount": "4995440843040000n", "encodedCalldata": { "...": "..." } }
    }
  ],
  "finalResult": { "payable": true, "payableAmount": "4995440843040000n", "encodedCalldata": { "...": "..." } }
}
```

**What this shows**:

1. `code` executes a TypeScript code block to convert years to seconds
2. `calculate_years_to_seconds` is the user-defined wrapper function
3. `getPath` extracts the `seconds` field from the result
4. `encode-calldata` prepares the contract call arguments
5. `read-function` calls the contract to get pricing info
6. `simpleRegister` is the final user-defined adapter that returns batch call data

### Using Oplogs for Debugging

* **Trace execution flow**: See exactly which functions run and in what order and check what each function receives and returns
* **Identify failures**: Failed operations show `"status": "error"` with error messages


# Herd Explorer
Source: https://docs.herd.eco/herd-app/explorer

Learn how to use the Herd Explorer and Sage agent

<Info>
  All data from the Herd Explorer is accessible in the [Herd MCP](/herd-mcp/introduction), which specializes in looking up relationships and context behind contracts, transactions, and wallets.
</Info>

## Learning the Basics

The Herd app has a [built in explorer](https://herd.eco/explorer) with an agent (Sage) who exists on every page to help you find and understand the chain. You can watch the video below for an overview of memory and the overall app.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

If you haven't used a block explorer like [Etherscan](https://etherscan.io) before, explorers in crypto are used to investigate smart contracts, wallets, and transactions. Our explorer uses an LLM to interpret each of these objects, to provide richer context alongside all the data.

<Info>The explorer and chat are NOT made for analytics, do not try and ask it Dune style analytical questions. It's targeted at understanding the logic and relationships between onchain objects.</Info>

## Ask Agent

You can utilize our agent to understand anything in Herd, by opening the chat in the bottom right. It will allow you tag context from the page, as well as add any contracts/transactions/wallets you want manually. This agent is also fully accessible via MCP for free.

## Explorer Pages

There are four main pages on the explorer, each focused on helping you quickly interpret and find onchain relationships. If you have any issues or feature requests, you can bring them up in [the Discord](https://discord.gg/NsfPWZZuKU).

### Contract Page

The contract page is a bit different from how other block explorers work:

* We start with a summary page, which is an LLM interpretation of all contract functions and events. If it's a token, it will also show top holders.
* If it's proxy, we show the underlying implementation directly. There is upgrade history in the dropdown in the top left so you can see all past versions

<Frame>
  <img alt="Herd contract summary page" />
</Frame>

<Note>Herd works with verified and unverified Solidity and Vyper contracts (using Etherscan for verified, and Heimdall for unverified).</Note>

Next up we have a "related contracts" tab, which shows all the top contracts either calling or being called by the current address (as well as which functions are being called). This helps you quickly understand protocol relationships and key transaction drivers.

<Frame>
  <img alt="Herd contract related tab" />
</Frame>

Then we have functions and events tabs, each with LLM summaries of what they handle as well as basic 1 day stats.

<Frame>
  <img alt="Herd functions tab page" />
</Frame>

Each function/event comes with it's own detailed page. It covers inputs/outputs, linked events, and shows most recent transactions calling this function (directly or indirectly). You can also copy just the individual function/event abi from here too.

<Frame>
  <img alt="Herd functions tab page" />
</Frame>

Functions can also be executed directly on the page, with an LLM that helps you prepare inputs and simulate the transactions. You can also paste in a previous transaction calling this function to pre-fill the input values directly.

<Frame>
  <img alt="Herd function execution page" />
</Frame>

There is a code tab as well, which lets you explore the proxy and contract code together (and search across them). The abi can be copied from here as well.

<Frame>
  <img alt="Herd code page" />
</Frame>

### Protocol Page

Many contracts will have protocol labels, such as "Circle", "Zora", "Uniswap", etc. These can be clicked to take you to the protocol page, showing main links to the protocol and also a chronological ordering of their deployed contracts.

<Frame>
  <img alt="Herd function execution page" />
</Frame>

If you notice any wrong or missing labels, you can message the team (on [Twitter](https://x.com/herd_eco) or [Discord](https://discord.gg/NsfPWZZuKU)).

### Transaction Page

We show an in depth summary with traces of each transaction (this works for any simulations you do on Herd as well).

<Frame>
  <img alt="Herd transaction page" />
</Frame>

Each trace can be expanded so that you can view the summary, decoded data, and raw information together.

<Frame>
  <img alt="Herd transaction expand page" />
</Frame>

### Wallet Page

On the wallet page, we mainly showcase the top contracts they have called as well as top contracts they have deployed.

<Frame>
  <img alt="Herd wallet page" />
</Frame>


# Supported Blockchains
Source: https://docs.herd.eco/herd-app/supported-chains

Chains supported by Herd

The Explorer currently covers:

* Ethereum Mainnet
* Base

<Note>If you would like to see a different chain supported on Herd, you can [reach out to me](https://x.com/andrewhong5297) or ask in [the Discord](https://discord.gg/NsfPWZZuKU).</Note>


# Herd Visualizer
Source: https://docs.herd.eco/herd-app/visualizer

Find relationships across contracts and wallets with one click

<Note>
  <p>You can start the visualizer from any contract or function page (see the purple button at the top).</p>
  <p>Please contact the team ([@andrewhong5297](https://x.com/andrewhong5297)) if you have any issues, this feature is still in beta and may run into bugs and long loading times.</p>
</Note>

The visualizer takes any contract and finds recent transactions for all of its functions, and then builds out a relationship call and variable graph.

Let's visualize the [ENS register for Basenames (on Base)](https://herd.eco/base/visualizer?contracts=0xa7d2607c6bd39ae9521e514026cbb078405ab322):

<Frame>
  <img alt="Herd visualizer interface" />
</Frame>

Each contract, function, and variable can have relationships drawn (edges). These are what each colored edge means:

* **Light Blue:** variable referencing a contract address
* **Dark Blue:** variable referencing a wallet address
* **Red:** function that creates another contract (deploys)
* **Light Green:** write function calling another function
* **Dark Green:** read function calling another function

## Exploring and Expanding the Graph

<Note>
  <p>The node headers and each function/variable can be clicked to give you more details and link you to the explorer pages. You can also click on any function edge to see the transactions associated with it.</p>
  <p>You can also use the sidebar to help you find where a contract/wallet is by hovering or clicking it there.</p>
</Note>

When you hover/click on a node, you will see the option to "Load All Functions" or "Load All Variables" if it has not already been done for that function. The contracts you choose to load functions from become "primary" contracts in the graph, and are given a purple outline. These are saved when you refresh or share the page.

<Info>We currently have set limits around function expansion if 50 contracts exist already in the graph. This is for performance purposes. You can reach out to the team if this is really blocking you on something.</Info>

<Frame>
  <img alt="Herd visualizer loading" />
</Frame>

Loading functions will look for transactions for every write function on the contract address. If a function you're looking for is missing, it means that it either hasn't been called yet or that function doesn't call any other contracts.

Loading variables will look for any addresses that appear in any variable (read function with no inputs) on that contract.

## Visualizer Settings

In the top right of the visualizer, you'll find four buttons for key graph settings:

* "Collapse/Expand": Collapsing will remove all functions/variables handles, showing just one line for every kind of relationship between nodes for a given node.
* "Functions": This toggles if you want to show the function relations (green and red lines) or not.
* "Variables": This toggles if you want to show the variable relations (blue lines) or not.


# Getting Started
Source: https://docs.herd.eco/herd-mcp/introduction

Build on top of crypto with agents powered by Herd's institutional-grade infrastructure. We handle the full operational lifecycle from due diligence to execution and monitoring.

# Herd Agent

Herd connects AI agents to on-chain data and actions through multiple interfaces. Query contracts, decode transactions, analyze wallets, build/simulate actions, and query onchain data — all using natural language.

The MCP server, CLI, and TypeScript SDK all expose the same set of tools and capabilities.

## MCP Install

Add Herd as an MCP server to your AI coding client.

```bash theme={null}
claude mcp add --transport http herd-mcp https://mcp.herd.eco/v1
```

* **Claude Code**: `claude mcp add --transport http herd-mcp https://mcp.herd.eco/v1`
* **Cursor**: Add via Settings → MCP
* **Codex**: Add via MCP configuration

### Authenticate

1. Open **/mcp** in your IDE (Claude, Cursor, or Codex)
2. Find **herd-mcp** in the MCP list
3. Click **Authenticate** to complete the OAuth flow
4. Sign in with your Herd account at [herd.eco](https://herd.eco)

### Manage

```bash theme={null}
# List configured MCPs (Claude Code)
claude mcp list

# Remove
claude mcp remove herd-mcp
```

## CLI Install

Install the [Herd CLI](https://github.com/herd-labs/herd-cli) for terminal-based access to all Herd tools.

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/herd-labs/herd-cli/main/install.sh | bash
```

### Authenticate

```bash theme={null}
herd login
```

This opens a browser for OAuth authentication. On successful login, the CLI automatically provisions an API key stored at `~/.herd/credentials.json`. This API key can also be used with the TypeScript SDK.

### Commands

| Group            | Commands                                                                       | Description                                      |
| ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------------ |
| `herd contract`  | `metadata`, `deployed`, `roles`, `diff`                                        | Contract info, deployments, roles, version diffs |
| `herd tx`        | `query`, `latest`                                                              | Transaction inspection, recent activity          |
| `herd wallet`    | `overview`, `tokens`, `transactions`                                           | Wallet profiling, token activity, tx history     |
| `herd bookmarks` | `list`, `update`                                                               | Manage saved items                               |
| `herd hal`       | `create`, `get`, `search`, `update`, `delete`, `simulate`, `simulate-existing` | HAL actions, adapters, code blocks, collections  |
| `herd docs`      | `read`                                                                         | Read HAL and platform documentation              |

### Output Formats

```bash theme={null}
--format pretty   # Indented JSON (default for TTY)
--format json     # Compact JSON for piping
--format table    # ASCII table for lists
```

## SDK Install

Install the [Herd TypeScript SDK](https://www.npmjs.com/package/@herd-labs/sdk) to integrate Herd tools into your applications.

```bash theme={null}
npm install @herd-labs/sdk
```

### Authentication

Use an API key generated via the CLI (`herd login`) or set the `HERD_API_KEY` environment variable.

```typescript theme={null}
import { HerdSDK } from "@herd-labs/sdk";

const herd = new HerdSDK({
  apiKey: process.env.HERD_API_KEY,
});
```

The SDK provides programmatic access to all the same tools available through the MCP server and CLI.

***

## Capabilities

<CardGroup>
  <Card title="Contracts" icon="file-code">
    Fetch metadata, search source code, compare proxy implementations, inspect role topology
  </Card>

  <Card title="Transactions" icon="arrow-right-arrow-left">
    Decode traces, parse logs, track balance changes
  </Card>

  <Card title="Wallets" icon="wallet">
    Detect wallet types, view holdings, list deployments
  </Card>

  <Card title="HAL" icon="code">
    Create and simulate actions, adapters, code blocks, and collections
  </Card>

  <Card title="Bookmarks" icon="bookmark">
    Save and manage wallets, contracts, and transactions
  </Card>
</CardGroup>

## Supported Networks

| Network  | Status    |
| -------- | --------- |
| Ethereum | Supported |
| Base     | Supported |

## Tools Quick Reference

### Contract Tools

| Tool                                                   | Use For                                         |
| ------------------------------------------------------ | ----------------------------------------------- |
| [Contract Metadata](/herd-mcp/tools/contract-metadata) | Contract info, ABI, proxy history, token data   |
| [Code Analysis](/herd-mcp/tools/code-analysis)         | Search contract source code with regex          |
| [Diff Versions](/herd-mcp/tools/diff-versions)         | Compare implementation version upgrades         |
| [Role Topology](/herd-mcp/tools/role-topology)         | Inspect role/permission structure of a contract |

### Transaction Tools

| Tool                                                         | Use For                                   |
| ------------------------------------------------------------ | ----------------------------------------- |
| [Query Transaction](/herd-mcp/tools/query-transaction)       | Decoded traces, logs, balances, transfers |
| [Latest Transactions](/herd-mcp/tools/latest-transactions)   | Recent function/event calls with filters  |
| [Transaction Activity](/herd-mcp/tools/transaction-activity) | Address tx history with filters           |

### Wallet Tools

| Tool                                                     | Use For                                     |
| -------------------------------------------------------- | ------------------------------------------- |
| [Wallet Overview](/herd-mcp/tools/wallet-overview)       | Wallet type, balances, tx count, signers    |
| [Token Activity](/herd-mcp/tools/token-activity)         | Token transfer history for a given position |
| [Deployed Contracts](/herd-mcp/tools/deployed-contracts) | Contracts deployed by an address            |

### Bookmark Tools

| Tool                                   | Use For                             |
| -------------------------------------- | ----------------------------------- |
| [Bookmarks](/herd-mcp/tools/bookmarks) | List, add, edit, remove saved items |

### HAL Tools

| Tool                                                       | Use For                                                 |
| ---------------------------------------------------------- | ------------------------------------------------------- |
| [Actions & Adapters](/herd-mcp/tools/hal-actions-adapters) | Create, search, update, delete HAL actions and adapters |
| [Code Blocks](/herd-mcp/tools/hal-code-blocks)             | Create, update, execute TypeScript code blocks          |
| [Collections](/herd-mcp/tools/hal-collections)             | Organize actions and adapters into collections          |
| [Evaluation](/herd-mcp/tools/hal-evaluation)               | Simulate and test HAL expressions                       |
| [Documentation](/herd-mcp/tools/documentation)             | Read HAL and platform docs                              |


# Bookmarks
Source: https://docs.herd.eco/herd-mcp/tools/bookmarks

Get and manage your saved wallets, contracts, and transactions

# Bookmarks

Two tools for reading and managing the current user's bookmarks — saved wallets, contracts, and transactions.

## Get Bookmarks

Fetches all bookmarks for the authenticated user, grouped by type.

### Returns

* **Contracts** — Address, blockchain, contract name, and label
* **Transactions** — Hash, blockchain, and label
* **Wallets** — Address and label

### Example Queries

```
What wallets do I have bookmarked?
```

```
Show me my saved contracts
```

```
List all my bookmarks
```

### Parameters

No input required. Returns bookmarks for the authenticated user.

### Sample Output

```
Bookmarks
=========

Contracts (2):
- USDC (ethereum) — 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
- Uniswap V3 Router (base) — 0x2626664c2603336e57b271c5c0b26f421741e481

Transactions (1):
- Aave Deposit — 0xabc123...

Wallets (1):
- My Hot Wallet — 0xdef456...
```

***

## Update Bookmarks

Adds, edits, or removes a single bookmark.

### Operations

| Operation | Description                                                     |
| --------- | --------------------------------------------------------------- |
| `add`     | Save a new bookmark; auto-generates a label if none is provided |
| `edit`    | Update the label on an existing bookmark (`null` to clear)      |
| `remove`  | Delete a bookmark                                               |

### Parameters

| Parameter    | Required    | Description                                                                               |
| ------------ | ----------- | ----------------------------------------------------------------------------------------- |
| `operation`  | Yes         | `add`, `edit`, or `remove`                                                                |
| `objectType` | Yes         | `wallet`, `contract`, or `transaction`                                                    |
| `objectId`   | Yes         | Contract address, transaction hash, or wallet address (`0x...`)                           |
| `blockchain` | Conditional | Required for `contract` and `transaction`; omit for `wallet`. `ethereum` or `base`        |
| `userLabel`  | No          | Custom label. For `add`: omit to auto-generate. For `edit`: new label, or `null` to clear |

### Example Queries

```
Bookmark vitalik.eth for me
```

```
Save contract 0x... on Base as "My Token"
```

```
Rename my USDC bookmark to "Circle Stablecoin"
```

```
Remove the bookmark for transaction 0x...
```

***

## Bookmark Types

| Type          | `objectId`       | `blockchain` required? |
| ------------- | ---------------- | ---------------------- |
| `wallet`      | Wallet address   | No                     |
| `contract`    | Contract address | Yes                    |
| `transaction` | Transaction hash | Yes                    |

## Tips

<Tip>
  When adding with no label, a default is generated automatically — e.g. ENS name for wallets, contract name for contracts.
</Tip>

<Tip>
  Use `getBookmarksTool` first to check existing bookmarks before adding duplicates.
</Tip>

## Related Tools

* **View wallet details** → `getWalletOverviewTool`
* **View contract details** → `contractMetadataTool`
* **View transaction details** → `queryTransactionTool`

## Next Steps

<CardGroup>
  <Card title="Wallet Overview" icon="wallet" href="/herd-mcp/tools/wallet-overview">
    Profile any wallet address
  </Card>

  <Card title="Contract Metadata" icon="file-code" href="/herd-mcp/tools/contract-metadata">
    Fetch contract details
  </Card>
</CardGroup>


# Code Analysis
Source: https://docs.herd.eco/herd-mcp/tools/code-analysis

Search contract source code with AI-generated regex patterns

# Code Analysis

Searches verified contract source code using AI-generated regex patterns.

## Capabilities

* Search by natural language query
* Find functions, patterns, or behaviors
* Return filtered results or full code

## Example Queries

```
Find all functions that can transfer tokens in the USDC contract
```

```
Show me the access control logic in this contract
```

```
What modifiers does this contract use?
```

## Parameters

| Parameter           | Required | Description                                                  |
| ------------------- | -------- | ------------------------------------------------------------ |
| `query`             | Yes      | What you're searching for                                    |
| `contractAddresses` | Yes      | Array of contract addresses to search                        |
| `includeProxies`    | No       | Search proxy code instead of implementation (default: false) |
| `returnAllCode`     | No       | Return all code without filtering (default: false)           |

## Usage Patterns

### Finding Functions

```
Find all mint functions in contract 0x...
```

### Access Control

```
How is admin access controlled in this contract?
```

Searches for: `onlyOwner` modifiers, role-based patterns, admin state variables

### Security Patterns

```
Are there any functions that can pause this contract?
```

Finds: pause/unpause functions, emergency stops, circuit breakers

## Practical Examples

### Example 1: Finding Fee Logic

**You:** "Show me how fees are calculated in the Uniswap V3 swap function"

**Result:**

```solidity theme={null}
// From SwapRouter.sol
function exactInputSingle(ExactInputSingleParams calldata params)
    external
    payable
    override
    returns (uint256 amountOut)
{
    amountOut = exactInputInternal(
        params.amountIn,
        params.recipient,
        params.sqrtPriceLimitX96,
        SwapCallbackData({
            path: abi.encodePacked(params.tokenIn, params.fee, params.tokenOut),
            payer: msg.sender
        })
    );
    // Fee is encoded in the path...
}
```

### Example 2: Checking for Dangerous Patterns

**You:** "Does this contract have any selfdestruct or delegatecall?"

**Result:**

```
Found 0 matches for 'selfdestruct'
Found 1 match for 'delegatecall':

Line 245: (bool success, ) = implementation.delegatecall(data);
Context: This is the standard proxy pattern delegatecall,
which is expected and safe in this context.
```

### Example 3: Understanding State Variables

**You:** "What are the main state variables in this contract?"

**Result:**

```solidity theme={null}
// Storage variables found:
mapping(address => uint256) private _balances;
mapping(address => mapping(address => uint256)) private _allowances;
uint256 private _totalSupply;
string private _name;
string private _symbol;
address public owner;
bool public paused;
```

## Full Code Retrieval

Use `returnAllCode: true` to get complete source code for:

* Full code review
* Context around matches
* Cross-function patterns

## Multi-Contract Search

Search across multiple contracts simultaneously:

```
Find how 'swap' is implemented across these DEX contracts: [addresses]
```

## Tips

<Tip>
  Be specific: "find the withdraw function" beats "find withdrawal logic"
</Tip>

<Tip>
  Search by behavior: "functions that can move user funds" captures more than "find transfer"
</Tip>

## Common Search Queries

| What You Want   | How to Ask                                          |
| --------------- | --------------------------------------------------- |
| Admin functions | "Find all functions with onlyOwner or admin access" |
| Token transfers | "Show me functions that transfer or move tokens"    |
| External calls  | "Find all external contract calls"                  |
| Events          | "What events does this contract emit?"              |
| Modifiers       | "List all modifiers in this contract"               |
| Constructor     | "Show me the constructor and initialization logic"  |
| Upgrade logic   | "How does this contract handle upgrades?"           |

## Limitations

<Warning>
  **Only works on verified contracts.** Unverified contracts don't have source code available.
</Warning>

<Warning>
  **Large contracts may be truncated.** Very large codebases might not return complete results in a single query.
</Warning>

## Combining with Other Tools

1. **Get overview first** → `contractMetadataTool`
2. **Search specific code** → `regexCodeAnalysisTool`
3. **Check how it's used** → `getLatestTransactionsTool`

## Next Steps

<CardGroup>
  <Card title="Contract Metadata" icon="file-code" href="/herd-mcp/tools/contract-metadata">
    Get contract overview first
  </Card>

  <Card title="Version Diffs" icon="code-compare" href="/herd-mcp/tools/diff-versions">
    Compare contract versions
  </Card>
</CardGroup>


# Contract Metadata
Source: https://docs.herd.eco/herd-mcp/tools/contract-metadata

Fetch contract info, ABI, deployment history, and token data

# Contract Metadata

Returns contract information including ABI, proxy history, and token data.

## Returns

* **Basic Info** - Contract name, compiler version, verification status
* **ABI** - Complete Application Binary Interface with function signatures
* **Proxy Information** - Implementation addresses for upgradeable contracts
* **Deployment History** - When and how the contract was deployed
* **Token Details** - If it's a token: price, volume, market cap, holders (via CoinGecko)

## Example Queries

```
What is the contract at 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48?
```

```
Give me an overview of the Uniswap V3 Router contract
```

```
What functions does AAVE's lending pool have?
```

## Parameters

| Parameter         | Required | Description                    |
| ----------------- | -------- | ------------------------------ |
| `contractAddress` | Yes      | The contract address (0x...)   |
| `blockchain`      | No       | `ethereum` (default) or `base` |

## Sample Output

For `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`:

* Contract name: Wrapped Ether (WETH)
* Verified: Yes
* Compiler: Solidity 0.4.18
* Functions: deposit, withdraw, approve, transfer
* Token data: price, market cap, holders

## What You Get Back

### Contract Information

```
Name: Wrapped Ether
Address: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
Verified: true
Compiler: v0.4.18+commit.9cf6e910
```

### ABI Summary

The tool provides function and event summaries:

**Functions:**

| Name      | Type  | Description                      |
| --------- | ----- | -------------------------------- |
| deposit   | write | Wrap ETH into WETH               |
| withdraw  | write | Unwrap WETH to ETH               |
| transfer  | write | Transfer WETH to another address |
| approve   | write | Approve spender allowance        |
| balanceOf | read  | Check WETH balance               |

**Events:**

| Name       | Description                    |
| ---------- | ------------------------------ |
| Transfer   | Emitted on transfers           |
| Approval   | Emitted on approvals           |
| Deposit    | Emitted when ETH is wrapped    |
| Withdrawal | Emitted when WETH is unwrapped |

### Token Data (if applicable)

```
Symbol: WETH
Decimals: 18
Price: $3,245.67
Market Cap: $4.2B
24h Volume: $1.8B
Holders: 845,231
```

### Proxy Information

For upgradeable contracts:

```
Proxy Type: TransparentUpgradeableProxy
Current Implementation: 0x1234...
Previous Implementations:
  - 0xabcd... (upgraded at block 15000000)
  - 0x5678... (original)
```

## Proxy Support

For upgradeable contracts, the tool:

1. Detects proxy type
2. Identifies current implementation
3. Returns implementation history
4. Provides the implementation ABI

## Related Tools

1. **Get overview** → `contractMetadataTool`
2. **Search code** → `regexCodeAnalysisTool` for specific functions
3. **Check upgrades** → `diffContractVersions` for change history
4. **See usage** → `getLatestTransactionsTool` for recent activity

## Tips

<Tip>
  Be specific: "what are the main functions" is better than "tell me about this contract"
</Tip>

<Tip>
  Specify chain for non-Ethereum: "on Base"
</Tip>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Before interacting with a new DeFi protocol">
    "Give me an overview of \[protocol] contract. What functions will I be calling to deposit/withdraw?"
  </Accordion>

  <Accordion title="Checking if a token is legitimate">
    "Is this token contract verified? Does it have any unusual functions like blacklist or pause?"
  </Accordion>

  <Accordion title="Understanding an NFT contract">
    "What's the minting function for this NFT? Are there any limits or requirements?"
  </Accordion>

  <Accordion title="Researching a protocol's architecture">
    "What are all the contracts in the \[protocol] system and how do they relate to each other?"
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Code Analysis" icon="magnifying-glass" href="/herd-mcp/tools/code-analysis">
    Search within contract code
  </Card>

  <Card title="Version Diffs" icon="code-compare" href="/herd-mcp/tools/diff-versions">
    Compare contract versions
  </Card>
</CardGroup>


# Deployed Contracts
Source: https://docs.herd.eco/herd-mcp/tools/deployed-contracts

Find contracts deployed by a wallet or factory

# Deployed Contracts

Lists contracts deployed by an address. Works with EOAs, factories, and Safes.

## Returns

* Deployed contract addresses and names
* Deployment timestamps and tx hashes
* Verification status
* Paginated results (10 per page)

## Example Queries

```
What contracts has 0x... deployed?
```

```
Show me all tokens created by this wallet
```

```
List contracts deployed by the Uniswap factory
```

## Parameters

| Parameter         | Required | Description                    |
| ----------------- | -------- | ------------------------------ |
| `deployerAddress` | Yes      | The deployer address to query  |
| `blockchain`      | No       | `ethereum` (default) or `base` |
| `page`            | No       | Page number (default: 1)       |

## Deployment Patterns Supported

| Pattern          | How It Works                            |
| ---------------- | --------------------------------------- |
| **Direct (EOA)** | Wallet directly deploys via transaction |
| **Factory**      | Contract creates other contracts        |
| **Safe**         | Multisig deploys via execution          |
| **CREATE2**      | Deterministic address deployment        |

## Example Output

### EOA Deployer

```
Contracts Deployed by 0xDeveloper...
====================================

Total Contracts: 15
Page 1 of 2

1. MyToken (0xToken...)
   - Deployed: 2024-01-10 14:32:00
   - Transaction: 0xabc...
   - Verified: Yes
   - Type: ERC-20 Token

2. NFTCollection (0xNFT...)
   - Deployed: 2024-01-08 10:15:00
   - Transaction: 0xdef...
   - Verified: Yes
   - Type: ERC-721 NFT

3. StakingRewards (0xStake...)
   - Deployed: 2024-01-05 16:45:00
   - Transaction: 0x123...
   - Verified: No
   - Type: Unknown

...
```

### Factory Contract

```
Contracts Deployed by Uniswap V3 Factory
========================================

Total Pools Created: 12,456
Page 1 of 1,246

1. USDC/WETH 0.3% Pool (0xPool1...)
   - Created: 2023-05-01
   - Creator Transaction: 0xabc...

2. WBTC/WETH 0.05% Pool (0xPool2...)
   - Created: 2023-04-28
   - Creator Transaction: 0xdef...

...
```

## Use Cases

**Developer portfolio:**

```
What contracts has this developer deployed?
```

**Factory analysis:**

```
How many pools has Uniswap V3 factory created on Base?
```

**Scam investigation:**

```
This scam token came from 0x... - what else did they deploy?
```

## Combining with Other Tools

For complete deployer analysis:

1. **List deployments** → `getDeployedContractsTool`
2. **Check deployer wallet** → `getWalletOverviewTool`
3. **Analyze specific contract** → `contractMetadataTool`
4. **Search contract code** → `regexCodeAnalysisTool`

## Common Use Cases

<AccordionGroup>
  <Accordion title="Auditing a developer's work">
    "List all contracts deployed by this audit client's wallet"
  </Accordion>

  <Accordion title="Finding protocol contracts">
    "What contracts make up the \[Protocol] ecosystem?"
  </Accordion>

  <Accordion title="Scam investigation">
    "What other tokens has this rug-puller deployed?"
  </Accordion>

  <Accordion title="Factory usage analysis">
    "How actively is this factory being used?"
  </Accordion>
</AccordionGroup>

## Tips

<Tip>
  Check verification status—verified contracts are easier to analyze.
</Tip>

<Tip>
  Look for patterns. Multiple similar deployments indicate factory or serial behavior.
</Tip>

## Pagination

For deployers with many contracts:

```
Page 1: Contracts 1-10
Page 2: Contracts 11-20
...
```

**You:** "Show page 3 of contracts deployed by this factory"

## Limitations

<Warning>
  **10 contracts per page.** Use pagination for complete list.
</Warning>

<Warning>
  **Complex factory patterns.** Some unusual factory patterns may not be fully captured.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Contract Metadata" icon="file-code" href="/herd-mcp/tools/contract-metadata">
    Analyze a deployed contract
  </Card>

  <Card title="Wallet Overview" icon="wallet" href="/herd-mcp/tools/wallet-overview">
    Learn more about the deployer
  </Card>
</CardGroup>


# Contract Version Diffs
Source: https://docs.herd.eco/herd-mcp/tools/diff-versions

Compare code changes between upgradeable contract versions

# Contract Version Diffs

Compares source code between contract implementation versions.

## Capabilities

* Structured diffs of code changes
* Works with proxy/implementation patterns
* Compare last two or all historical versions

## Example Queries

```
What changed in the latest USDC upgrade?
```

```
Show me the differences between the last two versions of this contract
```

```
Compare all historical versions of this upgradeable contract
```

## Parameters

| Parameter            | Required | Description                                          |
| -------------------- | -------- | ---------------------------------------------------- |
| `compareAllVersions` | No       | Compare all versions (default: false, only last two) |

<Note>
  The contract address is automatically determined from the current context. Make sure you've referenced a contract before asking for diffs.
</Note>

## Usage

### Latest Upgrade

```
Show me what changed in the latest upgrade of the Aave V3 Pool
```

### Full History

```
Show all changes this contract has gone through since deployment
```

Uses `compareAllVersions: true` to show every upgrade.

## Understanding the Output

### Diff Format

Changes are shown in a structured format:

```diff theme={null}
// File: LendingPool.sol

- function deposit(address asset, uint256 amount) external {
+ function deposit(address asset, uint256 amount, address onBehalfOf) external {
      // Added ability to deposit on behalf of another address

-     _deposit(asset, amount, msg.sender);
+     _deposit(asset, amount, onBehalfOf);
  }

+ // New function added in v2
+ function flashLoan(
+     address receiver,
+     address[] calldata assets,
+     uint256[] calldata amounts,
+     bytes calldata params
+ ) external {
+     // Flash loan implementation
+ }
```

### Change Summary

```
Changes in v2.0 → v2.1:
- Modified: deposit() - added onBehalfOf parameter
- Added: flashLoan() - new flash loan functionality
- Modified: withdraw() - added safety checks
- Removed: emergencyWithdraw() - deprecated function
```

## Why This Matters

### Security Research

When a contract is upgraded, you want to know:

* Were security fixes applied?
* Were new features added that could introduce risk?
* Were any functions removed or modified?

### Protocol Analysis

Understanding how a protocol evolves:

* What features were added over time?
* How did the team respond to issues?
* What's the upgrade frequency?

### Due Diligence

Before interacting with a protocol:

* Was it recently upgraded?
* What changed in the upgrade?
* Does the new code look safe?

## Real-World Example

### USDC Contract Upgrade Analysis

**You:** "Analyze the changes in the last USDC upgrade"

**Claude might return:**

```
USDC Implementation Upgrade Analysis
====================================

Previous: 0xabcd... (deployed Jan 2023)
Current:  0x1234... (deployed June 2023)

Key Changes:

1. Gas Optimizations
   - Simplified internal transfer logic
   - Reduced storage reads in balanceOf

2. New Features
   - Added permit() for gasless approvals (EIP-2612)
   - Added receiveWithAuthorization() for meta-transactions

3. Security Updates
   - Added additional checks in blacklist functions
   - Updated access control modifiers

4. Removed
   - Deprecated legacy migration functions

Assessment: Standard maintenance upgrade with gas
optimizations and new signature-based approval features.
```

## Proxy Pattern Detection

The tool automatically handles different proxy patterns:

| Pattern            | How It Works                      |
| ------------------ | --------------------------------- |
| Transparent Proxy  | Compares implementation contracts |
| UUPS Proxy         | Compares implementation contracts |
| Beacon Proxy       | Compares beacon implementations   |
| Diamond (EIP-2535) | Compares facet changes            |

## Tips

<Tip>
  Start with metadata to understand the proxy structure.
</Tip>

<Tip>
  Be specific: "Did the upgrade change how withdrawals work?"
</Tip>

## Limitations

<Warning>
  **Requires verified implementations.** All versions must have verified source code.
</Warning>

<Warning>
  **Proxy detection limitations.** Some custom proxy patterns may not be automatically detected.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Contract Metadata" icon="file-code" href="/herd-mcp/tools/contract-metadata">
    Get the full contract overview
  </Card>

  <Card title="Transaction Analysis" icon="receipt" href="/herd-mcp/tools/query-transaction">
    See how the contract is being used
  </Card>
</CardGroup>


# Documentation
Source: https://docs.herd.eco/herd-mcp/tools/documentation

Read HAL and platform documentation from within your agent

# Documentation

Read internal Herd documentation by document ID. Supports fetching multiple documents in a single call.

## Returns

* **Document content** — Full text of the requested documentation
* **Available IDs** — If an unknown ID is provided, returns the list of available document IDs

## Example Queries

```
Show me the HAL syntax documentation
```

```
Read the HAL examples and module docs
```

## Parameters

| Parameter    | Required | Description                                              |
| ------------ | -------- | -------------------------------------------------------- |
| `documentId` | Yes      | A single document ID string, or an array of document IDs |

### Available Documents

| Document ID               | Content                                                |
| ------------------------- | ------------------------------------------------------ |
| `hal://spec/syntax`       | HAL grammar and special forms                          |
| `hal://spec/modules/herd` | Blockchain functions (read, write, encode, swap, etc.) |
| `hal://spec/examples`     | Worked HAL expression examples                         |

## Tips

<Tip>
  Fetch all three HAL docs at once by passing an array: `["hal://spec/syntax", "hal://spec/modules/herd", "hal://spec/examples"]`
</Tip>

<Tip>
  Always read the HAL documentation before creating or editing HAL expressions — the syntax has non-obvious requirements.
</Tip>

## Related Tools

* **Create actions** → [Actions & Adapters](/herd-mcp/tools/hal-actions-adapters)
* **Test expressions** → [Evaluation](/herd-mcp/tools/hal-evaluation)
* **HAL language reference** → [HAL Expression System](/herd-actions/overview)

## Next Steps

<CardGroup>
  <Card title="HAL Reference" icon="book" href="/herd-actions/overview">
    Full HAL language documentation
  </Card>

  <Card title="Evaluation" icon="flask" href="/herd-mcp/tools/hal-evaluation">
    Simulate HAL expressions
  </Card>
</CardGroup>


# Actions & Adapters
Source: https://docs.herd.eco/herd-mcp/tools/hal-actions-adapters

Create, search, update, and delete HAL actions and adapters

# Actions & Adapters

Tools for managing HAL actions and adapters — the core building blocks of the [HAL Expression System](/herd-actions/overview).

**Actions** are executable batches of write functions for on-chain transactions. **Adapters** are reusable functions (write, read, or code) that can be imported into actions or other adapters.

***

## Search Actions & Adapters

Search existing actions and adapters before creating new ones — existing adapters can be imported directly into new actions.

### Parameters

| Parameter           | Required | Description                                    |
| ------------------- | -------- | ---------------------------------------------- |
| `expressionType`    | No       | `action`, `adapter`, or `both` (default)       |
| `name`              | No       | Search by name                                 |
| `scope`             | No       | Filter by `yours` and/or `verified`            |
| `contractAddress`   | No       | Filter by contract address                     |
| `functionSignature` | No       | Filter by function signature (4-byte selector) |
| `blockchain`        | No       | `ethereum` or `base`                           |
| `page`              | No       | Page number for pagination (20 per page)       |

### Example Queries

```
Search for existing USDC transfer adapters
```

```
Find verified swap actions on Base
```

***

## Get Action or Adapter

Retrieve a specific action or adapter by ID, including its full HAL expression.

### Parameters

| Parameter           | Required | Description                                               |
| ------------------- | -------- | --------------------------------------------------------- |
| `id`                | Yes      | Action or adapter ID                                      |
| `versionName`       | No       | Version name (e.g. `v1`); defaults to latest              |
| `includeReferences` | No       | When `true`, inlines imported expressions and code blocks |

***

## Create Action

Create a new action from a HAL expression. Actions have batched steps — each batch contains `write-function` calls.

<Tip>
  Before creating an action, read the HAL documentation using the [Documentation tool](/herd-mcp/tools/documentation) with document IDs `hal://spec/syntax`, `hal://spec/modules/herd`, and `hal://spec/examples`. Search for existing adapters first with the search tool above.
</Tip>

### Parameters

| Parameter     | Required | Description                          |
| ------------- | -------- | ------------------------------------ |
| `name`        | Yes      | Action name                          |
| `description` | No       | Description of what the action does  |
| `expression`  | Yes      | HAL expression (JSON array)          |
| `publish`     | No       | Publish immediately (`true`/`false`) |

***

## Create Adapter

Create a new adapter from a HAL expression. Adapters encapsulate reusable logic (queries and writes) for import into actions.

### Parameters

| Parameter     | Required | Description                          |
| ------------- | -------- | ------------------------------------ |
| `name`        | Yes      | Adapter name                         |
| `description` | No       | Description of what the adapter does |
| `expression`  | Yes      | HAL expression (JSON array)          |
| `publish`     | No       | Publish immediately (`true`/`false`) |

<Tip>
  Start with logic in actions — extract to adapters when you see the same pattern repeated across multiple actions.
</Tip>

***

## Update Action

Update an existing action's name, description, expression, or publish status.

### Parameters

| Parameter     | Required | Description                                               |
| ------------- | -------- | --------------------------------------------------------- |
| `id`          | Yes      | Action ID                                                 |
| `name`        | No       | New name                                                  |
| `description` | No       | New description                                           |
| `expression`  | No       | JSON Patch operations (RFC 6902) to modify the expression |
| `publish`     | No       | Publish the latest version                                |

Expression updates use [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) operations: `add`, `remove`, `replace`, `move`, `copy`, `test`. Paths use JSON Pointer syntax (e.g., `/0`, `/1/2`, `/1/2/1`).

***

## Update Adapter

Update an existing adapter's name, description, expression, or publish status. Same parameters and patch format as Update Action.

### Parameters

| Parameter     | Required | Description                                               |
| ------------- | -------- | --------------------------------------------------------- |
| `id`          | Yes      | Adapter ID                                                |
| `name`        | No       | New name                                                  |
| `description` | No       | New description                                           |
| `expression`  | No       | JSON Patch operations (RFC 6902) to modify the expression |
| `publish`     | No       | Publish the latest version                                |

***

## Delete Action or Adapter

Delete an action or adapter by ID.

### Parameters

| Parameter | Required | Description          |
| --------- | -------- | -------------------- |
| `id`      | Yes      | Action or adapter ID |

<Warning>
  Deletion fails if the action/adapter is auto-synced to a code block (delete the code block instead) or if other actions/adapters import it.
</Warning>

***

## Workflow

1. **Search** for existing adapters that do what you need
2. **Read** HAL documentation if creating new expressions
3. **Create** adapters for reusable logic, actions for transactions
4. **Simulate** with [Evaluation tools](/herd-mcp/tools/hal-evaluation) before publishing
5. **Publish** once tested

## Related Tools

* **Simulate expressions** → [Evaluation](/herd-mcp/tools/hal-evaluation)
* **Manage code blocks** → [Code Blocks](/herd-mcp/tools/hal-code-blocks)
* **Organize into groups** → [Collections](/herd-mcp/tools/hal-collections)
* **HAL language reference** → [HAL Expression System](/herd-actions/overview)

## Next Steps

<CardGroup>
  <Card title="HAL Reference" icon="book" href="/herd-actions/overview">
    Full HAL language documentation
  </Card>

  <Card title="Evaluation" icon="flask" href="/herd-mcp/tools/hal-evaluation">
    Simulate before publishing
  </Card>
</CardGroup>


# Code Blocks
Source: https://docs.herd.eco/herd-mcp/tools/hal-code-blocks

Create, update, and execute TypeScript code blocks for use in HAL expressions

# Code Blocks

Tools for managing TypeScript code blocks that run on Val.town/Deno. Code blocks can be called from HAL expressions via the `code` function and have auto-synced adapters generated for them.

***

## Get Code Block

Retrieve a code block's metadata, code, argument schemas, and version history. When called without an ID, lists code blocks with optional filtering.

### Parameters

| Parameter      | Required | Description                                 |
| -------------- | -------- | ------------------------------------------- |
| `definitionId` | No       | Code block ID. Omit to list all code blocks |
| `name`         | No       | Filter by name (when listing)               |
| `page`         | No       | Page number for pagination                  |

### Returns

* **Metadata** — Name, intent, creation date
* **Code** — Full TypeScript source for the selected version
* **Argument schemas** — Input and output schemas extracted from the deployed endpoint
* **Versions** — List of all versions with publish status
* **Auto-synced adapter ID** — The adapter that stays in sync with this code block

***

## Create Code Block

Create a new code block with TypeScript source code. The code is deployed to Val.town and an adapter is auto-generated.

### Parameters

| Parameter | Required | Description                           |
| --------- | -------- | ------------------------------------- |
| `name`    | Yes      | Code block name                       |
| `code`    | Yes      | TypeScript source code                |
| `publish` | No       | Immediately publish the first version |

### Code Format

Code blocks must use the `@herd-labs/code-blocks-framework` package:

```typescript theme={null}
import { initializeHerdCodeBlockServer } from "@herd-labs/code-blocks-framework";

export default initializeHerdCodeBlockServer({
  inputSchema: {
    years: { type: "int256" },
  },
  outputSchema: {
    seconds: { type: "uint256" },
  },
  handler: async ({ years }) => {
    const seconds = BigInt(years) * 365n * 24n * 60n * 60n;
    return { seconds: seconds.toString() };
  },
}).fetch;
```

<Tip>
  Set `publish=true` to make the code block immediately usable in actions. Otherwise, publish later via the update tool.
</Tip>

***

## Update Code Block

Update a code block's metadata and/or TypeScript code. Code changes trigger redeployment and schema re-extraction.

### Parameters

| Parameter      | Required | Description                          |
| -------------- | -------- | ------------------------------------ |
| `definitionId` | Yes      | Code block ID                        |
| `name`         | No       | New name                             |
| `intent`       | No       | New intent/description               |
| `code`         | No       | New TypeScript source code           |
| `publish`      | No       | Publish the latest unpublished draft |

When code is provided: if the latest version is an unpublished draft, it's updated in-place; otherwise a new draft version is created.

***

## Delete Code Block

Delete a code block and its auto-synced adapter.

### Parameters

| Parameter      | Required | Description   |
| -------------- | -------- | ------------- |
| `definitionId` | Yes      | Code block ID |

<Warning>
  Deletion fails if the auto-synced adapter is imported by other actions or adapters.
</Warning>

***

## Execute Code Block

Run a code block with given arguments. Uses the test branch (safe for iteration).

### Parameters

| Parameter      | Required | Description                                      |
| -------------- | -------- | ------------------------------------------------ |
| `definitionId` | Yes      | Code block ID                                    |
| `codeId`       | No       | Specific version ID (defaults to latest)         |
| `args`         | Yes      | Input arguments matching the code block's schema |

### Returns

* **Result** — Output values from the code block
* **Logs** — Console output from execution (useful for debugging)

***

## How Code Blocks Work in HAL

Once created, code blocks are callable in HAL expressions via the `code` function:

```json theme={null}
["coerce", {
  "type": { "seconds": "uint256" },
  "value": ["code", { "args": { "years": "years" }, "id": "definitionId:codeVersionId" }]
}]
```

Each code block has an auto-synced adapter that updates automatically when the code is published. This adapter can be imported into actions like any other adapter.

## Related Tools

* **Use in actions** → [Actions & Adapters](/herd-mcp/tools/hal-actions-adapters)
* **Test expressions** → [Evaluation](/herd-mcp/tools/hal-evaluation)
* **HAL language reference** → [HAL Expression System](/herd-actions/overview)

## Next Steps

<CardGroup>
  <Card title="Actions & Adapters" icon="layer-group" href="/herd-mcp/tools/hal-actions-adapters">
    Use code blocks in actions
  </Card>

  <Card title="Evaluation" icon="flask" href="/herd-mcp/tools/hal-evaluation">
    Test your code blocks in expressions
  </Card>
</CardGroup>


# Collections
Source: https://docs.herd.eco/herd-mcp/tools/hal-collections

Organize actions and adapters into collections

# Collections

Tools for organizing HAL actions and adapters into named collections. Only actions and read/code adapters can be added — write adapters are not allowed in collections.

***

## Search Collections

List and search collections by name, scope, or both.

### Parameters

| Parameter | Required | Description                              |
| --------- | -------- | ---------------------------------------- |
| `name`    | No       | Search by name                           |
| `scope`   | No       | Filter by `yours` and/or `verified`      |
| `page`    | No       | Page number for pagination (20 per page) |

### Returns

Each collection includes:

* **id, name, description** — Collection metadata
* **Item count** — Number of items in the collection
* **Items** — Action/adapter ID, version, type, name, description, verified status

***

## Get Collection

Retrieve a specific collection and its items.

### Parameters

| Parameter | Required | Description   |
| --------- | -------- | ------------- |
| `id`      | Yes      | Collection ID |

### Returns

* **Collection metadata** — ID, name, description, creator
* **Items** — Each item includes version ID, action ID, name, description, version name, intent, publish status

***

## Create Collection

Create a new collection of actions and adapters.

### Parameters

| Parameter     | Required | Description                            |
| ------------- | -------- | -------------------------------------- |
| `name`        | Yes      | Collection name                        |
| `description` | No       | Collection description                 |
| `actions`     | No       | Array of action/adapter IDs to include |

<Tip>
  After creating an action and its supporting adapters, organize them into a collection. Include the action and any read/code adapters that provide useful data context.
</Tip>

***

## Update Collection

Update a collection's name, description, and/or items.

### Parameters

| Parameter         | Required | Description                           |
| ----------------- | -------- | ------------------------------------- |
| `id`              | Yes      | Collection ID                         |
| `name`            | No       | New name                              |
| `description`     | No       | New description                       |
| `actionsToAdd`    | No       | Array of action/adapter IDs to add    |
| `actionsToRemove` | No       | Array of action/adapter IDs to remove |

***

## Use Cases

<AccordionGroup>
  <Accordion title="Protocol bundles">
    Group a protocol's deposit action with its position monitoring read adapter and balance checker.
  </Accordion>

  <Accordion title="Workflow sets">
    Collect related actions that form a complete workflow — e.g., approve, swap, and deposit.
  </Accordion>

  <Accordion title="Sharing verified actions">
    Organize verified, production-ready actions into discoverable collections for other users.
  </Accordion>
</AccordionGroup>

## Related Tools

* **Create actions** → [Actions & Adapters](/herd-mcp/tools/hal-actions-adapters)
* **Manage code blocks** → [Code Blocks](/herd-mcp/tools/hal-code-blocks)

## Next Steps

<CardGroup>
  <Card title="Actions & Adapters" icon="layer-group" href="/herd-mcp/tools/hal-actions-adapters">
    Create items for your collections
  </Card>

  <Card title="Evaluation" icon="flask" href="/herd-mcp/tools/hal-evaluation">
    Test actions before adding to collections
  </Card>
</CardGroup>


# Evaluation
Source: https://docs.herd.eco/herd-mcp/tools/hal-evaluation

Simulate and test HAL expressions in a sandboxed environment

# Evaluation

Tools for simulating HAL expressions before publishing. Expressions run in a sandboxed Tevm fork — no real transactions are submitted.

***

## Evaluate Existing Action

Simulate a saved action by ID. Loads the action's HAL expression, injects the `main()` call with provided inputs, and simulates the entire action.

### Parameters

| Parameter  | Required | Description                              |
| ---------- | -------- | ---------------------------------------- |
| `actionId` | Yes      | Action ID to simulate                    |
| `inputs`   | Yes      | Input values for the action's parameters |

### Returns

* **Evaluation result** — Final output of the expression
* **Operation log (oplog)** — Full trace of every function call during execution
* **Simulated transaction hashes** — Can be inspected with [Query Transaction](/herd-mcp/tools/query-transaction)

<Tip>
  Always simulate actions before publishing. Iteration is expected: simulate → inspect results with Query Transaction (works on simulated tx hashes) → fix issues → simulate again.
</Tip>

***

## Evaluate Arbitrary Expression

Evaluate a complete, self-contained HAL expression in a sandboxed Tevm fork. Use this for testing expressions that aren't saved yet.

### Parameters

| Parameter    | Required | Description                                   |
| ------------ | -------- | --------------------------------------------- |
| `expression` | Yes      | Complete HAL expression (JSON array)          |
| `inputs`     | No       | Input values if the expression has parameters |

### Returns

* **Evaluation result** — Final output
* **Operation log (oplog)** — Full execution trace

<Warning>
  Before constructing a HAL expression, read the HAL documentation using the [Documentation tool](/herd-mcp/tools/documentation) with document IDs `hal://spec/syntax`, `hal://spec/modules/herd`, and `hal://spec/examples`. HAL has non-obvious syntax requirements (e.g., ABI arrays must be wrapped in `["quote", [...]]` to prevent evaluation).
</Warning>

### Tevm Fork Behavior

* Forks are created lazily — only when the expression performs on-chain actions (`read-function`, `write-function`, `swap`)
* Pure expressions evaluate without any blockchain interaction
* Simulated transaction hashes can be queried with [Query Transaction](/herd-mcp/tools/query-transaction) to inspect traces

***

## Understanding Oplogs

Both evaluation tools return an operation log (oplog) — a detailed trace of every function call during execution. Each entry contains:

| Field          | Description                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `operationId`  | Unique ID for this operation                                             |
| `functionName` | Function called (e.g., `code`, `read-function`, `getPath`, user-defined) |
| `status`       | `success` or `error`                                                     |
| `args`         | Arguments passed to the function                                         |
| `result`       | Return value (or error message)                                          |
| `timestamp`    | When the operation executed                                              |

### Debugging with Oplogs

* **Trace execution flow** — See which functions run and in what order
* **Inspect inputs/outputs** — Check what each function receives and returns
* **Identify failures** — Failed operations show `"status": "error"` with error messages
* **Inspect transactions** — Use simulated tx hashes with [Query Transaction](/herd-mcp/tools/query-transaction) to discover missing approvals, encoding errors, etc.

***

## Simulation Workflow

1. **Read docs** — Fetch HAL documentation with the [Documentation tool](/herd-mcp/tools/documentation)
2. **Search adapters** — Find existing adapters with [Actions & Adapters](/herd-mcp/tools/hal-actions-adapters)
3. **Build expression** — Construct your HAL expression
4. **Simulate** — Run with Evaluate Arbitrary or Evaluate Existing
5. **Inspect** — Check oplog and use Query Transaction on simulated hashes
6. **Iterate** — Fix issues and simulate again
7. **Publish** — Once validated, publish via [Actions & Adapters](/herd-mcp/tools/hal-actions-adapters)

## Related Tools

* **Create actions** → [Actions & Adapters](/herd-mcp/tools/hal-actions-adapters)
* **Inspect simulated txs** → [Query Transaction](/herd-mcp/tools/query-transaction)
* **Read HAL docs** → [Documentation](/herd-mcp/tools/documentation)
* **HAL language reference** → [HAL Expression System](/herd-actions/overview)

## Next Steps

<CardGroup>
  <Card title="Query Transaction" icon="magnifying-glass" href="/herd-mcp/tools/query-transaction">
    Inspect simulated transactions
  </Card>

  <Card title="HAL Reference" icon="book" href="/herd-actions/overview">
    Full HAL language documentation
  </Card>
</CardGroup>


# Latest Transactions
Source: https://docs.herd.eco/herd-mcp/tools/latest-transactions

Find recent transactions by function call or event

# Latest Transactions

Fetches recent transactions that call a specific function or emit a specific event.

## Returns

* Transaction hashes with decoded arguments
* Function parameters or event data
* Useful for monitoring activity and finding examples

## Example Queries

```
Show me the last 10 swaps on Uniswap V3
```

```
Find recent mint transactions for this NFT contract
```

```
What are the latest Transfer events from USDC?
```

## Parameters

| Parameter         | Required | Description                              |
| ----------------- | -------- | ---------------------------------------- |
| `type`            | Yes      | `function` or `event`                    |
| `signature`       | Yes      | Keccak hash of function/event (from ABI) |
| `contractAddress` | Yes      | The contract to query                    |
| `blockchain`      | No       | `ethereum` (default) or `base`           |

<Note>
  You don't need to know the signature hash - Claude will look it up from the contract's ABI automatically.
</Note>

### Function Calls

```
Show me the latest deposit() calls on Aave
```

### Events

```
Find recent Transfer events from the PEPE token
```

## Understanding the Output

### Function Call Results

```
Recent deposit() calls on Aave V3 Pool:

1. Transaction: 0xabc...
   Block: 18,450,123
   Timestamp: 2024-01-15 14:32:00
   Arguments:
     - asset: 0xUSDC (USDC)
     - amount: 50,000.00
     - onBehalfOf: 0xUser...
     - referralCode: 0

2. Transaction: 0xdef...
   Block: 18,450,089
   ...
```

### Event Results

```
Recent Transfer events from USDC:

1. Transaction: 0x111...
   Block: 18,450,200
   Event Args:
     - from: 0xBinance
     - to: 0xUser
     - value: 10,000.00

2. Transaction: 0x222...
   ...
```

## Common Use Cases

### Monitor Protocol Activity

**You:** "How many swaps happened on Uniswap in the last hour?"

### Find Example Transactions

**You:** "Find me an example of someone using the flashLoan function"

### Track Large Movements

**You:** "Show recent large USDC transfers (look for whale activity)"

### Analyze User Behavior

**You:** "What functions are people calling most on this contract?"

## Function vs Event

| Use Functions When                           | Use Events When                    |
| -------------------------------------------- | ---------------------------------- |
| You want to see how people call the contract | You want to track outcomes/results |
| Analyzing input parameters                   | Tracking token movements           |
| Finding failed transactions                  | Historical data analysis           |
| Debugging contract interactions              | Building activity feeds            |

## Signature Hashes Explained

Each function and event has a unique identifier:

**Function signatures** (4 bytes):

```
transfer(address,uint256) → 0xa9059cbb
```

**Event signatures** (32 bytes):

```
Transfer(address,address,uint256) → 0xddf252ad...
```

Claude automatically handles these - just describe what you're looking for.

## Practical Examples

### Example 1: Monitoring NFT Mints

**You:** "Show me recent mints from the Azuki contract"

**Result:**

```
Recent mint() calls:

1. 0xabc... - Minted 2 tokens to 0xCollector
2. 0xdef... - Minted 1 token to 0xWhale
3. 0x123... - Minted 5 tokens to 0xTrader

Total minted in last 10 txs: 15 tokens
```

### Example 2: DEX Activity

**You:** "What pairs are being swapped most on Uniswap V3?"

**Result:**

```
Recent swap activity analysis:

Most active pairs:
1. WETH/USDC - 45 swaps
2. WETH/USDT - 23 swaps
3. WBTC/WETH - 18 swaps

Average swap size: $12,450
```

### Example 3: Governance Activity

**You:** "Show recent votes on Compound governance"

**Result:**

```
Recent VoteCast events:

1. Proposal #145: 0xVoter voted FOR (250,000 COMP)
2. Proposal #145: 0xWhale voted AGAINST (180,000 COMP)
3. Proposal #144: 0xDAO voted FOR (500,000 COMP)
```

## Combining with Other Tools

1. **Find recent transactions** → `getLatestTransactionsTool`
2. **Analyze specific tx** → `queryTransactionTool`
3. **Understand the function** → `regexCodeAnalysisTool`

## Tips

<Tip>
  Be specific: "deposit" is clearer than "put money in"
</Tip>

<Tip>
  Mention the contract—different protocols use different function names.
</Tip>

## Limitations

<Warning>
  **Historical depth varies.** Very old transactions may not be available.
</Warning>

<Warning>
  **Rate limits apply.** Don't query too frequently for the same data.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Query Transaction" icon="receipt" href="/herd-mcp/tools/query-transaction">
    Analyze a specific transaction in detail
  </Card>

  <Card title="Transaction Activity" icon="list" href="/herd-mcp/tools/transaction-activity">
    Get full transaction history for an address
  </Card>
</CardGroup>


# Query Transaction
Source: https://docs.herd.eco/herd-mcp/tools/query-transaction

Decode traces, logs, and balance changes for any transaction

# Query Transaction

Decodes transaction data including traces, logs, and balance changes.

## Returns

* Decoded calldata and function calls
* Parsed event logs with parameters
* Token/ETH balance changes
* Internal transaction traces
* All contracts and addresses involved

## Example Queries

```
What happened in transaction 0x1234...?
```

```
Decode this swap transaction: 0xabcd...
```

```
Explain all the token transfers in tx 0x5678...
```

## Parameters

| Parameter        | Required | Description                                               |
| ---------------- | -------- | --------------------------------------------------------- |
| `txHash`         | Yes      | The transaction hash (0x...)                              |
| `returnAllData`  | No       | Return all data without filtering (default: false)        |
| `balanceQuery`   | No       | Filter balance changes by query (e.g., "USDC transfers")  |
| `traceLogQuery`  | No       | Filter traces/logs by query (e.g., "swap function calls") |
| `includeRawData` | No       | Include raw hex calldata (default: false)                 |
| `blockchain`     | No       | `ethereum` or `base` (auto-detected if not provided)      |

## Understanding Transaction Components

### Balance Changes

Shows all token/ETH movements:

```
Balance Changes:
┌──────────────┬─────────────┬────────────────┬─────────────────┐
│ Token        │ From        │ To             │ Amount          │
├──────────────┼─────────────┼────────────────┼─────────────────┤
│ USDC         │ 0xUser...   │ 0xPool...      │ 1,000.00        │
│ WETH         │ 0xPool...   │ 0xUser...      │ 0.35            │
└──────────────┴─────────────┴────────────────┴─────────────────┘
```

<Note>
  Balance amounts are already decimal-adjusted (human-readable). No need to divide by decimals.
</Note>

### Traces

Internal calls within the transaction:

```
Traces:
1. 0xUser calls 0xRouter.swap(...)
   └─ 2. 0xRouter calls 0xPool.swap(...)
      └─ 3. 0xPool calls 0xUSDC.transferFrom(...)
      └─ 4. 0xPool calls 0xWETH.transfer(...)
```

### Event Logs

Decoded events emitted:

```
Events:
1. Swap (0xPool)
   - sender: 0xRouter
   - amount0In: 1000000000 (1000 USDC)
   - amount1Out: 350000000000000000 (0.35 WETH)

2. Transfer (0xUSDC)
   - from: 0xUser
   - to: 0xPool
   - value: 1000000000

3. Transfer (0xWETH)
   - from: 0xPool
   - to: 0xUser
   - value: 350000000000000000
```

### Basic Decode

```
What happened in 0x8a3c4b5d6e7f...
```

Returns: summary, function called, token transfers, gas cost, status

### Filtered Results

```
Show me only the USDC transfers in this transaction
```

Uses `balanceQuery` to filter balance changes.

### DeFi Transactions

```
Explain this Uniswap swap step by step
```

Shows: function called, input/output tokens, routing path, exchange rate, fees

## Real-World Examples

### Example 1: Simple Token Transfer

```
Transaction: 0x123...
Type: ERC-20 Transfer
From: 0xAlice
To: 0xBob
Token: USDC
Amount: 500.00 USDC
Gas: 65,000 ($2.34)
Status: Success
```

### Example 2: Complex DeFi Transaction

```
Transaction: 0x456...
Type: Multi-hop Swap
Protocol: Uniswap V3

Action: Swapped 10,000 USDC → 3.5 ETH

Route:
  USDC → WETH (0.3% fee pool)

Balance Changes:
  - User: -10,000 USDC
  - User: +3.5 WETH

Events Emitted:
  1. Approval (USDC)
  2. Swap (Uniswap Pool)
  3. Transfer (USDC)
  4. Transfer (WETH)

Effective Rate: 1 ETH = 2,857.14 USDC
Gas Used: 184,532 ($8.45)
```

### Example 3: Failed Transaction

```
Transaction: 0x789...
Status: FAILED (Reverted)
Reason: "Insufficient liquidity"

What Happened:
  User tried to swap 1M USDC for ETH
  Pool didn't have enough liquidity
  Transaction reverted after consuming 45,000 gas

Gas Wasted: $1.89
```

## Filtering Options

### Balance Query Examples

```
"USDC transfers"           → Only USDC movements
"mints and burns"          → Token minting/burning
"ETH transfers"            → Native ETH movements
"NFT transfers"            → ERC-721 movements
```

### Trace/Log Query Examples

```
"swap function calls"      → Swap-related traces
"Transfer events"          → ERC-20 Transfer logs
"approval events"          → Token approvals
"admin functions"          → Privileged operations
```

## Full Data Mode

Set `returnAllData: true` for complete output:

* All balance changes (unfiltered)
* Complete trace tree
* All decoded logs
* Raw data (if `includeRawData: true`)

## Tips

<Tip>
  Start broad, then filter. Ask "what happened" first, then drill into specifics.
</Tip>

<Tip>
  Ask "why" questions: "Why did this fail?" or "Why so many internal calls?"
</Tip>

## Common Questions

<AccordionGroup>
  <Accordion title="What if the transaction failed?">
    Claude will explain why it failed, show what it tried to do, and how much gas was wasted.
  </Accordion>

  <Accordion title="Can I see pending transactions?">
    No, only confirmed (mined) transactions can be analyzed.
  </Accordion>

  <Accordion title="What about internal transactions?">
    Yes! The traces show all internal calls, even those not visible on basic block explorers.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Latest Transactions" icon="clock" href="/herd-mcp/tools/latest-transactions">
    Find recent transactions by function/event
  </Card>

  <Card title="Transaction Activity" icon="list" href="/herd-mcp/tools/transaction-activity">
    Get transaction history for an address
  </Card>
</CardGroup>


# Role Topology
Source: https://docs.herd.eco/herd-mcp/tools/role-topology

Inspect the role and permission structure of a smart contract

# Role Topology

Fetches the full role topology for a smart contract — the hierarchy of roles, their holders, and relationships. Always fetches fresh on-chain data.

## Returns

* **Roots** — Top-level roles (e.g., DEFAULT\_ADMIN\_ROLE)
* **Nodes** — All role nodes with holder edges embedded
* **Resolved At** — Block number at which roles were resolved

## Example Queries

```
What roles exist on this contract and who holds them?
```

```
Show me the admin structure for 0x...
```

```
Who has the MINTER_ROLE on this contract?
```

## Parameters

| Parameter         | Required | Description                    |
| ----------------- | -------- | ------------------------------ |
| `contractAddress` | Yes      | The contract address (0x...)   |
| `blockchain`      | No       | `ethereum` (default) or `base` |

## Use Cases

<AccordionGroup>
  <Accordion title="Security auditing">
    Check who holds privileged roles like owner, admin, pauser, or upgrader before interacting with a protocol.
  </Accordion>

  <Accordion title="Governance research">
    Map out the permission structure of a DAO or multisig-controlled protocol.
  </Accordion>

  <Accordion title="Pre-integration checks">
    Before integrating with a contract, verify that the role hierarchy matches what the protocol claims.
  </Accordion>
</AccordionGroup>

## Related Tools

* **Contract overview** → [Contract Metadata](/herd-mcp/tools/contract-metadata)
* **Check upgrades** → [Diff Versions](/herd-mcp/tools/diff-versions)
* **See usage** → [Latest Transactions](/herd-mcp/tools/latest-transactions)

## Next Steps

<CardGroup>
  <Card title="Contract Metadata" icon="file-code" href="/herd-mcp/tools/contract-metadata">
    Fetch contract details
  </Card>

  <Card title="Diff Versions" icon="code-compare" href="/herd-mcp/tools/diff-versions">
    Compare contract versions
  </Card>
</CardGroup>


# Token Activity
Source: https://docs.herd.eco/herd-mcp/tools/token-activity

Token balance and transfer history for any address

# Token Activity

Returns token balance and transfer history for a specific holder/token pair.

## Returns

* Current balance
* Transfer history (in/out direction)
* Paginated results (100 per page)

## Example Queries

```
Show me the USDC transfer history for 0x...
```

```
When did this wallet last receive ETH?
```

```
Track PEPE token activity for this address
```

## Parameters

| Parameter       | Required | Description                    |
| --------------- | -------- | ------------------------------ |
| `holderAddress` | Yes      | The wallet address to check    |
| `tokenAddress`  | Yes      | The token contract address     |
| `blockchain`    | No       | `ethereum` (default) or `base` |
| `page`          | No       | Page number (default: 1)       |

<Note>
  You can use token symbols (like "USDC") - Claude will look up the correct contract address.
</Note>

## Example Output

```
Token Activity for 0xUser...
Token: USDC (0xA0b86991...)
============================

Current Balance: 25,000.00 USDC

Transfer History (Page 1):
┌───────────────────────┬───────────┬─────────────────┬────────────────┐
│ Date                  │ Direction │ Amount          │ Counterparty   │
├───────────────────────┼───────────┼─────────────────┼────────────────┤
│ 2024-01-15 14:32:00   │ OUT       │ 1,000.00        │ 0xDEX...       │
│ 2024-01-14 10:15:00   │ IN        │ 5,000.00        │ 0xCEX...       │
│ 2024-01-13 22:45:00   │ OUT       │ 2,500.00        │ 0xFriend...    │
│ 2024-01-12 08:00:00   │ IN        │ 10,000.00       │ 0xSalary...    │
│ 2024-01-10 16:30:00   │ OUT       │ 500.00          │ 0xMerchant...  │
└───────────────────────┴───────────┴─────────────────┴────────────────┘

Showing 5 of 150 transfers (100 per page)
```

## Understanding Direction

| Direction | Meaning                       |
| --------- | ----------------------------- |
| **IN**    | Tokens received by the holder |
| **OUT**   | Tokens sent from the holder   |

## Use Cases

**Track incoming funds:**

```
When did this wallet last receive USDC and from where?
```

**Analyze spending:**

```
How much ETH has this wallet spent in the last month?
```

**Track whale movements:**

```
Track PEPE transfers for this known whale wallet
```

## Pagination

For addresses with extensive history:

**You:** "Show page 5 of USDC transfers for 0x..."

```
Transfer History (Page 5):
Showing transfers 401-500 of 1,234
```

## Comparing Multiple Tokens

You can ask about multiple tokens:

**You:** "Compare the USDC and USDT activity for this wallet"

**Claude will make multiple queries and provide comparison.**

## Common Use Cases

<AccordionGroup>
  <Accordion title="Track salary/income payments">
    "Show me all incoming USDC transfers over \$1,000"
  </Accordion>

  <Accordion title="Monitor DeFi positions">
    "Track aUSDC (Aave deposit token) activity for this wallet"
  </Accordion>

  <Accordion title="Analyze trading activity">
    "Show the WETH in/out flow for this trader"
  </Accordion>

  <Accordion title="Investigate token accumulation">
    "When did this wallet start accumulating this token?"
  </Accordion>
</AccordionGroup>

## Combining with Other Tools

For complete analysis:

1. **Check all holdings** → `getWalletOverviewTool`
2. **Focus on one token** → `getTokenActivityTool`
3. **Analyze specific transfer** → `queryTransactionTool`
4. **Check counterparty** → `getWalletOverviewTool` on the other address

## Tips

<Tip>
  Use token symbols—"USDC activity" is easier than the full address.
</Tip>

<Tip>
  Ask for net flow: "What's the net USDC flow for this wallet?"
</Tip>

## Supported Token Types

| Type           | Support           |
| -------------- | ----------------- |
| ERC-20         | Full support      |
| Native ETH     | Full support      |
| ERC-721 (NFTs) | Transfer tracking |
| ERC-1155       | Transfer tracking |

## Limitations

<Warning>
  **100 transfers per page.** Use pagination for complete history.
</Warning>

<Warning>
  **Historical depth.** Very old transfers may have limited data.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Wallet Overview" icon="wallet" href="/herd-mcp/tools/wallet-overview">
    See complete wallet profile
  </Card>

  <Card title="Deployed Contracts" icon="file-code" href="/herd-mcp/tools/deployed-contracts">
    Find contracts created by an address
  </Card>
</CardGroup>


# Transaction Activity
Source: https://docs.herd.eco/herd-mcp/tools/transaction-activity

Enriched transaction history for any address

# Transaction Activity

Returns transaction history with decoded function calls, balance changes, and contract creations.

## Returns

* Function names and decoded parameters
* Balance changes per transaction
* Contract creations
* Paginated history (10 per page)

## Example Queries

```
Show me the recent transactions from 0x...
```

```
What has this wallet been doing lately?
```

```
Get the transaction history for vitalik.eth
```

## Parameters

| Parameter     | Required | Description                               |
| ------------- | -------- | ----------------------------------------- |
| `fromAddress` | Yes      | The address to get activity for           |
| `toAddress`   | No       | Filter to specific destination            |
| `blockchain`  | No       | `ethereum` (default) or `base`            |
| `page`        | No       | Page number (default: 1, 10 txs per page) |

## Example Output

```
Transaction Activity for 0xUser...
Page 1 of 15 (10 transactions per page)

1. 2024-01-15 14:32:00
   Function: swap(...)
   To: Uniswap V3 Router
   Balance Changes:
     - Sent: 1,000 USDC
     - Received: 0.35 WETH
   Gas: $4.52

2. 2024-01-15 10:15:00
   Function: approve(...)
   To: USDC Contract
   Balance Changes: None
   Gas: $2.11

3. 2024-01-14 22:45:00
   Function: deposit(...)
   To: Aave V3 Pool
   Balance Changes:
     - Sent: 5,000 USDC
     - Received: 5,000 aUSDC
   Gas: $6.78

...
```

## Filtering by Destination

To see only interactions with a specific contract:

**You:** "Show me all transactions from 0xUser to Uniswap"

This uses the `toAddress` parameter to filter results.

## Use Cases

**Wallet investigation:**

```
What has this wallet been doing in the last week?
```

**Protocol usage:**

```
How does this user interact with Aave?
```

**Trading analysis:**

```
Show me the trading activity of this MEV bot
```

## Pagination

For addresses with many transactions:

**You:** "Show me page 3 of transactions for 0x..."

```
Transaction Activity for 0xUser...
Page 3 of 15

21. 2024-01-10 ...
22. 2024-01-10 ...
...
30. 2024-01-09 ...

Showing transactions 21-30 of ~150
```

## Balance Changes Explained

Each transaction shows what moved:

```
Balance Changes:
  - Sent: 1,000 USDC (to 0xPool)
  - Received: 0.35 WETH (from 0xPool)
  - Received: 50 UNI (airdrop claim)
```

<Note>
  Only shows balance changes where the queried address is the holder. For complete transaction breakdown, use `queryTransactionTool`.
</Note>

## Contract Creations

When an address deploys contracts:

```
Transaction: 0xabc...
Type: Contract Creation
Created: 0xNewContract (MyToken)
Verified: Yes
```

## Common Use Cases

<AccordionGroup>
  <Accordion title="Due diligence on a wallet">
    "Give me an overview of this wallet's activity over the past month"
  </Accordion>

  <Accordion title="Finding specific transactions">
    "When did this wallet last interact with Compound?"
  </Accordion>

  <Accordion title="Analyzing trading patterns">
    "What DEXs does this wallet use most?"
  </Accordion>

  <Accordion title="Tracking protocol deployments">
    "What contracts has this deployer wallet created?"
  </Accordion>
</AccordionGroup>

## Combining with Other Tools

For comprehensive analysis:

1. **Get wallet overview** → `getWalletOverviewTool`
2. **Check transaction history** → `getTransactionActivityTool`
3. **Deep dive specific tx** → `queryTransactionTool`
4. **Check token holdings** → `getTokenActivityTool`

## Tips

<Tip>
  Filter when possible—use `toAddress` to focus on specific protocols.
</Tip>

<Tip>
  Ask for summaries: "Summarize this wallet's DeFi activity"
</Tip>

## Limitations

<Warning>
  **10 transactions per page.** Use pagination for full history.
</Warning>

<Warning>
  **Only shows outgoing context.** Balance changes are relative to the fromAddress. Use `queryTransactionTool` for complete transaction details.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Query Transaction" icon="receipt" href="/herd-mcp/tools/query-transaction">
    Get full details on any transaction
  </Card>

  <Card title="Wallet Overview" icon="wallet" href="/herd-mcp/tools/wallet-overview">
    Get complete wallet profile
  </Card>
</CardGroup>


# Wallet Overview
Source: https://docs.herd.eco/herd-mcp/tools/wallet-overview

Wallet type detection, token balances, and activity metrics

# Wallet Overview

Returns wallet type, token balances, and activity data for any address.

## Returns

* **Wallet Type** - EOA, multisig, smart wallet, or delegated account
* **Token Balances** - Holdings with USD values
* **Activity** - Transaction count, deployed contracts
* **Multisig Details** - Signers and pending transactions (for Safes)
* **ERC-7702** - Implementation address for delegated EOAs

## Example Queries

```
Give me an overview of vitalik.eth
```

```
What tokens does 0x... hold?
```

```
Is this wallet a multisig? Who are the signers?
```

## Parameters

| Parameter       | Required | Description                    |
| --------------- | -------- | ------------------------------ |
| `walletAddress` | Yes      | The wallet address (0x...)     |
| `blockchain`    | No       | `ethereum` (default) or `base` |

## Wallet Types Detected

| Type         | Description                                      |
| ------------ | ------------------------------------------------ |
| **EOA**      | Externally Owned Account (regular wallet)        |
| **ERC-7702** | EOA with delegated code (smart account features) |
| **ERC-4337** | Smart contract wallet (Account Abstraction)      |
| **Multisig** | Safe or similar multi-signature wallet           |
| **Contract** | Other smart contract                             |

## Example Output

### Regular Wallet (EOA)

```
Wallet Overview: 0xUser...
============================
Type: EOA (Externally Owned Account)
Chain: Ethereum

Balances:
┌──────────────┬─────────────────┬────────────────┐
│ Token        │ Balance         │ USD Value      │
├──────────────┼─────────────────┼────────────────┤
│ ETH          │ 15.234          │ $48,234.56     │
│ USDC         │ 25,000.00       │ $25,000.00     │
│ WETH         │ 5.000           │ $15,825.00     │
│ UNI          │ 1,500.00        │ $12,750.00     │
│ AAVE         │ 100.00          │ $8,500.00      │
└──────────────┴─────────────────┴────────────────┘

Total Portfolio Value: ~$110,309.56

Activity:
- Transaction Count: 1,245
- Contracts Deployed: 3
- First Transaction: 2021-03-15
```

### Multisig Wallet (Safe)

```
Wallet Overview: 0xTreasury...
==============================
Type: Multisig (Gnosis Safe)
Chain: Ethereum
Threshold: 3 of 5 signers

Signers:
1. 0xSigner1... (EOA)
2. 0xSigner2... (EOA)
3. 0xSigner3... (EOA - also a contract signer)
4. 0xSigner4... (EOA)
5. 0xSigner5... (EOA)

Pending Transactions: 2
- Tx #45: Transfer 100 ETH to 0x... (2/3 signatures)
- Tx #46: Upgrade contract 0x... (1/3 signatures)

Balances:
┌──────────────┬─────────────────┬────────────────┐
│ Token        │ Balance         │ USD Value      │
├──────────────┼─────────────────┼────────────────┤
│ ETH          │ 5,000.00        │ $15.8M         │
│ USDC         │ 10,000,000.00   │ $10.0M         │
│ ...          │ ...             │ ...            │
└──────────────┴─────────────────┴────────────────┘

Total Portfolio Value: ~$45.2M
```

### Smart Wallet (ERC-4337)

```
Wallet Overview: 0xSmartWallet...
=================================
Type: ERC-4337 Smart Account
Implementation: Biconomy Smart Account v2
Chain: Ethereum

Features:
- Batch transactions
- Gasless transactions (paymaster support)
- Social recovery enabled

Balances: [similar to above]
```

### Delegated EOA (ERC-7702)

```
Wallet Overview: 0xDelegated...
===============================
Type: ERC-7702 Delegated EOA
Delegation: Active
Implementation: 0xImpl... (Coinbase Smart Wallet)

Delegated Functions:
- execute(address,uint256,bytes)
- executeBatch(...)
- supportsInterface(bytes4)

Balances: [similar to above]
```

## Use Cases

| Task            | Query                                        |
| --------------- | -------------------------------------------- |
| Check control   | "Is this wallet a multisig?"                 |
| Portfolio value | "Total value of tokens in this wallet?"      |
| DAO treasury    | "Details on the Uniswap governance treasury" |

## Related Tools

1. **Start with overview** → `getWalletOverviewTool`
2. **Check specific tokens** → `getTokenActivityTool`
3. **View transactions** → `getTransactionActivityTool`
4. **Check deployments** → `getDeployedContractsTool`

## Tips

<Tip>
  ENS names work: "vitalik.eth" resolves automatically
</Tip>

<Tip>
  Be specific: "Is this a fresh wallet?" or "How active is this wallet?"
</Tip>

## Common Questions

<AccordionGroup>
  <Accordion title="What if the wallet has many tokens?">
    The overview shows the most valuable holdings. Ask for "all tokens" to see the complete list.
  </Accordion>

  <Accordion title="How current are the balances?">
    Balances reflect the latest indexed block, typically within seconds of real-time.
  </Accordion>

  <Accordion title="Can I see NFTs?">
    Yes, NFT holdings are included with floor price estimates where available.
  </Accordion>
</AccordionGroup>

## Limitations

<Warning>
  **USD values are estimates.** Based on current market prices and may fluctuate.
</Warning>

<Warning>
  **Some tokens may not have prices.** Low-liquidity or new tokens might show \$0 value.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Token Activity" icon="coins" href="/herd-mcp/tools/token-activity">
    Track specific token movements
  </Card>

  <Card title="Transaction Activity" icon="list" href="/herd-mcp/tools/transaction-activity">
    See full transaction history
  </Card>
</CardGroup>