Conductor docs

Overview#copy link

Conductor runs the work your v4 hook can't: keeper jobs for Uniswap v4 hooks on Robinhood Chain (chainId 4663), run by operators inside rules the hook's owner sets on chain, with an open indexer underneath. Hooks and automations: see the next sections. Data layer: register an address, then read holders, balances, transfers and decoded events over HTTP, subscribe to signed webhooks, and export holder snapshots at any indexed block.

Base URL: the API host, or this website, which proxies /v1/* to it. Locally the API listens on http://127.0.0.1:8787. JSON in, JSON out, except the CSV snapshot.

export LATTICE="http://127.0.0.1:8787"
curl -s "$LATTICE/v1/health"

Every request on this page comes in three forms (curl, the TypeScript SDK, the lattice CLI) generated from one definition, pointed at this site's origin. Pick a form once and every example follows. Read routes have a Try it panel that sends the real request to this site's /v1 and shows the answer.

Conventions#copy link

Errors#copy link

{ "error": { "code": "not_found", "message": "contract 0xabc... is not registered" } }

Auth and limits#copy link

• Reads need no auth.
• Writes (POST /v1/contracts and every /v1/webhooks route) take x-api-key: <key> when the operator configures keys. With no keys configured, writes are open.
• POST /v1/contracts also works without a key when public registration is on (the default), limited to 5 per minute per IP. The register form on /data uses this.
• Webhooks are scoped to the key that created them: list, get, patch and delete only see your own.
• Reads: 300 requests per minute per IP. Requests with a valid key are exempt.

Keeper jobs for v4 hooks#copy link

Conductor runs the work your v4 hook can't. A hook only wakes up inside a swap or a liquidity call. It cannot read the clock, rebalance, refresh an oracle, step a dynamic fee, claim its own fees or pay anyone out on a schedule. Conductor's operators do that, inside rules the hook's owner sets on chain, with every run recorded.

A keeper job is an ordinary automation task: a trigger, a list of calls, and the policy that bounds them. What makes it hook-aware is the trigger: it can read the pool's state through the UniswapV4PoolChecker and wake on the pool's events through an event marker.

• The hook's owner (or the project behind it) owns the Automation contract and its policy.
• Operators watch the pool, simulate the job, and submit execute; the contract rejects any call the policy does not allow.
• Every run is recorded with its trigger, transactions and balance changes, like any other run.

The v4 pool checker#copy link

UniswapV4PoolChecker reads getSlot0(poolId) and getLiquidity(poolId) from the v4 StateView. A task sets it as trigger.checker with checkerData = abi.encode(PoolCondition), where PoolCondition is { mode, poolId, tickLower, tickUpper, liquidityThreshold }. When it is ready its payload is abi.encode(tick, sqrtPriceX96, liquidity, lpFee).

• A pool that was never initialised (sqrtPriceX96 == 0) is not ready in any mode except Any.
• The range modes revert InvalidRange() when tickLower >= tickUpper.
• Task eligibility for these tasks carries { tick, sqrtPriceX96, liquidity, lpFee, poolId, mode, inRange }.

Event markers#copy link

Markers are off-chain wake-ups: trigger.eventMarker is the keccak256 of the marker string, and the worker re-checks the task as soon as a matching PoolManager event is indexed instead of waiting for the next interval. The task's pool is the poolId in its PoolCondition; a v4 marker on a task with another checker is ignored.

Hook job templates#copy link

The build console at /app/new and GET /v1/workflows list these. Planned templates describe the shape they will ship with; until then, start from a blank automation and add the task by hand.

Hooks and pools API#copy link

Read-only, no key. The indexer mirrors the PoolManager's Initialize, Swap and ModifyLiquidity events into hooks and pools. A hook's flags are the low 14 bits of its address; permissions spells them out (beforeInitialize is bit 13, afterRemoveLiquidityReturnDelta bit 0).

GET/v1/hooks?limit=&cursor=#copy link

GET/v1/hooks/:address#copy link

GET/v1/pools?hook=&limit=&cursor=#copy link

GET/v1/pools/:poolId#copy link

How automation works#copy link

Tell your contract what to do, and when. Each project owns an Automation contract: the policy (which calls it may make, which assets may move, to whom, how much per epoch) and its tasks. Conductor's operators watch the triggers, simulate, and submit execute; the contract rejects anything outside the rules. Every run is recorded.

• Writes never come from Conductor: the API returns transactions (TxRequest) and your wallet signs them.
• Pause, revoking an operator, deactivating a task, withdrawing and tightening the policy are always immediate.
• The owner can always exit: withdraw and ownerCall ignore pause, policy and timelock.

Policy and limits#copy link

A call made by execute is allowed only if its (target, selector) is permitted, it sends ETH only where allowValue is set, its validator (if any) accepts it, and any token transfer/approve goes to an allowed recipient. The Universal Router is only reachable through the UniversalRouterV4Validator, which accepts one exact-in v4 swap whose output returns to the automation.

Every tracked asset (up to 16, ETH first) is measured before and after each call. Gross outflow is charged against a per-asset cap per epoch. Epochs are fixed windows aligned to unix time: a 7-day epoch resets every Thursday 00:00 UTC. Around a boundary up to 2x the cap can move in a short time (end of one epoch, start of the next). Cap 0 = inflow only; uint256 max = uncapped but tracked.

The timelock is optional and defaults to 0. It cannot protect the owner from themselves; it is a public promise to holders that the rules cannot be loosened without notice (max 30 days).

Operator fees#copy link

Paid in ETH from the automation to the operator at the end of an execute in which at least one step succeeded: gasUsed x min(gasprice, maxGasPrice) x (1 + premium) + L1 fee + flat fee, then capped by the per-execute cap, the task's per-run cap, the per-epoch fee budget and the automation's balance. The fee never reverts a run.

Keep some ETH in the automation: when its balance is below one run's max fee, or the fee budget is used up, the dashboard asks for a deposit (a plain ETH send to the automation).

Tasks, triggers and runs#copy link

A task is up to 16 steps; each step is one call template plus up to 8 slots. Every byte outside a slot is fixed by the owner. Slots are filled at run time: by the contract (a balance, the run's inflow, now + N, a copy of another slot) or, only for OPERATOR slots, by the operator within the owner's bounds (e.g. a swap's minimum output).

Atomic tasks run in one transaction: a failing required step reverts everything and nothing is charged. allowFailure steps (sweeps, claims) may fail without stopping the run. Run states: pending -> simulating -> submitted -> succeeded | failed; submitted -> stuck (no receipt after gas bumps; the dashboard says recovering) -> resubmitted or failed; skipped when not eligible.

The policy engine#copy link

Every run goes through one function, Automation.execute(taskId, resolvedCalls). The operator proposes the calls; the contract binds them to the owner's template, checks each final call against the policy, measures what moved, charges the allowances and pays a capped fee. Anything outside the rules reverts the whole transaction.

What an operator can choose: when to run (within the trigger), OPERATOR slot values within the owner's bounds (e.g. a swap's minOut), skipping allowFailure steps, and stopping a stepped run. What it cannot: change a target, selector, recipient or any template byte, add calls, or move more than the allowances.

Loosening and tightening#copy link

Every policy change is a PolicyUpdate{op, data}. Tightening applies at once. Loosening applies at once when policyDelay is 0; otherwise updatePolicy reverts LooseningRequiresTimelock(index) and the owner queues it: queuePolicyUpdate, then executeQueuedPolicyUpdate at or after the eta (max delay 30 days). Pause, revoke, deactivate and withdraw are never delayed.

Deployed contracts#copy link

Robinhood Chain, chainId 4663. The factory row is checked against what this site's API reports in GET /v1/automation-stats. Per-launch pons curve and token addresses are never listed: they are read from ponsV2Factory.getLaunchedToken(token).

The workflow#copy link

Template pons-rewards/v1: whenever your pons v2 project has earned enough creator fees, claim them, swap the ETH to the reward token on its graduated Uniswap v4 pool, and fund your rewards contract. The automation itself becomes the creator fee recipient.

Activation#copy link

The rule builder previews the plan as you type, then simulates it against the chain with nothing deployed. Activation is blocked until the simulation passes. Then you sign, in order:

• Create the automation with the policy and the task (factory.createAutomation), or for an existing automation updatePolicy then createTask.
• Claim what is already credited to you (escrow.claim()): credited fees do not move with the recipient.
• Hand the fees to the automation: ponsFactory.transferCreatorFeeRecipient(feeToken, automation), signed by the current fee recipient.

Undo at any time: the owner calls ownerCall with transferCreatorFeeRecipient(feeToken, ownerWallet) and withdraws.

Reads#copy link

Public, no key. Lists are { data, next } with cursor pagination like every other route. Without deployed contracts every route below except /v1/automation-stats and /v1/workflows answers 503 not_configured. A freshly created automation can be 404 for a few seconds while the mirror catches up. Try it fills automation and run ids from the newest ones the API knows.

GET/v1/automation-stats#copy link

curl -s "http://127.0.0.1:8787/v1/automation-stats"

GET/v1/automations?owner=&template=&paused=&limit=&cursor=#copy link

curl -s "http://127.0.0.1:8787/v1/automations?owner=0x3d8a0670d278c125966f884dc66bea34944a4220&limit=10"

GET/v1/automations/:address#copy link

curl -s "http://127.0.0.1:8787/v1/automations/0x5b1f000000000000000000000000000000000000"

GET/v1/automations/:address/tasks[/:taskId]#copy link

curl -s "http://127.0.0.1:8787/v1/automations/0x5b1f000000000000000000000000000000000000/tasks"

curl -s "http://127.0.0.1:8787/v1/automations/0x5b1f000000000000000000000000000000000000/tasks/0"

GET/v1/automations/:address/runs?taskId=&status=&limit=&cursor=#copy link

curl -s "http://127.0.0.1:8787/v1/automations/0x5b1f000000000000000000000000000000000000/runs?limit=20"

GET/v1/runs?automation=&status=&limit=&cursor=#copy link

curl -s "http://127.0.0.1:8787/v1/runs?status=failed,stuck&limit=20"

GET/v1/runs/:id#copy link

curl -s "http://127.0.0.1:8787/v1/runs/run_381"

GET/v1/operators#copy link

curl -s "http://127.0.0.1:8787/v1/operators"

GET/v1/workflows#copy link

curl -s "http://127.0.0.1:8787/v1/workflows"

Simulate and preview#copy link

POST/v1/simulate#copy link

Exactly one of task (an existing task, automation.simulate at latest) or draft (nothing deployed: the AutomationSimulator creation-code call). Always 200 with ok: false and the decoded revert when the execution would fail. Limited to SIMULATE_RATE_PER_MIN per IP.

curl -s -X POST "http://127.0.0.1:8787/v1/simulate" \
  -H "content-type: application/json" \
  -d '{"task":{"automation":"0x5b1f000000000000000000000000000000000000","taskId":0}}'

GET/v1/simulations/:id#copy link

Every simulation is cached for 10 minutes under its id; worker-recorded simulations carry source: "worker" and a runId. 404 after expiry.

curl -s "http://127.0.0.1:8787/v1/simulations/sim_9c2b5e0d4a1f3e7b6c8d9a0b"

POST/v1/workflows/pons-rewards/preview#copy link

The rule builder's single call: resolves both launches, quotes the swap, builds the task and policy, simulates, and returns the ordered txs to sign plus warnings.

curl -s -X POST "http://127.0.0.1:8787/v1/workflows/pons-rewards/preview" \
  -H "content-type: application/json" \
  -d '{"owner":"0x3d8a0670d278c125966f884dc66bea34944a4220","feeToken":"0xa24326d9bcbd110c918dcf386472441b9347cbf6","rewardToken":"0x68ff81dfff6eccefb74706fe1e0a86320cb2eb96","rewardsTarget":"0x3d8a0670d278c125966f884dc66bea34944a4220","fundMode":"transfer","minClaimable":"10000000000000000","nativeCapPerEpoch":"1000000000000000000"}'

The preview accepts an optional slippageBps (default WORKER_SLIPPAGE_BPS). It answers 400 with details[{ path, message }] for missing or invalid fields and 422 unsupported for a fee or reward token that is not ETH-quoted or not graduated. Draft simulations run on a throwaway clone, so simulation.trigger.ok is usually false: judge the run by executed and stepResults.

Transactions to sign#copy link

These routes only encode. They return a TxRequest { chainId, to, data, value, from, description }; send it from the from wallet unchanged.

POST/v1/automations/prepare-create#copy link

POST/v1/automations/:address/calldata#copy link

POST/v1/policy/encode#copy link

curl -s -X POST "http://127.0.0.1:8787/v1/automations/0x5b1f000000000000000000000000000000000000/calldata" \
  -H "content-type: application/json" \
  -d '{"action":"setPaused","args":{"paused":true}}'

POST /v1/policy/encode ABI-encodes policy updates; with automation it also says which updates loosen the policy and whether they apply immediately.

curl -s -X POST "http://127.0.0.1:8787/v1/policy/encode" \
  -H "content-type: application/json" \
  -d '{"updates":[{"op":"setRecipient","recipient":"0x3d8a0670d278c125966f884dc66bea34944a4220","allowed":true}]}'

Terminal#copy link

The lattice CLI's grammar over this site's API: the same console as /app/terminal and the drawer on every /app page (Ctrl+). Reads run here; writes print a transaction for your wallet. Tab completes commands and automation addresses, the arrow keys walk the history, --json prints raw JSON, tail` streams runs and logs.

Dashboard routes#copy link

Read-only routes behind /app, /explore and the terminal: an overview, an eligibility timeline, metric series, a leaderboard, the worker's logs and a live stream. Same error envelope, cursor and rate-limit rules as above. overview, timeline, timeseries and leaderboard answer 503 not_configured while AUTOMATION_FACTORY is unset; worker/logs and stream always work. owner (optional wherever accepted) scopes to one owner's automations; omitted = protocol-wide.

Pages on this site#copy link

Overview#copy link

GET/v1/dashboard/overview#copy link

curl -s "http://127.0.0.1:8787/v1/dashboard/overview?owner=0x3d8a0670d278c125966f884dc66bea34944a4220"

{ "asOf": "2026-10-22T21:27:19.034Z", "chainId": 4663, "syncedBlock": 2000, "headBlock": 2700,
  "tiles": { "automations": 3, "activeTasks": 4, "runs24h": 2, "runsSucceeded24h": 1, "runsFailed24h": 1,
             "successRate30d": 0.6667, "ethMoved24h": "100000000000000000", "feesPaid24h": "1000000000000000",
             "depositTotal": "15000000000000000", "runwayDays": 52.5, "operatorsActive": 1 },
  "automations": [ { "address": "0x...d001", "owner": "0x...0e1", "label": "fees -> rewards", "paused": false,
      "nativeBalance": "5000000000000000", "allowance": [ { "asset": "0x0000000000000000000000000000000000000000",
      "symbol": "ETH", "decimals": 18, "usedInEpoch": "0", "capPerEpoch": "1000000000000000000",
      "epochEndsAt": "2026-10-29T00:00:00.000Z" } ], "nextEligibleAt": "2026-10-22T21:26:18.863Z",
      "nextEligibleReason": "interval", "lastRunAt": "2026-10-22T20:57:18.870Z", "lastRunStatus": "succeeded",
      "runCount": 4, "feeBudgetRemaining": "1500000000000000" } ],
  "alerts": [ { "id": "al_ebf536299673ade6", "kind": "fee_budget_low", "severity": "warning", "automation": "0x...d001",
                "taskId": null, "message": "fee budget 0.0015 ETH is below 3x the average fee (0.000667 ETH)",
                "at": "2026-10-22T21:27:19.034Z", "href": "/app/a/0x...d001" } ],
  "operators": [ { "address": "0x...00be", "active": true, "heartbeatAt": "2026-10-22T21:27:18.887Z", "syncedBlock": 2000,
                   "balance": "30000000000000000", "pendingTxs": 0, "runs24h": 3, "lastError": "out of budget" } ] }

Alerts are sorted critical, warning, info, then newest at first. id = al_ + 16 hex, stable for the same condition so the UI can remember dismissals. href is null for alerts without an automation.

Timeline#copy link

GET/v1/dashboard/timeline#copy link

Every task, newest automation first, then task id. hours (1-720, default 24) only sets the returned from / to drawing window; tasks due later are still listed.

curl -s "http://127.0.0.1:8787/v1/dashboard/timeline?hours=24"

{ "data": [
  { "automation": "0x...d001", "label": "fees -> rewards", "taskId": 0, "taskLabel": "fees -> rewards",
    "nextEligibleAt": "2026-10-22T21:57:18.870Z", "reason": "interval", "intervalSeconds": 3600,
    "lastRunAt": "2026-10-22T20:57:18.870Z", "eligibleNow": false, "details": {} },
  { "automation": "0x...d003", "label": "fees -> rewards", "taskId": 1, "taskLabel": "checker task",
    "nextEligibleAt": null, "reason": "checker", "intervalSeconds": 0, "lastRunAt": null, "eligibleNow": false,
    "details": { "unswept": "12", "claimable": "0" } } ],
  "from": "2026-10-22T21:27:19.121Z", "to": "2026-10-23T21:27:19.121Z" }

Reason order: paused > inactive > parked (nextEligibleAt = retry_after) > interval (lastRunAt + intervalSeconds still in the future) > the worker's cached checkTrigger result (balance => threshold, checker_false / checker_reverted => checker, ok / run_open => eligibleNow: true) > the trigger shape when nothing is cached > unknown. details = the cached eligibility details (pons: claimable, unswept, phase).

Metrics and leaderboard#copy link

GET/v1/metrics/timeseries#copy link

bucket defaults to hour. to defaults to now and from to 23 hours (hour) / 29 days (day) before to, so the default is 24 / 30 points. Both are truncated to the bucket and every bucket in between is present ("0" when empty). Values are decimal strings. More than 1000 points => 400 bad_request.

curl -s "http://127.0.0.1:8787/v1/metrics/timeseries?metric=runs&bucket=hour"

GET/v1/leaderboard#copy link

by = runs | volume | fees, window = 24h | 7d | 30d | all. Defaults by=runs, window=7d, limit 20 (max 100). Only automations with at least one run in the window. volume = native ETH outflow; successRate is null when none finished. Ties: more runs, then address.

curl -s "http://127.0.0.1:8787/v1/leaderboard?by=volume&window=7d&limit=10"

Worker logs#copy link

GET/v1/worker/logs#copy link

Newest first; cursor = {id}. limit default 200, max 1000. level is a minimum (warn = warn + error; debug lines exist only when the worker runs with LOG_LEVEL=debug). The worker batches every structured log line into the table each second without blocking its run loop and keeps the newest 5000 rows. loop is sync, run or submit (null for the app).

curl -s "http://127.0.0.1:8787/v1/worker/logs?level=warn&limit=50"

{ "data": [ { "id": 123, "at": "2026-10-22T21:27:19.034Z", "level": "warn", "loop": "run", "msg": "run failed",
              "fields": { "automation": "0x...d001", "taskId": 0, "runId": 12, "code": "simulation_failed" },
              "automation": "0x...d001", "runId": "run_12" } ], "next": "eyJpZCI6MTIzfQ" }

Live stream#copy link

GET/v1/stream#copy link

Server-Sent Events. types (default all of run, automation, worker, log, heartbeat) and owner filter; an unknown type => 400. Each event has an increasing id; reconnect with Last-Event-ID (EventSource does this) or ?lastEventId= to replay the last 500. A heartbeat arrives on connect and every 15 s.

curl -sN "http://127.0.0.1:8787/v1/stream?types=run,heartbeat"

retry: 3000

id: 1761168439001
event: heartbeat
data: {"t":"2026-10-22T21:27:19.034Z","headBlock":2700,"syncedBlock":2000}

id: 1761168439002
event: run
data: {"id":"run_12","automation":"0x...d001","taskId":0,"status":"submitted",...,"change":"created"}

• Payloads: run = RunRecord + change (created | updated); automation = AutomationSummary + change; worker = an operators[] row of the overview; log = one worker log line.
• worker and heartbeat ignore owner; log lines without an automation only reach streams without owner.
• At most 200 concurrent streams per API process; above that 503 unavailable with retry-after: 10. A client that stops reading is disconnected after 1 MB buffered.
• The site's live views degrade to polling /v1/runs and /v1/worker/logs every 5 s when the stream is unavailable.

Health#copy link

GET/v1/health#copy link

ok = database reachable and chain state updated within 60 s. 200 when ok, 503 otherwise, same body.

{ "ok": true, "chainId": 4663, "version": "0.1.0", "db": "ok",
  "headBlock": 94596923, "safeBlock": 94596911, "headAgeSeconds": 1.4 }

curl -s "http://127.0.0.1:8787/v1/health"

Stats#copy link

GET/v1/stats#copy link

Public and cheap. The indexer strip on /data polls it every 10 s.

curl -s "http://127.0.0.1:8787/v1/stats"

{ "chainId": 4663, "contractsIndexed": 12, "contractsLive": 11,
  "eventsIndexed": 1840022, "transfersIndexed": 1530044, "holdersTracked": 40211,
  "headBlock": 94596923, "safeBlock": 94596911, "indexedBlock": 94596920, "lagBlocks": 3,
  "updatedAt": "2026-10-21T12:00:00.000Z" }

Register a contract#copy link

POST/v1/contracts#copy link

curl -s -X POST "http://127.0.0.1:8787/v1/contracts" \
  -H "content-type: application/json" \
  -d '{"address":"0xa24326d9bcbd110c918dcf386472441b9347cbf6","label":"GITFUND"}'

Response: 201 (new) or 200 (already registered, unchanged) with ContractInfo. Status moves pending -> backfilling -> live; error carries a reason; paused is set by the operator.

Read contracts#copy link

GET/v1/contracts#copy link

Query: status, kind, limit, cursor. Ordered createdAt DESC, address ASC. Returns Page<ContractInfo>.

curl -s "http://127.0.0.1:8787/v1/contracts?status=live&limit=20"

GET/v1/contracts/:address#copy link

curl -s "http://127.0.0.1:8787/v1/contracts/0xa24326d9bcbd110c918dcf386472441b9347cbf6"

{ "address": "0xa24326d9bcbd110c918dcf386472441b9347cbf6", "kind": "erc20", "label": "GITFUND",
  "name": "GitFund", "symbol": "GITFUND", "decimals": 18, "totalSupply": "1000000000000000000000000000",
  "status": "live", "error": null, "startBlock": 92482929, "indexedThrough": 94596920, "progress": 1,
  "holdersCount": 412, "transfersCount": 9811, "eventsCount": 15230, "hasAbi": false,
  "createdAt": "2026-10-21T11:58:00.000Z", "updatedAt": "2026-10-21T12:00:00.000Z" }

Holders and balances#copy link

GET/v1/contracts/:address/holders#copy link

Query: block (as-of), limit, cursor. Sorted balance DESC, holder ASC. Zero balances and the zero address never appear. share = balance / sum of all balances at that block. erc721: balance = tokens held.

curl -s "http://127.0.0.1:8787/v1/contracts/0xa24326d9bcbd110c918dcf386472441b9347cbf6/holders?limit=10"

{ "contract": "0xa243...cbf6", "block": 94596920, "holderCount": 412, "decimals": 18,
  "data": [
    { "holder": "0x5ea3...b5ef", "balance": "120000000000000000000000000", "formatted": "120000000", "share": 0.12 }
  ],
  "next": "eyJiIjoiMTIwMDAw..." }

GET/v1/contracts/:address/holders/:holder#copy link

Balance of one address. Query: block. A non-holder returns balance: "0" with 200. erc721 adds tokenIds (ascending, max 1000).

curl -s "http://127.0.0.1:8787/v1/contracts/0xa24326d9bcbd110c918dcf386472441b9347cbf6/holders/0x3d8a0670d278c125966f884dc66bea34944a4220"

GET/v1/contracts/:address/tokens/:tokenId#copy link

erc721 only. Query: block. Returns { contract, tokenId, owner | null, block }. erc20 => 409 conflict.

curl -s "http://127.0.0.1:8787/v1/contracts/0xa24326d9bcbd110c918dcf386472441b9347cbf6/tokens/1"

GET/v1/addresses/:address/balances#copy link

Every registered erc20/erc721 contract where the address has a non-zero balance. Query: limit, cursor.

curl -s "http://127.0.0.1:8787/v1/addresses/0x3d8a0670d278c125966f884dc66bea34944a4220/balances?limit=20"

Transfers#copy link

GET/v1/contracts/:address/transfers#copy link

erc20 / erc721. Query: address (either side), direction = in | out | any (only with address), tokenId, fromBlock, toBlock (inclusive), order, limit, cursor. Returns Page<Transfer>.

curl -s "http://127.0.0.1:8787/v1/contracts/0xa24326d9bcbd110c918dcf386472441b9347cbf6/transfers?order=desc&limit=20"

GET/v1/addresses/:address/transfers#copy link

Transfers touching an address across every registered contract. Query: contract, direction, fromBlock, toBlock, order, limit, cursor.

curl -s "http://127.0.0.1:8787/v1/addresses/0x3d8a0670d278c125966f884dc66bea34944a4220/transfers?contract=0xa24326d9bcbd110c918dcf386472441b9347cbf6&order=desc&limit=20"

{ "data": [ { "contract": "0xa243...cbf6", "blockNumber": 94596900, "blockHash": "0x...",
              "blockTime": "2026-10-21T11:59:58.000Z", "txHash": "0x...", "logIndex": 3,
              "from": "0x...", "to": "0x...", "amount": "1000000000000000000",
              "tokenId": null, "confirmed": true } ],
  "next": null }

Events#copy link

GET/v1/contracts/:address/events#copy link

Every log of the contract, decoded when the ABI matches (undecoded logs have name: null, args: null). Query: event (e.g. Transfer; _unknown = undecoded only), address (matches any address-typed arg), txHash, fromBlock, toBlock, order, limit, cursor.

curl -s "http://127.0.0.1:8787/v1/contracts/0xa24326d9bcbd110c918dcf386472441b9347cbf6/events?event=Transfer&order=desc&limit=20"

{ "data": [ { "contract": "0xa243...cbf6", "blockNumber": 94596900, "blockHash": "0x...",
              "blockTime": null, "txHash": "0x...", "txIndex": 1, "logIndex": 3,
              "name": "Transfer", "signature": "Transfer(address,address,uint256)",
              "args": { "from": "0x...", "to": "0x...", "value": "1000000000000000000" },
              "topics": ["0xddf252ad...", "0x000...", "0x000..."], "data": "0x...",
              "confirmed": true } ],
  "next": "eyJuIjo5NDU5NjkwMCwiaSI6M30" }

args is keyed by ABI input name (index string when unnamed); integers as decimal strings, addresses lowercase, bytes as hex, arrays and tuples as arrays and objects.

Snapshots#copy link

GET/v1/contracts/:address/snapshot#copy link

The full holder list at a block, for airdrops and holder-gated payouts. Not paginated. Query: block (default min(safeBlock, indexedThrough)), format = json | csv, minBalance (raw units, default 1). Too many holders => 409 conflict. Snapshots at or below the safe block are immutable and may be cached.

curl -s "http://127.0.0.1:8787/v1/contracts/0xa24326d9bcbd110c918dcf386472441b9347cbf6/snapshot?format=json"

Set format to csv in the Try-it panel and every tab switches to the CSV download.

{ "contract": "0xa243...cbf6", "kind": "erc20", "symbol": "GITFUND", "decimals": 18, "block": 94596911,
  "holderCount": 412, "total": "1000000000000000000000000000",
  "rows": [ { "holder": "0x5ea3...b5ef", "balance": "120000000000000000000000000", "formatted": "120000000" } ] }

holder,balance,formatted
0x5ea3...b5ef,120000000000000000000000000,120000000

erc721 rows add tokenIds (JSON) or a token_ids column with ids separated by ; (CSV). Rows are sorted balance DESC, holder ASC.

Manage webhooks#copy link

A webhook subscribes to logs of one registered contract, optionally narrowed to one event name and/or one address (matched against any address-typed argument). Every route needs write auth.

Create#copy link

curl -s -X POST "http://127.0.0.1:8787/v1/webhooks" \
  -H "x-api-key: $LATTICE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contract":"0xa24326d9bcbd110c918dcf386472441b9347cbf6","url":"https://example.com/hooks/lattice","eventName":"Transfer"}'

contract must be registered (404). url must be http(s); https only in production; private and loopback hosts are rejected. eventName must exist in the ABI when it is known (400). fromBlock defaults to the current chain head; pass a lower value, e.g. 0, to also receive history. The webhook object returns it as fromBlock.

List, read, enable, test#copy link

The reads need your key too: paste it into the Try-it panel. It is sent with that one request and never stored.

curl -s "http://127.0.0.1:8787/v1/webhooks?contract=0xa24326d9bcbd110c918dcf386472441b9347cbf6&limit=20" \
  -H "x-api-key: $LATTICE_API_KEY"

curl -s "http://127.0.0.1:8787/v1/webhooks/wh_3f9a0c1d2e4b5a6978877665" \
  -H "x-api-key: $LATTICE_API_KEY"

curl -s -X PATCH "http://127.0.0.1:8787/v1/webhooks/wh_3f9a0c1d2e4b5a6978877665" \
  -H "x-api-key: $LATTICE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"active":true}'

curl -s "http://127.0.0.1:8787/v1/webhooks/wh_3f9a0c1d2e4b5a6978877665/deliveries?limit=20" \
  -H "x-api-key: $LATTICE_API_KEY"

curl -s -X POST "http://127.0.0.1:8787/v1/webhooks/wh_3f9a0c1d2e4b5a6978877665/test" \
  -H "x-api-key: $LATTICE_API_KEY"

Deliveries#copy link

• Only confirmed logs are delivered: the POST goes out once the head is 12 blocks past the log (about 1-2 s on 4663).
• A reorg before delivery deletes the pending delivery. After delivery the row is marked reverted; no retraction is sent in v0.
• A webhook only delivers logs with blockNumber >= fromBlock. fromBlock defaults to the chain head at creation, so history is never replayed, not during a backfill and not on a later re-index. Opt in with "fromBlock": 0 (or any block) on create to also receive history the indexer writes after that; expect one POST per log.
• Order is best effort. Use event.blockNumber and event.logIndex to order.

POST <your url>
content-type: application/json
user-agent: lattice-webhooks/0.1
x-lattice-webhook-id: wh_3f9a0c1d2e4b5a6978877665
x-lattice-delivery-id: dlv_5512
x-lattice-event: Transfer
x-lattice-signature: t=1792617600,v1=5b0e...c4

{
  "id": "dlv_5512", "type": "event", "webhookId": "wh_3f9a0c1d2e4b5a6978877665",
  "attempt": 1, "sentAt": "2026-10-21T12:00:03.120Z", "chainId": 4663,
  "contract": "0xa24326d9bcbd110c918dcf386472441b9347cbf6",
  "event": { "blockNumber": 94596900, "txHash": "0x...", "logIndex": 3,
             "name": "Transfer", "args": { "from": "0x...", "to": "0x...", "value": "1000000000000000000" },
             "confirmed": true, "...": "same fields as the events API" },
  "transfer": { "from": "0x...", "to": "0x...", "amount": "1000000000000000000", "tokenId": null, "...": "..." }
}

transfer is non-null only for Transfer logs of erc20/erc721 contracts. id is stable across retries: dedupe on it. Test pings send { "type": "ping", "id": "ping_...", ... } with x-lattice-event: ping.

Verify signatures#copy link

x-lattice-signature: t=<unix seconds>,v1=<hex HMAC-SHA256> over ${t}.${rawBody}, keyed with the whole whsec_... secret as UTF-8. Verify the raw body before parsing it, reject when |now - t| > 300, and compare in constant time. Every retry is re-signed with a fresh t.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, header, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=").map((s) => s.trim())));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > tolerance) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1?.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

The SDK exports the same verifySignature(secret, rawBody, header, tolerance?), built on WebCrypto, for Node and browsers.

Retries and disabling#copy link

• Success = any 2xx within 10 s. The first 1024 bytes of the response are logged.
• Anything else (non-2xx, timeout, network error, a redirect) is a failed attempt. Redirects are not followed.
• Up to 8 attempts. Delays: 10 s, 30 s, 2 m, 10 m, 30 m, 1 h, 2 h, plus 0-10 % jitter.
• 410 Gone disables the webhook immediately.
• 20 consecutive failed deliveries disable it. Re-enable with PATCH /v1/webhooks/:id {"active": true}; failures while disabled are not replayed.
• Every attempt, pings included, is listed at GET /v1/webhooks/:id/deliveries.

SDK and CLI#copy link

The TypeScript SDK has one method per route, async iterators for paginated reads, LatticeError (status, code, message), and verifySignature. Zero dependencies.

import { Lattice } from "@lattice/sdk";

const lattice = new Lattice({ baseUrl: process.env.LATTICE_API_URL });
const stats = await lattice.stats();
for await (const holder of lattice.iterateHolders("0xa24326d9bcbd110c918dcf386472441b9347cbf6")) {
  console.log(holder.holder, holder.formatted);
}

The CLI reads LATTICE_API_URL and LATTICE_API_KEY (or --api, --key).

lattice register 0xa24326d9bcbd110c918dcf386472441b9347cbf6 --label GITFUND --wait
lattice status 0xa24326d9bcbd110c918dcf386472441b9347cbf6
lattice holders 0xa24326d9bcbd110c918dcf386472441b9347cbf6 --limit 20
lattice snapshot 0xa24326d9bcbd110c918dcf386472441b9347cbf6 --block 94596911 --csv --out holders.csv
lattice webhook add|ls|rm|test ...