05 · Developer automation API

Plug automation into your app.

Read everything over JSON, write through the contract with your own wallet or keeper. No API key: every route is rate-limited per network. A write API with keys is planned, not built.
GET /api/v1/status · live

The same JSON your app can read. CORS is open for GET.

Read API

EndpointWhat it returns
GET /api/v1/statusForge address, head block, task count, escrow + credits against the ETH it holds.
GET /api/v1/tasksNewest 200 tasks from the forge's views. Filters: owner=0x…, status=active, paused, halted, done or cancelled, due=1.
GET /api/v1/tasks/<id>One task read fresh, its condition's value now, its runs (decoded failures) and changes.
GET /api/v1/runsRun history from events. Filters: task, owner, keeper, failed=1, limit 1–500.
GET /api/v1/guard?owner=0x…An owner's caller address, allowed pairs (each confirmed with allowed()), open tasks and credits.
GET /api/monitor?address=0x…A contract's logs over 2,000 / 10,000 / 50,000 blocks, optional topic0.

Task state always comes from the forge's views. History comes from events: blocks older than 20 are indexed, newer ones are re-read every time and marked unconfirmed. A response with an unread span says "incomplete": true and is never cached.

Create a task in code

Call EoniqTaskForge.createTask from any wallet library. The forge checks the same limits the form does: interval ≥ 10 s, call gas 21,000–3,000,000, ≤ 10,000 runs, call data ≤ 2,048 bytes, condition gas ≤ 300,000.

import { createWalletClient, custom, parseEther, encodeFunctionData } from "viem";

// The same fields the scheduler form fills. value = reward × maxRuns, exactly.
const task = {
  target: "0xYourContract", callData: encodeFunctionData({ abi, functionName: "harvest" }),
  interval: 3600, callGas: 200_000, maxRuns: 24, reward: parseEther("0.001"),
  needsApproval: false, maxFailures: 3,
  condOp: 0, condTarget: "0x0000000000000000000000000000000000000000", condData: "0x", condGas: 0, condValue: 0n,
  label: "hourly harvest",
};
await wallet.writeContract({ address: FORGE, abi: forgeAbi, functionName: "createTask",
  args: [task, true /* add the pair to my guard */], value: task.reward * BigInt(task.maxRuns) });

Run a keeper

The keeper script is open source in this repository. It runs on your machine with your key; it asks the forge's own check() which tasks are due, simulates each run, and only sends when the reward covers the gas you set as the margin.

# Read-only: lists due tasks, simulates each run and prints the gas cost against the reward.
node examples/keeper.mjs --dry-run

# Runs due tasks with your own key, only when reward ≥ estimated gas cost × margin.
FORGE=0x… KEEPER_KEY=0x… RPC_URL=https://rpc.mainnet.chain.robinhood.com node examples/keeper.mjs --loop 30

Nobody is paid to run your task except the reward you set. Eoniq runs no hosted keeper network today (planned): a task runs when some keeper finds it worth the gas.

Rules worth knowing

  • Your tasks call out from your own caller address (made by the forge with your first task). Give roles and allowances to that address, never to the forge.
  • A task call never carries ETH: the forge sends value 0. Tasks cannot move the escrow anywhere except to the keeper as its reward.
  • A keeper is paid for a run whether your call succeeds or reverts, because it paid the gas either way. Set a failure limit so a broken task halts.
  • The forge forwards exactly the call gas you set; a keeper that brings less gas has its whole transaction refused, so it cannot make your call fail on purpose that way.
  • Time uses block timestamps. On Robinhood Chain (an Arbitrum Orbit chain) block.number inside a contract is Ethereum's block number, not the chain's own (measured 13 Nov 2026: about 26.4 M inside a contract against about 113 M chain blocks), so the forge never uses it.
  • The forge holds the ETH you escrow for rewards. It is new code with Foundry tests and a written self-review, and it needs an independent security review before real volumes. Start with small amounts.

Planned

  • plannedHosted keeper network (Eoniq-run keepers with a public schedule)
  • plannedPush alerts for watched contracts (today: in the page, while it is open)
  • plannedWrite API with API keys (today: read-only API + your own wallet or keeper)
  • planned$EONIQ for keeper fees and API quotas, once those services exist

Questions about the token are on the token page.