jev-trader README

The project's README from github.com/jarrodwatts/jev-trader. As one markdown file: README.md.

jev-trader

One decision every Monad block. A TypeSafe Jev model watches the Kuru MON-USDC order book and answers buy or sell every ~300 ms. Every block posts a real post-only limit order on that side, one tick inside the touch, replacing the last one. Fills happen when a taker hits it, so the bot earns the spread instead of paying it. A small server streams every block to the dashboard.

Run

cp .env.example .env
bun install
bun run start

With no PRIVATE_KEY it dry-runs: real book, real decisions, simulated fills. Set MODEL=jev and TYPESAFE_AI_API_KEY to use Jev; the default mock is a momentum heuristic stand-in.

Endpoints

Deployed (dry run, mock model): https://jev-trader-production.up.railway.app

Every event (see src/trader.ts for types):

{
  "block": 105488269, "ts": 1789593630676,
  "mid": 0.022636, "bestBid": 0.022628, "bestAsk": 0.022644, "spreadBps": 7.07,
  "decision": { "action": "buy", "probabilities": { "buy": 0.77, "sell": 0.23, "hold": 0 }, "upIn10": 0.77, "latencyMs": 81, "late": false },
  "quote": { "side": "buy", "price": 0.022629, "size": 200, "txHash": "0x…", "gasMon": 0.0357, "cancel": [100295801], "status": "sent", "orderId": null, "capped": false },
  "fill": null,
  "resting": { "bidMon": 200, "askMon": 200 },
  "position": { "side": "short", "size": 200, "entryPrice": 0.022633, "unrealizedUsd": -0.0006, "unrealizedMon": -0.027 },
  "totals": { "blocks": 3, "decisions": 3, "quotes": 3, "fills": 1, "reverted": 0, "lateBlocks": 0, "jevUsd": 0.000004, "gasMon": 0.107, "gasUsd": 0.0024, "realizedUsd": 0, "pnlUsd": -0.003, "pnlMon": -0.13, "pnlPct": -0.003 }
}

Every block the model is asked about the move over HORIZON_BLOCKS (default 100, ~30 s) and answers buy or sell. quote is the order that block put on the book: a post-only limit order of TRADE_SIZE_MON on that side, QUOTE_INSIDE_TICKS inside the touch (clamped to the touch when the spread is too tight), in one batchUpdate that also cancels everything we had resting (cancel). hold appears only with decision.late: true, when the model missed the block and nothing was posted. When the position cap (or, live, margin funds) blocks a side, the quote goes on the other side with capped: true and probabilities still show the model's call. resting is our size known to be on the book after this block. upIn10 equals the buy probability.

Live sends are fired and forgotten, so the block event carries the intent: status: "sent", gasMon is gasLimit x (last known base fee + priority). Monad charges the gas limit, so that is the real cost whether the order lands or not. The receipt arrives a block or two later as its own SSE event:

event: quote
data: { "block": 105488269, "quote": { …, "status": "placed", "orderId": 100295812, "gasMon": 0.0357 } }

status becomes placed (with the order id) or reverted (the book moved through the price before the tx landed, or a cancelled order had already filled). No receipt after 10 blocks gives lost. Fills are not in our own transactions: someone else's taker order hits our resting one, and the Trade log for it arrives via the same eth_getLogs poll that feeds the model. Each block with fills gets its own SSE event, and position, realizedUsd and fills update then:

event: fill
data: { "block": 105488271, "fill": { "side": "buy", "size": 200, "price": 0.022629, "txHash": "0x…", "orderId": 100295812, "simulated": false } }

txHash is the taker's transaction. In a dry run the quote is status: "sim": the order rests for one block and a real print crossing its price fills it (simulated: true).

Layout

src/config.ts   env
src/chain.ts    block feed (WebSocket newHeads + polling backstop, newest block only), raw RPC
src/book.ts     one-eth_call order book reader (decodes getL2Book, merges the AMM vault)
src/market.ts   Kuru: read book, hand-encoded batchUpdate (cancel + post-only place), margin deposits, local nonce, async confirmation
src/model.ts    Model interface, JevModel (AI SDK experimental_evaluate), MockModel
src/trader.ts   the loop: one in flight, hold when late, position and P&L accounting
src/server.ts   Bun.serve: snapshot, history, SSE

The 300 ms budget

A decision and an order have to fit in one block, so the hot loop makes exactly two RPC round trips: one eth_call for the book (~18 ms on the public RPC, READ_RPC_URL) and one eth_sendRawTransaction (RPC_URL), which returns as soon as the tx is accepted. Nothing else is on the path — no eth_estimateGas (Monad charges gas on the limit, so the limit is hardcoded or derived once at startup), no eth_sendRawTransactionSync (it blocks until the tx is Proposed), no gas price lookup (static type-2 fees: MAX_FEE_GWEI cap, 2 gwei priority; the effective price is base + priority). Receipts, the fee estimate and the vault check run off the hot path on later blocks. Measured in a dry run with the mock model: read p50 18 ms, whole loop p50 100 ms (80 ms of it the mock's inference stand-in).

bun run scripts/bench-read.ts     # book reader vs the SDK: exactness and latency
bun run scripts/dry-encode.ts     # signs a buy and a sell offline, asserts the calldata matches the SDK

jev-trader (jarrodwatts/jev-trader)

Searching Database…

3K ·GitHub
Jev-trader
What is this?An autonomous crypto trading bot for Monad: an AI model watches the Kuru MON-USDC order book and answers buy or sell every block (~300 ms), posting a post-only limit order each time.
Is this a hosted service I sign up for, or something I run myself?Something you run yourself: a Bun server that trades and also serves a small dashboard, so the bot, its API and the live event stream all live in one process on your machine.
How do I get it running?cp .env.example .env, bun install, bun run start. Without a PRIVATEKEY it starts in dry-run mode: real order book, real decisions, simulated fills — so you can try it risk-free.
Do I need an AI API key to use it?Just Bun and a Monad RPC endpoint. The default model is a mock momentum heuristic, so no AI key is needed; set MODEL=jev and TYPESAFEAIAPIKEY to use the real Jev AI model.
Is there a catch to running it live?Gas: Monad charges the gas limit, so every posted order costs gas whether or not it lands. A quote can also come back reverted if the book moves through your price before the tx lands.
Is 300 ms really enough to read the book, decide and post an order?Yes, by design. The hot loop makes exactly two RPC round trips: one eth_call for the order book (p50 18 ms on the public RPC) and one raw transaction send. In a measured dry run the whole loop was p50 100 ms, 80 ms of it the mock model's stand-in inference.
What happens if the model is too slow for a block?It posts nothing that block: hold shows up with decision.late set to true. Receipts can also come back reverted if the book moved through the price first, or lost if no receipt lands within 10 blocks.
How does it learn about fills if they are other people's transactions?Fills are detected through the same eth_getLogs poll that feeds the model — the taker's tx hash arrives with the fill, and position, realized P&L and fill counts update via a dedicated SSE event.
What are similar projects?pons-copy-trading-bot, StockSharp, Trpjan-solana-trading-toolkit, beebots, astra-quant-agent, pons-sniper-bot, hummingbot, gekko
Which topics is it in?dex, crypto-trading, defi, sse, trading-bot, algorithmic-trading, crypto, trading, bun, blockchain, finance, real-time
Creator
jarrodwatts
Size
0.1 MB
Stars
3K
Updated
CommitOct 13
Age
1mo
Commits · 90 Days