Skip to content

The arbitrage CLI

coven-arb is the primary way to run the bot. It watches every block for the payouts of fair-launch hooks (and, with --gaps, USDC price-gap cycles across Uniswap v3, v4 and v3-style forks), simulates each route through CovenProbe against live state, and sends only the ones that pay for their own gas, bidding a share of each payout. A trade either makes money or is skipped on-chain; you never hold inventory.

Version 0.6.0 sees blocks sooner, bids on payouts and turns price gaps off by default; see Upgrading from 0.5. Version 0.5.0 moved the bot from CovenArb to CovenProbe; see Upgrading from 0.4.

Requires Node.js ≥ 18.3 (Node 22+ for the websocket feed). viem is a peer dependency and is installed automatically on npm 7+.

Terminal window
# global install (recommended for a long-running bot)
npm i -g @covennetwork/arb
coven-arb doctor
# or run without installing
npx @covennetwork/arb doctor

The package ships a compiled CLI; there is no build step on your side.

Whether a send lands in the next block is most of the result. The defaults already pick the fastest public endpoints; doctor shows which ones keep up from your machine.

Terminal window
npm i -g @covennetwork/arb
coven-arb doctor # endpoints, websockets, contract, gas, cache
coven-arb run --dry-run --log dry.jsonl # an hour or two, no key needed
export COVEN_PRIVATE_KEY=0x... # a fresh key holding a few USDC for gas and bids
coven-arb run --max-loss 2 --log trades.jsonl

To keep it running after you log out, start it inside tmux or screen, or as a systemd service. The first start replays about three hours of market events to find pools, which takes several minutes on public endpoints; later starts read the cache and take seconds.

Terminal window
coven-arb run [--dry-run] [--min-profit <usdc>] [--payout-bid <pct>] [--gaps] [--max-loss <usdc>] [--ws <url,...|off>] [--log <file>]
coven-arb scan [--min-profit <usdc>] [--json]
coven-arb index [--from <block>]
coven-arb doctor
  • run is the live bot. It needs a signer (see Environment) unless you pass --dry-run, which does everything except sign and send. Ctrl-C stops it cleanly: it waits for pending transactions and prints the session’s profit and gas.
  • scan is one read-only pass over the current market. It prints every route that is profitable on-chain right now and whether it clears the floor after gas.
  • index is optional. It records every pool ever created, newest first, so a token’s dormant venues are known before they first trade. It is resumable (Ctrl-C is safe) and needs an endpoint that serves historical logs; on the public endpoints a full index takes about two hours.
  • doctor checks each endpoint’s latency, log support and how often its head trails the freshest (hot path or history only), whether each websocket accepts a subscription, the CovenProbe contract and its current fee, the gas price and what a trade costs, the signer’s balance, and the pool cache. It exits non-zero if anything fails.

There is no flag to choose the contract: the CLI always uses the deployed CovenProbe. There is no --tokens flag either, since the bot finds its own markets.

