Ask and Explore
Questions over the workspace, and lookups of any transaction, address, block or verified source on a supported chain.
Requires contract-dev login. <contract> is a watched contract’s address or name; describe, events <contract> and holders refuse an address the workspace does not watch. Add --json for the full answer.
find <query>
What a name points at: contracts (by name, address or a kind word: pools, vaults, tokens, nfts, proxies), groups, metrics, notifications, destinations.
contract-dev find pools
contract-dev find stethEach kind of match prints as its own table. Metrics are listed with the group, contract or table they are on.
describe <contract>
What a watched contract is: kinds, standards, groups, owner, implementation, token; its events and write functions. Each event field’s token is shown as checked against the contract’s own transactions, for the token to name in a formula.
contract-dev describe steth [--chain <id|name>]query <dataset>
Ask one dataset a question in the table language.
contract-dev query <dataset> [scope flags] [clauses]| Dataset | Rows | Scope flags |
|---|---|---|
contracts | The watched contracts, with a group’s columns. | [--group <g>] [--chain <id>] [--kind pool|vault|token|…] [--read …] [--series …] |
table "<name>" | A table’s rows: an activity table’s (its own --where carried in), a state table’s, or a metric’s records, one row per event. | [--days <n>] (event rows, default 7) [--among active|done|all] (state tables, default active) |
metric "<name>" | What is behind a metric: its records or readings. | [--days <n>] |
metrics --metric "<name>"… | Metrics split the same way, side by side: one row per split value (an integrator, a sender, a contract), one column per metric’s total. | [--split contract|<param>] [--days <n>] |
monitors | The workspace’s monitors. | |
alerts | Its alerts. | [--days <n>] |
reports | Its reports. | |
transactions | The transactions that reached the contracts, or a watched wallet sent and received, newest first. | [--group <g> | --contract <c>] [--days <n>] [--signer <0x>] [--failed] [--direct | --routed] [--before <time>] |
transfers | What moved in and out of them, each leg priced on its day. | [--group <g> | --contract <c>] [--days <n>] [--in | --out] [--token <symbol|0x|native>] [--counterparty <0x>] [--signer <0x>] [--before <time>] |
wallets | The wallets behind them: new or returning, first and last seen, dollars in and out. | [--group <g> | --contract <c>] [--days <n>] [--signer <0x>] |
--contract takes a watched contract or a watched wallet, by name or address: a wallet’s transactions are the ones it sent and received, its transfers the legs naming it. --signer keeps one address’s own transactions within the scope. --before <time> pages transactions and transfers further back: the window counted back from that time, which the answer’s More: --before … line gives.
On transactions, transfers and wallets, a --by on day, contract, wallet, counterparty, token, status or via, with --count, --sum "{Value}" or --sum "{USD}", is exact over the whole window at any size.
Clauses
Clauses work on any dataset, except --column and --detail, which list event rows: a table’s or a metric’s. Columns are named by label in braces or by key.
| Clause | Description |
|---|---|
--where "<expr>" | Keep the rows this holds for: --where "{Held} < {Required}". |
--show <name>="<expr>" | A worked-out column, usable by the other clauses: --show headroom="{Held} - {Required}". Repeat for more. |
--sort "<expr>" [--asc] | Rank the rows, largest first. With --by: rank the groups by a measure (default the first). |
--by <a,b> | Fold the rows into groups, with one of --count, --sum, --avg, --min, --max, --distinct, --first or --last "<expr>". |
--measure <name>="<fn>(<expr>) [where <rule>]" | With --by, in place of a single measure: several values per group, each a column by its name. Repeat it. fn is count, sum, avg, min, max, distinct (how many different values), first or last (on the group’s earliest or latest row). where counts or adds only its rows. |
--having "<expr>" | With --by: keep the groups this holds for, over their columns and measures by name. |
--breakdown <column> | With --by: split each group again, its parts listed under it, largest first, with a column counting them. |
--total <a,b> | Add these columns up over every matching row. |
--limit <n> | Rows or groups to print. Default 25; the answer says how many matched. |
--top <n> | The n largest: with --by, the groups by their first measure; otherwise the rows by --sort. Not with --limit or --asc. |
--column <name> | Event rows listed, not folded: a column to show, in order. Repeat it; only those show. A field, a parameter, or the row’s own time, day, tx, chain, contract, event or wallet. |
--detail <name> | A column each row opens onto, one line per item of a list field, printed under the row. |
--status "<Label>: <Opt>=<rule>; <Opt>" | A category on each row, usable by name in the other clauses. Its options are tried in order; the last may have no rule. |
contract-dev query transactions --group "Wildcat markets" --days 30 --by day --count
contract-dev query transfers --contract Treasury --out --days 30 --by counterparty --sum "{USD}"
contract-dev query wallets --group "Wildcat markets" --days 7 --where '{Status} == "new"'
contract-dev query transactions --signer 0x1234…abcd --days 90
contract-dev query table "Withdrawal rounds" --where '{Stage} == "Paying" and age > 7d' --sort "{Outstanding}"
contract-dev query metric Deposits --days 30 --by day --sum "{value}"
contract-dev query metric "Swap volume" --by wallet --sum "{Value}" --breakdown chain
contract-dev query metrics --metric "DZap bridges" --metric "DZap swaps" --metric "DZap swap volume" --split integrator
contract-dev query alerts --days 30 --by monitor --countReads on contracts
query contracts --read reads a figure on every contract now, or as it was then.
| Form | Example |
|---|---|
<name>=<view()> [in <token>] [as usd|amount] | --read cov="coverageLiquidity() in asset()" |
… at <time> (7d, 24h, 2w, or a UTC date) | --read bal7="balanceOf(0x…)(uint256) in asset() at 7d" |
| One of several outputs, with arguments | --read n="getConnectedGardens(uint256,uint256).total with 0, 1" |
<name>=<expression> over earlier reads and the group’s columns | --read gap="held - cov" |
--series <from>[..<to>] [--every 1h|6h|1d|1w] reads every --read at each step over a window: one row per time per contract.
contract-dev query contracts --group "Wildcat markets" --show headroom="{Held} - {Required}" --where "headroom < 0" --sort headroom --asc
contract-dev query contracts --group "Wildcat markets" --read cov="coverageLiquidity() in asset()" \
--read held="totalAssets() in asset()" --read gap="held - cov" --sort gap --asc
contract-dev query contracts --group Vaults --read sp="convertToAssets(1000000000000000000)" \
--read sp7="convertToAssets(1000000000000000000) at 7d" --show apr="(sp - sp7) / sp7 * 52" --sort apr
contract-dev query contracts --group Vaults --read sp="convertToAssets(1000000000000000000)" --series 30d --every 1dTo keep a question as a table, see table create.
events [<contract>]
Every event fired in the window, event by event, with how many times each fired.
contract-dev events [<contract>] [--range 24h|7d|30d|90d] [--chain <id|name>] [--limit <n>]| Flag | Description |
|---|---|
--range | The window: 24h (default), 7d, 30d or 90d. --window reads the same. |
--chain <id|name> | One chain. |
--limit <n> | Rows to print. Default 25. |
contract-dev events USDCUSDC · Ethereum · events · last 24h
20,515 events fired · 2 kinds
Event Fired
Transfer 18,204
Approval 2,311events --event <Name>
The events themselves, worked through formulas in the language of metric define.
contract-dev events [<contract> | --group <group> | --address 0x… --chain <id>] --event <Name> [--event …] [--chain <id|name>]
[--read "<name>=<call> [on <target>] [with <arg>, …]"]… [--fixed <read>]…
[--show "<name>=<expr>"]… [--where "<expr>"] [--sort "<expr>" [--asc]]
[--by contract|day|week|sender|<name>]… [--sum|--avg|--min|--max "<expr>" | --count]
[--window 1h|24h|7d|30d|90d|365d] [--limit <n>]| Flag | Description |
|---|---|
--sort "<expr>" | Rank the events, largest first. Newest first without it. |
--by … | Group them; --sum, --avg, --min, --max or --count adds each group up. Without --by, the whole window is one total. |
--address 0x… | Read a contract the workspace does not watch (a position manager, a factory, a pool). Narrow it with a --where equality on an indexed field (to == 0x…), or keep --window to 7d at most. With no verified ABI, write the event as its full signature. |
Tokens are named in the formula: usd(raw, token), amount(raw, token), the token an address, a read or a parameter. Each event is priced on its own day. Each listed event says who made it: the wallet (a smart account when there is one), the signer it came via, a searcher bot.
A --sort on a field, abs(), usd() or amount() of one, or max() of those, with no --where, ranks the whole window. Any other reads the newest 10,000 events (1,000 with a read per transaction) and says where it started.
contract-dev events 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640 --event Swap --read "t0=token0()" --fixed t0 \
--sort "usd(abs(amount0), t0)" --limit 10
contract-dev events --group "Wildcat markets" --event Deposit --read "a=asset()" --fixed a \
--where "usd(assetAmount, a) > 100000" --show "usd=usd(assetAmount, a)"
contract-dev events --group "Uniswap v3" --event Swap --read "t0=token0()" --fixed t0 \
--by contract --by day --sum "usd(abs(amount0), t0)" --window 7d
contract-dev events --address 0xC36442b4a4522E871399CD717aBDD847Ab11FE88 --chain 1 --event Transfer \
--where "to == 0xMYWALLET" --window 90dhistory
Every firing of some events since launch: counts by event and contract, a timeline, top and repeat wallets, the weekday and hour shape, the first, last, newest and largest firings.
contract-dev history [<contract> | --address 0x… --chain <id>] --event <Name> [--event <Name>]… [--group <group>] [--chain <id|name>]
[--window all|24h|7d|30d|90d|1y | --since <date>] [--until <date>]
[--by auto|day|week|month] [--tz <zone>] [--who <field>|signer]
[--read "<name>=<call>"]… [--value "<formula>"]
[--wallet 0x…] [--limit <n>] [--once]| Flag | Description |
|---|---|
--value "<formula>" | What each firing is worth: a formula in the language of events over the event’s fields and --read views. Adds the spread of those values (total, quartiles, dollar buckets when the formula prices them, each firing at its own day’s price) and each contract’s and wallet’s total. |
--read "<name>=<call>" | A view read once per contract: an answer that never changes, like asset() or token0(). |
--who <field> | Count by an address field of the event (account, owner). By default, the transaction’s signer. |
--by | The timeline’s period: auto (default: days up to 45 days, weeks up to a year, else months), day, week or month. |
--tz <zone> | The IANA zone the days, weeks and hours are cut in. Default UTC. |
--address 0x… | Read a contract the workspace does not watch. Narrow it with --who naming an indexed address field and --wallet 0x…, or keep --window to 30d at most. With no verified ABI, write the event as its full signature. |
--once | Stop after one call. A long history is read over up to three. |
A window longer than the workspace’s history is served from where that history starts.
contract-dev history --group "Wildcat markets" --event WithdrawalQueued --read "a=asset()" \
--value "usd(normalizedAmount, a)" --who account --by week
contract-dev history 0x5ab22e9c360807f16dfa34ad5c589055d2871a5b --event WithdrawalQueued --event WithdrawalExecuted --tz Australia/Sydney
contract-dev history --group pools --event Swap --window 30d --who signer
contract-dev history --address 0xC36442b4a4522E871399CD717aBDD847Ab11FE88 --chain 1 --event Transfer --who to --wallet 0xMYWALLETholders <contract>
A token’s holders: how many hold it, the largest, how concentrated.
contract-dev holders <contract> [--chain <id|name>] [--limit <n>]--chain picks between the same name watched on several chains. --limit sets the holder rows printed: default 15, at most 25.
who <address|ENS|name>
Who it is: its name, kind, and the contracts it touches here.
contract-dev who Wintermute [--chain <id|name>] [--limit <n>]read <contract> <function> [<arg>…]
Call a view function, now or at a past block.
contract-dev read <contract> <function> [<arg>…] [--chain <id|name>] [--decimals <n>] [--at <date|time> | --block <n>]
contract-dev read "Withdrawal Queue" unfinalizedStETH --decimals 18
contract-dev read USDC balanceOf 0xTreasury… --decimals 6 --at 2026-10-01To read a lending market’s rates or utilisation, see how it computes them with source, then read the functions.
Explorer
Any transaction, address or block on a supported chain, and a contract’s verified source.
contract-dev tx <hash> [--chain <id|name>]
contract-dev address <0x…> [--chain <id|name>] [--limit <n>]
contract-dev block <number> --chain <id|name> [--limit <n>]
contract-dev wallet <0x…> [--chain <id|name>] [--approvals]
contract-dev source <contract|0x…> [--chain <id|name>] [--out <dir>]| Command | Shows |
|---|---|
tx | A transaction: outcome, decoded call, fees, transfers, logs. Without --chain it looks on every chain the CLI names. |
address | Balance, what it is, its recent transactions. A Chainlink feed says what it reads now and its published terms. Needs --chain unless the workspace watches the address on one chain. |
block | A block and its transactions. Needs --chain. |
wallet | A wallet’s transactions. Without --chain it reads most chains; name Katana, Ink, Scroll, Morph, Soneium, ZKsync Era, Flare, Tempo, Boba, Rootstock, opBNB, Mode, Citrea or ZetaChain with --chain. --approvals lists its open approvals instead. |
source | A contract’s verified source: its writes and reads. --function <name> prints one function in full; --out <dir> writes the files. Without --chain it uses a watched contract’s chain or looks the address up; with --out, an address the workspace does not watch needs --chain. |
contract-dev tx 0x5d1c8a0e7f2b4c6d9e3a1b8f0c7d2e5a4b6c9d1e8f0a3b2c5d7e9f1a4b6c8d0e
contract-dev block 21000000 --chain ethereum
contract-dev wallet 0x4b2e8f1a6c9d3e7b5a0f2c8d1e6b9a3f7c5d0e21 --approvals
contract-dev source "Withdrawal Queue" --out ./src/withdrawal-queue