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.
Install
Section titled “Install”Requires Node.js ≥ 18.3 (Node 22+ for the websocket feed). viem is a peer dependency and is installed automatically on npm 7+.
# global install (recommended for a long-running bot)npm i -g @covennetwork/arbcoven-arb doctor
# or run without installingnpx @covennetwork/arb doctorThe package ships a compiled CLI; there is no build step on your side.
Quick start on a server
Section titled “Quick start on a server”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.
npm i -g @covennetwork/arbcoven-arb doctor # endpoints, websockets, contract, gas, cachecoven-arb run --dry-run --log dry.jsonl # an hour or two, no key neededexport COVEN_PRIVATE_KEY=0x... # a fresh key holding a few USDC for gas and bidscoven-arb run --max-loss 2 --log trades.jsonlTo 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.
Commands
Section titled “Commands”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 doctorrunis 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.scanis 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.indexis 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.doctorchecks 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, theCovenProbecontract 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. |
Environment
Section titled “Environment”| 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.
No private-key flag
Section titled “No private-key flag”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:
export COVEN_KEYSTORE=~/.keys/arb.json COVEN_KEYSTORE_PASSWORD=...coven-arb run --log trades.jsonlHow a trade is found
Section titled “How a trade is found”- 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
Initializeevent, 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. - Routes. Every
USDC → X → USDCandUSDC → X → Y → USDCloop 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. - Screen. Market events arrive over several websocket subscriptions at once, each event taken from whichever delivers it first, with an
eth_getLogspoll 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. - Simulate. Every candidate goes through
CovenProbein 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. - Send. A route whose profit beats its gas plus
--min-profitis sent alone, signed locally and broadcast to every endpoint. A payout send bids--payout-bidof 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. - 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.
Bidding: payouts yes, price gaps no
Section titled “Bidding: payouts yes, price gaps no”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.
doctorshows which endpoints keep up and which websockets accept a subscription, and everysentline 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.
The log
Section titled “The log”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.
Upgrading from 0.5
Section titled “Upgrading from 0.5”- Price gaps are off by default; pass
--gapsto trade them as before. - Payout sends bid 10% of their profit as priority fee (
--payout-bid,--max-bid);--payout-bid 0restores zero-tip sends. --wstakes 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_URLorARC_WS_URL, checkdoctor: Circle’s and QuickNode’s public endpoints trail the head by about 400 ms and refuse websocket subscriptions. scanand--dry-runnow price hook payouts; before, they simulated from the zero address and saw none.- Library:
createRpc(urls, fastUrls)returns afastclient besidesclient;rankEndpoints,fastEndpointsandpayoutTipare new.
Upgrading from 0.4
Section titled “Upgrading from 0.4”- The bot trades through
CovenProbeinstead of the deprecatedCovenArb. Nothing to approve or migrate: neither contract holds your funds. --bidis gone; use--tip <gwei>, default 0.--max-lossis new.--min-profitnow 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
outbidandcompetitorlog events are gone;outcomehas a newmissedstatus. - Library:
evaluate,priorityFeeForandCompetitorBookare removed. UsecycleCandidates,priceandsimulate. TheCovenArbhelpers are still exported, marked deprecated.
Limits
Section titled “Limits”- 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.
indexfinds them from theirInitializeevent. - Routes of up to three legs are enumerated; the contract itself takes up to four.