Flag Applies to Default Description
--rpc <url,...> all $ARC_RPC_URL, else the public Arc endpoints Comma-separated. Timed against the chain head at startup: those that keep up serve the hot path (events, simulation, receipts), the rest serve history. A rate-limited endpoint is skipped, and transactions are broadcast to every one.
--min-profit <usdc> run, scan 0 Smallest profit worth sending, after CovenProbe’s fee, gas and any bid. The contract enforces it.
--payout-bid <pct> run 10 Priority fee bid on a hook payout, as a share of its profit. 0 turns bidding off. See Bidding.
--max-bid <usdc> run 2 Cap on one payout bid.
--gaps run off Also trade price-gap cycles.
--tip <gwei> run, scan 0 Priority fee per gas on every send, on top of any payout bid.
--max-loss <usdc> run — Stop once gas spent exceeds profit by this much.
--ws <url,...|off> run $ARC_WS_URL, else dRPC, Blockdaemon and PublicNode Websockets for pushed market events, all subscribed at once; each event is taken from the first to deliver it. A refused or dropped socket is retried. Polling stays on behind them. Needs Node 22+; on older versions the bot polls only.
--dry-run run off Report what it would send without signing anything.
--log <file> run — Append every opportunity, send, outcome and status line as JSON lines.
--json scan off Print routes as JSON.
--from <block> index first DEX block Oldest block to index.
--help, -h — — Print usage and exit.
Variable Used by Description
COVEN_PRIVATE_KEY run, doctor Raw private key (0x-prefixed or bare).
COVEN_KEYSTORE / COVEN_KEYSTORE_PASSWORD run, doctor An encrypted v3 keystore, as written by geth, cast wallet or MetaMask, and its password.
ARC_RPC_URL all Default endpoints when --rpc is not passed. Comma-separated.
ARC_WS_URL run Default websockets when --ws is not passed. Comma-separated.
COVEN_ARB_CACHE all Directory for the pool cache. Default ~/.cache/coven-arb.

The signer only pays gas. CovenProbe settles each route inside one transaction, so no trading capital is needed. A trade costs 0.004 to 0.014 USDC in gas depending on its legs, and a send whose gap has already gone about 0.0013. Each send needs about 0.02 USDC free up front, since the node checks gas limit × max fee before accepting it, and more when it carries a bid. Keep a few USDC on the signer; below what a send needs, the bot logs NOT SENT and waits instead of failing silently.

There is no --private-key flag, on purpose. It lands in shell history and in screenshots when people paste logs. Provide the key out of band instead:

Terminal window
export COVEN_KEYSTORE=~/.keys/arb.json COVEN_KEYSTORE_PASSWORD=...
coven-arb run --log trades.jsonl
  1. Discovery. At startup the bot replays about three hours of swap and liquidity events to find every pool that is actually trading. A v3-style pool is rebuilt from its own getters and kept if a known factory created it: Uniswap v3, Synthra V3 or a Slipstream-style CL clone. A v4 pool only reveals its key in its Initialize event, usually older than a public endpoint will serve, so the key is recovered from a transaction that swapped the pool. For each token found, it also checks the token’s other venues against USDC, EURC and native USDC. Hooks that keep a per-pool fee inventory are noted. Everything is cached, so later starts take seconds.
  2. Routes. Every USDC → X → USDC and USDC → X → Y → USDC loop through distinct pools, where either end can be ERC-20 or native USDC. For each fair-launch hook pool, a payout route: buy the hook’s fee inventory at the pool price and sell it back.
  3. Screen. Market events arrive over several websocket subscriptions at once, each event taken from whichever delivers it first, with an eth_getLogs poll behind them so no block is ever missed. Only endpoints that keep up with the chain head serve this hot path. Swap events carry the pool’s new price and liquidity, so state stays exact. Payout routes of touched hook pools, and all of them every 30 seconds, are simulated; with --gaps, touched cycles are priced from spot prices and LP fees first.
  4. Simulate. Every candidate goes through CovenProbe in one round of calls at the block the events came from. The contract checks, sizes and trades each route, so the profit it reports is exact after every tick, hook and fee, and after its own cut.
  5. Send. A route whose profit beats its gas plus --min-profit is sent alone, signed locally and broadcast to every endpoint. A payout send bids --payout-bid of its profit as priority fee. Gas and bid go along as the contract’s profit floor: if someone else takes the gap first, the contract skips the trade and the send costs about 60k gas. A payout route also requires the hook to still hold at least half the inventory the bot saw, so a late payout send stops after about 44k gas.
  6. Back off. After a miss, every pool the route used sits out for 30 seconds, doubling with each consecutive miss up to 30 minutes, since many cycles share the same contested pools. Hook payout routes are exempt: their gate already makes a miss cheap.

