Use contract.dev from your agent
An agent reads and acts on a workspace through the toolkit: 22 typed tools behind one API, wrapped by the CLI. Everything the agent can see is the workspace’s watched contracts.
Requires contract-dev login or an API key.
Keys
Every route takes an API key: Authorization: Bearer <key>. Mint one under APIs in the app, or let contract-dev login mint it. A key carries scopes and an optional expiry of 30 days, 90 days or never.
| Scope | Allows |
|---|---|
read | Every read tool |
contracts:write | watch_contract |
metrics:write | track_metric |
monitors:write | create_monitor |
reports:write | create_report, run_report |
slots:read | Storage-slot lookups on the public API |
A key for an agent gets read plus only the write scopes the agent is meant to use.
Tools
GET /api/mainnet/tools lists every tool with its name, description and input schema. POST /api/mainnet/tools/<name> with { "input": { … } } runs one and answers { "ok": true, "result": … } or { "ok": false, "error": "…", "code": "…" }.
| Tool | |
|---|---|
find | Resolve a name, address, group or kind word (pools) to what the workspace holds. |
list_contracts | Watched contracts with inferred kinds: pool, vault, token, nft, proxy. |
describe_contract | What a contract is, its events and functions, what it calls, its Chainlink feeds. |
list_events | Event names and counts in a scope. |
dependencies | The contracts and price feeds a contract reads. |
top_counterparties | Who moved the most value in or out, in USD. |
holdings | TVL now and its split. |
positions | Positions in Aave v3, Morpho Blue, Compound v3, Euler, Curve Lend, Fraxlend and ERC-4626 vaults. |
list_monitors | Monitors and their states. |
list_alerts | Alert episodes. |
list_destinations | Where alerts and reports go. |
get_metrics | A metrics table for a scope: the period, its change, the longer windows. |
compare_activity | Rank the contracts in a group by a measure, with change. |
query_activity | Events, transactions or distinct wallets per contract per day. |
compile_monitor | Words in, the exact monitor out, with a 7-day backtest and the sentence it will print. |
create_monitor | Save the monitor compile_monitor described. |
track_metric | Start tracking a value on a watched contract. |
watch_contract | Watch a contract. |
preview_report | The table a report would send, computed now, saved nowhere. |
create_report | Save a scheduled report. |
run_report | Send a saved report now. |
list_reports | Saved reports, their schedules and last runs. |
The CLI wraps the same list:
contract-dev tool list
contract-dev tool show compile_monitor
contract-dev tool run find --input '{ "query": "pools" }'The common tools have a command of their own: find, describe, compare, activity query, monitor compile, monitor add --event, report preview, report create. Every command takes --json.
Pattern
- Find, then read, then act.
findturns a name, address, group or kind into the things the workspace holds; the read tools take what it returns; the write tools come last. - Compile before create.
compile_monitorreturns the sentence a monitor will print and how often it would have fired in the last 7 days.create_monitortakes the same input once the sentence is right. - Preview before create.
preview_reportprints the table a report would send;create_reportsaves it. - Watched contracts only. The agent never sees data outside the workspace’s watched contracts, and a contract must be watched before anything else can read it.
Examples
Which of our pools had the most swaps this week
contract-dev find pools
contract-dev compare --group pools --by events --event Swap --window 7dfind lists the watched contracts that behave like pools, with chain, address and group. compare ranks them by Swap count over 7 days, each row beside its previous-window count and the change.
Tell me when a trade over 10,000 USDC lands on the ETH/USDC pool, and who sent it
contract-dev monitor compile --on "ETH/USDC pool" --event Swap --where "amount0 at least 10000" --to slackSwap is emitted where amount0 is at least 10,000 USDC
Would have fired <n> times in 7 daysThe newest firings follow, each with its transaction, time, sender and arguments. Nothing is saved. When the sentence is right, monitor add with the same flags creates the monitor:
contract-dev monitor add --on "ETH/USDC pool" --event Swap --where "amount0 at least 10000" --to slackEach alert names the transaction it came from.
Send me active wallets, transactions and TVL every morning at 9
contract-dev report preview --template daily
contract-dev report create --template daily --to slack --at 9 --tz Australia/Sydneyreport preview prints the table the daily template sends: active wallets, transactions, TVL and the template’s other rows for the last 24h, with the change against the day before. report create saves it; it sends at 09:00 in the given zone.
Set up your agent
npm install -g @contract-dev/cli
contract-dev loginLogin ends by offering the agent skill: the instructions that let Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot use the CLI for you, including setting up a protocol. Press Enter to install it. Later, or on another machine:
contract-dev skills install # for every project on this machine
contract-dev skills install --project # in this repository, to commit for the team
contract-dev skills statusThen ask your agent, in your protocol’s repository: “set up our protocol on contract.dev”. Upgrading the CLI refreshes the skill on the next command. Before uninstalling the CLI, run contract-dev skills uninstall.
Limits
- A window longer than the workspace’s history reads as the window it has; every answer names the window it served.
- Activity — calls, events, counterparties and backtests — covers Ethereum, Avalanche and Sepolia.
- Thresholds are in the field’s units (
10000on a USDC amount is 10,000 USDC), never dollars. A threshold in dollars is refused. - A question outside the watched contracts gets an answer that says so:
… is not a watched contract in this workspace. Watch it first (watch_contract).