API for agents

Everything the builder does is open as JSON on the site's own origin, so an agent can read the modules, write a recipe, get the Solidity, prove it on the live chain and deploy it from its own wallet, without the interface.

The flow

Read the catalog with GET /api/modules and write a recipe.
Check it and read the Solidity with POST /api/build. Nothing is compiled.
Prove it with POST /api/prove: the compile and the run on the live chain, with the creation code a deploy sends.
Deploy from your own wallet through the factory's deploy(), with a salt mined for that wallet. See deploying.
Publish the source with POST /api/verify, and find the hook with every other one in GET /api/hooks.

Errors come back as { "error": "..." } with a 4xx status, in the same words the builder shows: a recipe out of bounds names the module and the parameter.

GET /api/modules

The module catalog: generator (v4builder/2), the units (pips, bps, seconds, days, percent), and every module with its id, name, kind, short line, params (key, label, unit, min, max, default), targets, callbacks and an example sentence at the default numbers. examples holds the three example recipes. Open to any origin.

POST /api/build

Body { recipe }. Returns the contract name, the target, the permission flags and callbacks of an own hook, whether its pool needs the dynamic fee flag, the constructor argument names, one sentence per module, the recipe string the factory will record, and the Solidity source. Open to any origin. A cooldown of one minute:

Request

curl -s -X POST https://v4builder.dev/api/build \
  -H 'content-type: application/json' \
  -d '{"recipe":{"v":1,"name":"Slow Swaps","target":"hook","baseFee":3000,"modules":[{"id":"cooldown","p":{"seconds":60}}]}}'

Response (source cut after six lines)

{
  "contract": "SlowSwaps",
  "target": "hook",
  "flags": 128,
  "callbacks": [
    "beforeSwap"
  ],
  "dynamic": false,
  "constructor": [
    "poolManager"
  ],
  "sentences": [
    "A wallet that just swapped in this pool waits 1 minute before its next swap."
  ],
  "recipe": "{\"v\":1,\"g\":\"v4builder/2\",\"name\":\"Slow Swaps\",\"target\":\"hook\",\"baseFee\":3000,\"modules\":[{\"id\":\"cooldown\",\"p\":{\"seconds\":60}}]}",
  "source": "// SPDX-License-Identifier: MIT\npragma solidity 0.8.26;\n\n// SlowSwaps: a Uniswap v4 hook, written by v4 Builder (v4builder/2) from the recipe below.\n// Callbacks: beforeSwap. Its address carries them in its low bits.\n//\n..."
}

POST /api/prove

Body { recipe }. Compiles the source with solc 0.8.26 and runs the proof on the live chain in the same request. It is limited to 12 proofs a minute per IP address; over that, a 429.

Field	What it holds
ok, reason	Whether the hook passed, and why not when it did not
contract, source, sentences	What /api/build returns
flags, callbacks, dynamic	The permissions of an own hook, and the dynamic fee flag
compile	ok, ms, size in bytes, viaIR, and errors when it failed
creationCode	The code a deploy sends, before the constructor arguments
sim.block	The block the run was simulated on
sim.rows	One row per moment and wallet: moment, at, who (anyone or agent), what, ok, refused, reason, feeBps, gas
sim.gas	deploy and perSwap; extra over the twin pool for an own hook, max for a stacked hook
sim.listGas	A stacked hook: the gas limit to list it with
sim.exit	An own hook: whether the liquidity could leave at the end, and why not
notes	Plain remarks, such as a stacked hook close to the gas ceiling

POST /api/verify

Body { hook }: for a hook built through the factory, reads the recipe back from its Built event, rebuilds and compiles the source with the deploy settings, and submits it to Sourcify with the creation transaction. The answer carries the verification state and, while it is pending, an id. Send { hook, id } to ask where it stands.

GET /api/hooks

Every hook built through the factory, newest first, read from its Built events: hook, builder, kind (hook or stack), flags, the parsed recipe and the raw recipeRaw, paid in ETH, tx, block and at. Open to any origin, refreshed every 30 seconds. The same list is the hooks page.

The endpoints never hold a key and never send a transaction: deploying, opening a pool and listing are always signed by the caller's own wallet.