Arc orders transactions by priority fee per gas, so a higher bid lands first. Price gaps go to reactive bidders who paid a median 81% of what they won in fees, so the bot never bids on them and leaves them off by default. Large hook payouts are an auction too: over 3.5 days in October 2026, payout winners paid 53% of their profit in fees, and senders bidding about 1 gwei won every zero-tip tie. Replayed against those rivals’ actual bids, bidding 10% of each payout about doubled payout profit when sends land in the next block, so --payout-bid defaults to 10. A lost bid still pays its tip on the ~44k gas the gate uses.

Three things decide whether a run makes money:

  • Latency. 80% of payout profit is taken one block after the payout appears. Public endpoints differ by most of a block: some serve a head about 400 ms old. doctor shows which endpoints keep up and which websockets accept a subscription, and every sent line reports which source delivered the block and the milliseconds to the broadcast.
  • Hook payouts. On Arc the largest repeatable source has been fair-launch hooks that sell their collected fees to the next swapper. Other bots harvest them too; whoever lands first, with the higher bid, takes it.
  • Opportunity size. Most price gaps at a given moment are dust, below gas. Real ones follow large swaps on pools that share a token with another venue.

Before putting a key in, run coven-arb run --dry-run --log dry.jsonl for an hour or two on the endpoint you will actually use, and count how often a send clears the floor.

With --log, every event is one JSON line:

type Written when
opportunity A dry run finds a route that clears the floor.
below_floor A route is profitable on-chain but not after gas and --min-profit.
low_balance A send was skipped because the signer cannot cover it up front.
sent A transaction is broadcast, with reactionMs from the block it was decided on, the source that delivered that block, tipGwei and the bid in USDC.
outcome It lands as won (profit paid), missed (the gap was gone; only the check’s gas was spent) or reverted, or is dropped. With the expected and realized profit, the protocol fee, the gas paid, and the block it was decided on and landed in.
status Once a minute: block, pools, cycles, hook pools, simulations, sends and running profit.
error Anything that went wrong, with where it happened.

landedBlock minus seenBlock is the number that matters most: it says how often your sends make the next block.

  • Price gaps are off by default; pass --gaps to trade them as before.
  • Payout sends bid 10% of their profit as priority fee (--payout-bid, --max-bid); --payout-bid 0 restores zero-tip sends.
  • --ws takes several URLs and defaults to dRPC, Blockdaemon and PublicNode instead of the first --rpc. A refused websocket is retried instead of turned off.
  • The default endpoints changed, and only those that keep up with the chain head serve the hot path. If you set ARC_RPC_URL or ARC_WS_URL, check doctor: Circle’s and QuickNode’s public endpoints trail the head by about 400 ms and refuse websocket subscriptions.
  • scan and --dry-run now price hook payouts; before, they simulated from the zero address and saw none.
  • Library: createRpc(urls, fastUrls) returns a fast client besides client; rankEndpoints, fastEndpoints and payoutTip are new.
  • The bot trades through CovenProbe instead of the deprecated CovenArb. Nothing to approve or migrate: neither contract holds your funds.
  • --bid is gone; use --tip <gwei>, default 0. --max-loss is new.
  • --min-profit now defaults to 0, since every send carries its own gas cost as the on-chain floor.
  • Native-USDC pools, Synthra V3 and Slipstream-style pools, and fair-launch hook payouts are traded.
  • The outbid and competitor log events are gone; outcome has a new missed status.
  • Library: evaluate, priorityFeeFor and CompetitorBook are removed. Use cycleCandidates, price and simulate. The CovenArb helpers are still exported, marked deprecated.
  • Fee-on-transfer tokens paid into a v3-style pool fail the pool’s balance check. Such routes simulate at no profit and are never sent.
  • Some v4 pools cannot be recovered. For 10 to 20% of the v4 pools seen trading, the key cannot be rebuilt from one transaction. index finds them from their Initialize event.
  • Routes of up to three legs are enumerated; the contract itself takes up to four.