@sperax/tool-contract-explorer

Inspect, read, and decode any verified EVM smart contract. Fetch ABIs, call view functions, stream events, and decode transactions.

Contract Explorer is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-contract-explorer

Usage

Call it directly

import { contractExplorerExecutor } from '@sperax/tool-contract-explorer';

const result = await contractExplorerExecutor.invoke('getContractABI', {"address":"<address>","chain":"<chain>"}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { ContractExplorerManifest, contractExplorerExecutor } from '@sperax/tool-contract-explorer';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: ContractExplorerManifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await contractExplorerExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

ContractExplorerManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-contract-explorer

API reference

getContractABI

Fetch the verified ABI for a smart contract. Returns all callable functions and events with their signatures. Use this first before readContract.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | EVM contract address (0x…) | | chain | string | no | Chain name: ethereum, arbitrum, polygon, base, optimism, avalanche, bsc. Defaults to ethereum. |

readContract

Call a view or pure function on a smart contract and return the on-chain result. The contract must be verified. Use getContractABI first to find available functions.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | EVM contract address (0x…) | | args | array | no | Arguments for the function call as an array of strings | | chain | string | no | Chain name: ethereum, arbitrum, polygon, base, optimism, avalanche, bsc. Defaults to ethereum. | | functionName | string | yes | Name of the view/pure function to call (e.g. "totalSupply", "balanceOf", "owner") |

getContractEvents

Fetch recent event logs emitted by a smart contract. Optionally filter by event signature.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | EVM contract address (0x…) | | chain | string | no | Chain name: ethereum, arbitrum, polygon, base, optimism, avalanche, bsc. Defaults to ethereum. | | eventSignature | string | no | Optional: filter by event signature topic (e.g. "Transfer(address,address,uint256)") | | limit | number | no | Max number of events to return (default 10) |

decodeTransaction

Decode a transaction hash — shows which contract function was called, with what arguments, and the ETH value sent.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | no | Chain name: ethereum, arbitrum, polygon, base, optimism, avalanche, bsc. Defaults to ethereum. | | txHash | string | yes | Transaction hash (0x…) |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-contract-explorer is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0