everyblock-mcp 0.2.0

package/dist/server.js

@@ -0,0 +1,638 @@
+// The Everyblock MCP server: tools an AI agent uses to read, quote and trade Everyblock markets.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { isAddress } from "viem";
+import { z } from "zod";
+import { everyblockAbi } from "./abi.js";
+import { FEED_NAMES, feeBps, MONAD_MAINNET, now, read, readToken, reason, send, serialize, writeBlocker, } from "./chain.js";
+import { centsToUsd, clearBatch, describeKind, escrowOf, feeOn, GRACE, isBid, kindOf, KINDS, marketStatus, meanPrice, OUTCOMES, ownPriceAt, priceOf, scenarios, tickOf, usd, WINDOW, } from "./orders.js";
+export const INSTRUCTIONS = `Everyblock runs short crypto UP/DOWN markets (e.g. "is BTC/USD higher at the close than at the open?") on Monad.
+
+How it works:
+- Each market has an open and a close time (5 minutes on the live schedule). The strike is the mean of 12 Pyth prices over the 60 s before the open; the closing price is the mean of 12 Pyth prices over the 60 s from the close. UP wins if the closing mean is above the strike, DOWN if below; a tie, or no proof within an hour, voids the market and every share redeems for $0.50.
+- A winning share pays $1.00. Prices are in cents (1-99): buying UP at 60 means paying at most $0.60 per share.
+- There is no continuous order book. All orders sent in the same block form one batch that clears at ONE uniform price after the block ends, so being first or fast in a block gives no advantage. Orders better than the clearing price fill fully, orders at it may fill pro rata, worse ones do not fill. Buyers never pay more than their limit and get back any price improvement.
+- Orders live for one block. After it, call claim with the order's nonce to collect the fill, the refund of anything unfilled and the price improvement. Claiming is required even if the order did not fill (that returns the escrow).
+- After a market resolves, call redeem to turn winning shares into collateral. Claim open orders first.
+- split turns $1 of collateral into 1 UP + 1 DOWN (needed before you can sell shares you do not own); merge does the reverse.
+
+Typical flow: list_markets -> preview_order -> place_order -> (next block) claim -> (after resolution) get_positions -> redeem.
+Amounts are shown in dollars (strings) and in raw collateral units (6 decimals). Writes are capped per call by the server's limits and refused on chains not in its allowlist.`;
+const MAX_ORDERS_SCANNED = 50n;
+// ------------------------------------------------------------------------------------------------
+// Output helpers
+// ------------------------------------------------------------------------------------------------
+const json = (v) => JSON.stringify(v, (_, x) => (typeof x === "bigint" ? x.toString() : x), 2);
+const ok = (v) => ({ content: [{ type: "text", text: json(v) }] });
+const fail = (msg) => ({ content: [{ type: "text", text: `Error: ${msg}` }], isError: true });
+function guarded(fn) {
+    return async (args) => {
+        try {
+            return await fn(args);
+        }
+        catch (e) {
+            return fail(reason(e));
+        }
+    };
+}
+const iso = (t) => new Date(Number(t) * 1000).toISOString();
+const feedName = (id) => FEED_NAMES[id.toLowerCase()] ?? id;
+const tx = (s) => ({ txHash: s.txHash, blockNumber: s.blockNumber, gasUsed: s.gasUsed });
+const eventArgs = (s, name) => s.events.find((e) => e.name === name)?.args;
+async function lastClearing(ctx, marketId, latest) {
+    const stop = latest > ctx.logLookback ? latest - ctx.logLookback : 0n;
+    for (let to = latest; to >= stop;) {
+        const from = to - ctx.logRange + 1n > stop ? to - ctx.logRange + 1n : stop;
+        const logs = await ctx.pub.getContractEvents({
+            address: ctx.everyblock,
+            abi: everyblockAbi,
+            eventName: "BatchCleared",
+            args: { marketId },
+            fromBlock: from,
+            toBlock: to,
+        });
+        const traded = logs.filter((l) => l.args.clearingTick !== 0);
+        const last = traded.at(-1);
+        if (last) {
+            const a = last.args;
+            return { batchId: a.batchId, priceCents: a.clearingTick, priceUsd: centsToUsd(a.clearingTick), volume: a.volume };
+        }
+        if (from === 0n)
+            break;
+        to = from - 1n;
+    }
+    return null;
+}
+async function marketView(ctx, marketId, t, latestBlock) {
+    const [m, outcome, fee] = await Promise.all([
+        read(ctx, "getMarket", [marketId]),
+        read(ctx, "outcome", [marketId]),
+        feeBps(ctx, marketId),
+    ]);
+    const status = marketStatus(t, m.openTime, m.closeTime, outcome);
+    const deadline = m.closeTime + WINDOW + GRACE;
+    return {
+        marketId,
+        feed: { id: m.feedId, name: feedName(m.feedId) },
+        openTime: m.openTime,
+        closeTime: m.closeTime,
+        open: iso(m.openTime),
+        close: iso(m.closeTime),
+        status,
+        secondsToOpen: status === "upcoming" ? m.openTime - t : 0n,
+        secondsToClose: status === "trading" || status === "upcoming" ? m.closeTime - t : 0n,
+        strike: meanPrice(m.strikeSum, m.expo, m.strikeSet),
+        closePrice: m.outcome !== 0 ? meanPrice(m.closeSum, m.expo, true) : null,
+        outcome: OUTCOMES[outcome],
+        settlementDeadline: iso(deadline),
+        pendingBatch: m.pendingBatch === 0n ? null : m.pendingBatch,
+        fee: { bps: fee.bps, source: fee.source },
+        lastClearing: latestBlock === null ? undefined : await lastClearing(ctx, marketId, latestBlock),
+    };
+}
+async function batchView(ctx, marketId, batchId) {
+    const [b, cleared] = await Promise.all([
+        read(ctx, "getBatch", [marketId, batchId]),
+        read(ctx, "isCleared", [marketId, batchId]),
+    ]);
+    const [bidBits, askBits, clearingTick, volume, bidFill, askFill] = b;
+    const bits = bidBits | askBits;
+    const ticks = [];
+    for (let t = 1; t <= 99; t++)
+        if ((bits >> BigInt(t)) & 1n)
+            ticks.push(t);
+    const levels = await Promise.all(ticks.map(async (tick) => {
+        const [bid, ask] = (await read(ctx, "getLevel", [marketId, batchId, tick]));
+        return { tick, bid, ask };
+    }));
+    const shown = levels.map((l) => ({ tick: l.tick, priceUsd: centsToUsd(l.tick), bidShares: l.bid, askShares: l.ask }));
+    const result = (c) => c.tick === 0
+        ? { traded: false }
+        : {
+            traded: true,
+            priceCents: c.tick,
+            upPriceUsd: centsToUsd(c.tick),
+            downPriceUsd: centsToUsd(100 - c.tick),
+            volume: c.volume,
+            bidFillAtTick: c.bidFillAtTick,
+            askFillAtTick: c.askFillAtTick,
+        };
+    return {
+        marketId,
+        batchId,
+        cleared,
+        note: "Prices are cents of UP: a bid is a Buy UP (or a Sell DOWN at 100 - tick), an ask a Sell UP (or a Buy DOWN at 100 - tick).",
+        levels: shown,
+        clearing: cleared ? result({ tick: clearingTick, volume, bidFillAtTick: bidFill, askFillAtTick: askFill }) : null,
+        indicative: cleared
+            ? undefined
+            : { ...result(clearBatch(levels)), note: "Not cleared yet: this is what it would clear at with the orders so far." },
+    };
+}
+async function currentAndNext(ctx, feeds, t) {
+    const out = [];
+    for (const feedId of feeds) {
+        const d = (await read(ctx, "feedDuration", [feedId]));
+        if (d === 0n)
+            continue;
+        const cur = (t / d) * d;
+        for (const openTime of [cur, cur + d]) {
+            out.push({ feedId, duration: d, openTime, marketId: (await read(ctx, "marketOf", [feedId, openTime])) });
+        }
+    }
+    return out;
+}
+function resolveFeeds(ctx, feed) {
+    if (!feed)
+        return ctx.feeds;
+    const f = feed.toLowerCase();
+    const match = ctx.feeds.filter((id) => id.toLowerCase() === f || feedName(id).toLowerCase().startsWith(f));
+    if (match.length === 0)
+        throw new Error(`unknown feed ${feed}; configured: ${ctx.feeds.map(feedName).join(", ")}`);
+    return match;
+}
+async function quote(ctx, a) {
+    const marketId = BigInt(a.marketId);
+    const size = BigInt(a.size);
+    const kind = kindOf(a.side, a.outcome);
+    const { timestamp } = await now(ctx);
+    const [m, outcome, fee] = await Promise.all([
+        read(ctx, "getMarket", [marketId]),
+        read(ctx, "outcome", [marketId]),
+        feeBps(ctx, marketId),
+    ]);
+    const status = marketStatus(timestamp, m.openTime, m.closeTime, outcome);
+    const escrow = escrowOf(kind, a.price, size, ctx.cent, fee.bps);
+    const s = scenarios(kind, a.price, size, ctx.cent, fee.bps);
+    const notional = size * BigInt(a.price) * ctx.cent;
+    const problems = [];
+    if (status !== "trading")
+        problems.push(`market is ${status}, not trading (open ${iso(m.openTime)}, close ${iso(m.closeTime)})`);
+    if (size > ctx.maxOrderSize)
+        problems.push(`size ${size} is over this server's limit of ${ctx.maxOrderSize} shares`);
+    if (escrow.collateral > ctx.maxSpend) {
+        problems.push(`escrow $${usd(escrow.collateral, ctx.cent)} is over this server's limit of $${usd(ctx.maxSpend, ctx.cent)} per call`);
+    }
+    let wallet;
+    if (ctx.address) {
+        const [bal, allowance, up, down] = await Promise.all([
+            readToken(ctx, "balanceOf", [ctx.address]),
+            readToken(ctx, "allowance", [ctx.address, ctx.everyblock]),
+            read(ctx, "upBalance", [marketId, ctx.address]),
+            read(ctx, "downBalance", [marketId, ctx.address]),
+        ]);
+        if (bal < escrow.collateral)
+            problems.push(`collateral balance $${usd(bal, ctx.cent)} is below the escrow`);
+        if (up < escrow.up)
+            problems.push(`you hold ${up} UP of this market; selling ${size} needs them (split or buy first)`);
+        if (down < escrow.down)
+            problems.push(`you hold ${down} DOWN of this market; selling ${size} needs them (split or buy first)`);
+        wallet = {
+            account: ctx.address,
+            collateralUsd: usd(bal, ctx.cent),
+            upShares: up,
+            downShares: down,
+            approvalNeeded: allowance < escrow.collateral,
+        };
+    }
+    const money = (v) => (v === undefined ? undefined : { usd: usd(v, ctx.cent), units: v });
+    return {
+        marketId,
+        kind,
+        size,
+        status,
+        problems,
+        escrowCollateral: escrow.collateral,
+        view: {
+            market: { marketId, feed: feedName(m.feedId), status, close: iso(m.closeTime), secondsToClose: status === "trading" ? m.closeTime - timestamp : 0n },
+            order: {
+                side: a.side,
+                outcome: a.outcome,
+                kind: KINDS[kind],
+                limitCents: a.price,
+                limitUsd: centsToUsd(a.price),
+                size,
+                book: isBid(kind) ? "bid" : "ask",
+                upBookTick: tickOf(kind, a.price),
+            },
+            escrow: { collateral: money(escrow.collateral), upShares: escrow.up, downShares: escrow.down },
+            ifFullyFilledAtLimit: {
+                maxCost: money(s.maxCost),
+                payoutIfWins: money(s.payoutIfWins),
+                minProceeds: money(s.minProceeds),
+                maxProfit: money(s.maxProfit),
+                maxLoss: money(s.maxLoss),
+            },
+            fee: {
+                bps: fee.bps,
+                source: fee.source,
+                estimateAtLimit: money(feeOn(notional, fee.bps)),
+            },
+            limits: { maxOrderSize: ctx.maxOrderSize, maxSpendUsd: usd(ctx.maxSpend, ctx.cent) },
+            wallet,
+            ok: problems.length === 0,
+            problems,
+            note: "The order joins the current block's batch and clears at one price for everyone once the block ends; you never pay more than your limit. Claim it with its nonce afterwards.",
+        },
+    };
+}
+// ------------------------------------------------------------------------------------------------
+// Server
+// ------------------------------------------------------------------------------------------------
+const id = z.number().int().positive();
+const orderShape = {
+    marketId: id.describe("Market id (from list_markets)."),
+    side: z.enum(["buy", "sell"]).describe("buy or sell."),
+    outcome: z.enum(["up", "down"]).describe("The outcome traded: up (price rises) or down."),
+    price: z
+        .number()
+        .int()
+        .min(1)
+        .max(99)
+        .describe("Limit in cents of that outcome, 1-99: the most a buyer pays, the least a seller takes, per $1 share."),
+    size: z.number().int().positive().describe("Number of shares; each pays $1.00 if its outcome wins."),
+};
+export function createServer(ctx) {
+    const server = new McpServer({ name: "everyblock", version: "0.1.0" }, { instructions: INSTRUCTIONS });
+    const readOnly = { readOnlyHint: true, openWorldHint: true };
+    const writes = { readOnlyHint: false, destructiveHint: false, openWorldHint: true };
+    server.registerTool("list_markets", {
+        title: "List markets",
+        description: "The current and next market of every listed feed: times, status (upcoming/trading/closed/resolved/void), strike, outcome, last clearing price and fee. Start here to find a marketId to trade. A slot shown with marketId null has not been opened yet (the keeper opens it; anyone may).",
+        inputSchema: { feed: z.string().optional().describe("Only this feed: a symbol like BTC or a Pyth feed id.") },
+        annotations: readOnly,
+    }, guarded(async ({ feed }) => {
+        const { timestamp, number } = await now(ctx);
+        const slots = await currentAndNext(ctx, resolveFeeds(ctx, feed), timestamp);
+        const markets = await Promise.all(slots.map((s) => s.marketId === 0n
+            ? {
+                marketId: null,
+                feed: { id: s.feedId, name: feedName(s.feedId) },
+                openTime: s.openTime,
+                closeTime: s.openTime + s.duration,
+                open: iso(s.openTime),
+                close: iso(s.openTime + s.duration),
+                status: "not opened",
+            }
+            : marketView(ctx, s.marketId, timestamp, number)));
+        return ok({ chainId: ctx.chainId, block: number, time: iso(timestamp), markets });
+    }));
+    server.registerTool("get_market", {
+        title: "Get market",
+        description: "One market in detail: times, status, strike and closing price, outcome, fee, last clearing price, and the batch still waiting to clear (with its indicative price), plus your UP/DOWN balance if this server has a wallet.",
+        inputSchema: { marketId: id.describe("Market id.") },
+        annotations: readOnly,
+    }, guarded(async ({ marketId }) => {
+        const mid = BigInt(marketId);
+        const { timestamp, number } = await now(ctx);
+        const view = await marketView(ctx, mid, timestamp, number);
+        const pending = view.pendingBatch ? await batchView(ctx, mid, view.pendingBatch) : null;
+        let yours;
+        if (ctx.address) {
+            const [up, down] = await Promise.all([
+                read(ctx, "upBalance", [mid, ctx.address]),
+                read(ctx, "downBalance", [mid, ctx.address]),
+            ]);
+            yours = { account: ctx.address, upShares: up, downShares: down };
+        }
+        return ok({ ...view, pendingBatchBook: pending, yours });
+    }));
+    server.registerTool("get_batch", {
+        title: "Get batch",
+        description: "The order book of one batch (a market's orders from one block, batchId = block number): size resting at each tick on each side, and the clearing result (price, volume, fills at the clearing tick). A batch not cleared yet shows the indicative clearing price.",
+        inputSchema: { marketId: id.describe("Market id."), batchId: id.describe("Block number of the batch (from place_order or get_positions).") },
+        annotations: readOnly,
+    }, guarded(async ({ marketId, batchId }) => ok(await batchView(ctx, BigInt(marketId), BigInt(batchId)))));
+    server.registerTool("get_positions", {
+        title: "Get positions",
+        description: "An account's open (unclaimed) orders with what claim would pay now, its UP/DOWN balances in recent and listed markets with their redeemable value, and its collateral balance. Defaults to this server's wallet.",
+        inputSchema: {
+            account: z.string().optional().describe("Address to inspect; defaults to this server's wallet."),
+            marketIds: z.array(id).max(20).optional().describe("Extra market ids to include balances for."),
+        },
+        annotations: readOnly,
+    }, guarded(async ({ account, marketIds }) => {
+        const who = (account ?? ctx.address);
+        if (!who || !isAddress(who))
+            return fail("pass an account address (this server has no wallet)");
+        const { timestamp, number } = await now(ctx);
+        const n = (await read(ctx, "orderNonce", [who]));
+        const first = n > MAX_ORDERS_SCANNED ? n - MAX_ORDERS_SCANNED : 0n;
+        const orders = [];
+        const markets = new Set((marketIds ?? []).map(BigInt));
+        for (let nonce = first; nonce < n; nonce++) {
+            // viem decodes uint32/uint40 as numbers and uint64 as bigints.
+            let o;
+            try {
+                o = (await read(ctx, "getOrder", [who, nonce]));
+            }
+            catch {
+                continue; // claimed
+            }
+            const mid = BigInt(o.marketId);
+            const batchId = BigInt(o.batchId);
+            markets.add(mid);
+            const kind = o.kind;
+            const cleared = (await read(ctx, "isCleared", [mid, batchId]));
+            let claim = null;
+            if (cleared) {
+                const [filled, upOut, downOut, cashOut] = (await read(ctx, "previewClaim", [who, nonce]));
+                const [, c] = (await read(ctx, "orderFill", [who, nonce]));
+                claim = {
+                    filled,
+                    clearingPriceCents: c === 0 ? null : ownPriceAt(kind, c),
+                    upOut,
+                    downOut,
+                    cashOutUsd: usd(cashOut, ctx.cent),
+                    cashOut,
+                };
+            }
+            orders.push({
+                nonce,
+                marketId: mid,
+                batchId,
+                ...describeKind(kind),
+                kind: KINDS[kind],
+                limitCents: priceOf(kind, o.tick),
+                size: o.size,
+                status: cleared ? "cleared: claim it" : batchId === number ? "in the current block's batch" : "waiting to clear",
+                claim,
+            });
+        }
+        for (const s of await currentAndNext(ctx, ctx.feeds, timestamp))
+            if (s.marketId !== 0n)
+                markets.add(s.marketId);
+        const balances = [];
+        for (const mid of [...markets].sort((a, b) => (a < b ? -1 : 1))) {
+            const [up, down] = (await Promise.all([read(ctx, "upBalance", [mid, who]), read(ctx, "downBalance", [mid, who])]));
+            if (up === 0n && down === 0n)
+                continue;
+            const outcome = (await read(ctx, "outcome", [mid]));
+            const share = 100n * ctx.cent;
+            const value = outcome === 1 ? up * share : outcome === 2 ? down * share : outcome === 3 ? ((up + down) * share) / 2n : null;
+            balances.push({
+                marketId: mid,
+                upShares: up,
+                downShares: down,
+                outcome: OUTCOMES[outcome],
+                redeemableUsd: value === null ? null : usd(value, ctx.cent),
+                action: value === null ? "wait for resolution (or merge UP+DOWN pairs back to collateral)" : "redeem",
+            });
+        }
+        const [collateral, native] = await Promise.all([
+            readToken(ctx, "balanceOf", [who]),
+            ctx.pub.getBalance({ address: who }),
+        ]);
+        return ok({
+            account: who,
+            block: number,
+            collateral: { usd: usd(collateral, ctx.cent), units: collateral },
+            nativeBalanceWei: native,
+            openOrders: orders,
+            balances,
+            note: n > MAX_ORDERS_SCANNED ? `only the last ${MAX_ORDERS_SCANNED} order nonces were scanned` : undefined,
+        });
+    }));
+    server.registerTool("preview_order", {
+        title: "Preview order",
+        description: "Quotes an order without sending anything: which book side and tick it maps to, the escrow it locks, the worst/best case if fully filled at the limit, the fee, and whether it passes the market's state, your balances and this server's limits. Use before place_order.",
+        inputSchema: orderShape,
+        annotations: readOnly,
+    }, guarded(async (a) => ok((await quote(ctx, a)).view)));
+    server.registerTool("place_order", {
+        title: "Place order",
+        description: "Sends a limit order into the current block's batch (one transaction; plus a collateral approval first if needed, capped at this server's per-call spend limit). Returns the tx hash, the order's nonce and batchId (block). The order lives one block: afterwards call claim with its nonce to collect fills and refunds. Refused if over the server's size or spend limits, on a chain not allowed for writes, or if the market is not trading.",
+        inputSchema: orderShape,
+        annotations: writes,
+    }, guarded(async (a) => {
+        const blocked = writeBlocker(ctx);
+        if (blocked)
+            return fail(blocked);
+        return serialize(ctx, async () => {
+            const q = await quote(ctx, a);
+            if (q.problems.length)
+                return fail(`order refused: ${q.problems.join("; ")}`);
+            let approval;
+            const escrow = q.escrowCollateral;
+            if (escrow > 0n)
+                approval = await ensureAllowance(ctx, escrow);
+            const sent = await send(ctx, "everyblock", "placeOrder", [q.marketId, q.kind, a.price, q.size]);
+            const ev = eventArgs(sent, "OrderPlaced");
+            return ok({
+                placed: true,
+                ...tx(sent),
+                approval,
+                order: { ...q.view.order, nonce: ev?.nonce, batchId: ev?.batchId, upBookTick: ev?.tick },
+                escrow: q.view.escrow,
+                next: `Batch ${ev?.batchId} clears once its block has passed. Then call claim with nonces [${ev?.nonce}] (get_batch shows the clearing price).`,
+            });
+        });
+    }));
+    server.registerTool("claim", {
+        title: "Claim orders",
+        description: "Settles your orders whose batch has cleared (the block after they were placed or later): credits the UP/DOWN shares bought, pays the cash from sales, refunds anything unfilled plus price improvement. One transaction per nonce; returns each tx hash and what it paid. Order nonces come from place_order or get_positions.",
+        inputSchema: { nonces: z.array(z.number().int().min(0)).min(1).max(20).describe("Order nonces to claim.") },
+        annotations: writes,
+    }, guarded(async ({ nonces }) => {
+        const blocked = writeBlocker(ctx);
+        if (blocked)
+            return fail(blocked);
+        return serialize(ctx, async () => {
+            const results = [];
+            for (const nonce of nonces) {
+                try {
+                    const sent = await send(ctx, "everyblock", "claim", [BigInt(nonce)]);
+                    const c = eventArgs(sent, "Claimed");
+                    results.push({
+                        nonce,
+                        claimed: true,
+                        ...tx(sent),
+                        marketId: c?.marketId,
+                        batchId: c?.batchId,
+                        filled: c?.filled,
+                        upShares: c?.upOut,
+                        downShares: c?.downOut,
+                        cashUsd: c ? usd(c.cashOut, ctx.cent) : undefined,
+                        cashUnits: c?.cashOut,
+                    });
+                }
+                catch (e) {
+                    results.push({ nonce, claimed: false, error: reason(e) });
+                }
+            }
+            return ok({ results });
+        });
+    }));
+    server.registerTool("redeem", {
+        title: "Redeem",
+        description: "After a market resolves, burns all your UP and DOWN shares of it and pays $1.00 per winning share ($0.50 per share of either side if void). Claim open orders in that market first so their shares are included.",
+        inputSchema: { marketId: id.describe("Market id.") },
+        annotations: writes,
+    }, guarded(async ({ marketId }) => {
+        const blocked = writeBlocker(ctx);
+        if (blocked)
+            return fail(blocked);
+        return serialize(ctx, async () => {
+            const sent = await send(ctx, "everyblock", "redeem", [BigInt(marketId)]);
+            const r = eventArgs(sent, "Redeemed");
+            return ok({
+                redeemed: true,
+                ...tx(sent),
+                marketId,
+                upShares: r?.up,
+                downShares: r?.down,
+                payoutUsd: r ? usd(r.payout, ctx.cent) : undefined,
+                payoutUnits: r?.payout,
+            });
+        });
+    }));
+    server.registerTool("split", {
+        title: "Split collateral into UP + DOWN",
+        description: "Locks $1.00 of collateral per set and credits 1 UP + 1 DOWN share of the market per set, e.g. to sell one side. Allowed until the market closes; capped by this server's spend limit.",
+        inputSchema: { marketId: id.describe("Market id."), sets: z.number().int().positive().describe("Number of sets.") },
+        annotations: writes,
+    }, guarded(async ({ marketId, sets }) => {
+        const blocked = writeBlocker(ctx);
+        if (blocked)
+            return fail(blocked);
+        const cost = BigInt(sets) * 100n * ctx.cent;
+        if (cost > ctx.maxSpend) {
+            return fail(`split of $${usd(cost, ctx.cent)} is over this server's limit of $${usd(ctx.maxSpend, ctx.cent)} per call`);
+        }
+        return serialize(ctx, async () => {
+            const approval = await ensureAllowance(ctx, cost);
+            const sent = await send(ctx, "everyblock", "split", [BigInt(marketId), BigInt(sets)]);
+            return ok({ split: true, ...tx(sent), approval, marketId, sets, costUsd: usd(cost, ctx.cent), upShares: sets, downShares: sets });
+        });
+    }));
+    server.registerTool("merge", {
+        title: "Merge UP + DOWN into collateral",
+        description: "Burns 1 UP + 1 DOWN share per set and returns $1.00 of collateral per set. Works any time, even before resolution.",
+        inputSchema: { marketId: id.describe("Market id."), sets: z.number().int().positive().describe("Number of sets.") },
+        annotations: writes,
+    }, guarded(async ({ marketId, sets }) => {
+        const blocked = writeBlocker(ctx);
+        if (blocked)
+            return fail(blocked);
+        return serialize(ctx, async () => {
+            const sent = await send(ctx, "everyblock", "merge", [BigInt(marketId), BigInt(sets)]);
+            return ok({ merged: true, ...tx(sent), marketId, sets, returnedUsd: usd(BigInt(sets) * 100n * ctx.cent, ctx.cent) });
+        });
+    }));
+    server.registerTool("faucet", {
+        title: "Testnet faucet",
+        description: "Testnet only: mints free, valueless TestUSD collateral (10,000 per call) to this server's wallet. Refused on mainnet and when the collateral is not TestUSD. The wallet still needs a little native MON for gas.",
+        inputSchema: {},
+        annotations: { ...writes, idempotentHint: false },
+    }, guarded(async () => {
+        const blocked = writeBlocker(ctx);
+        if (blocked)
+            return fail(blocked);
+        if (ctx.chainId === MONAD_MAINNET)
+            return fail("the faucet is testnet only");
+        try {
+            await readToken(ctx, "FAUCET_AMOUNT");
+        }
+        catch {
+            return fail(`collateral ${ctx.collateral} is not TestUSD; there is no faucet`);
+        }
+        return serialize(ctx, async () => {
+            const sent = await send(ctx, "collateral", "faucet", []);
+            const bal = (await readToken(ctx, "balanceOf", [ctx.address]));
+            return ok({ minted: true, ...tx(sent), collateralUsd: usd(bal, ctx.cent), units: bal });
+        });
+    }));
+    server.registerTool("open_market", {
+        title: "Open a market",
+        description: "Opens the current (or next) market for a feed, so there is something to trade when no keeper runs. Anyone may open one; it costs gas only. If it is already open, returns its id without sending anything.",
+        inputSchema: {
+            feed: z.string().optional().describe('Feed name or id, e.g. "BTC" (default BTC).'),
+            when: z.enum(["current", "next"]).optional().describe("The slot trading now (default) or the next one."),
+        },
+        annotations: { ...writes, idempotentHint: true },
+    }, guarded(async ({ feed, when }) => {
+        const blocked = writeBlocker(ctx);
+        if (blocked)
+            return fail(blocked);
+        const [feedId] = resolveFeeds(ctx, feed ?? "BTC");
+        const d = (await read(ctx, "feedDuration", [feedId]));
+        if (d === 0n)
+            return fail(`${feedName(feedId)} is not listed`);
+        const t = (await now(ctx)).timestamp;
+        const openTime = (t / d) * d + (when === "next" ? d : 0n);
+        const existing = (await read(ctx, "marketOf", [feedId, openTime]));
+        if (existing !== 0n)
+            return ok({ opened: false, alreadyOpen: true, marketId: existing, feed: feedName(feedId), open: iso(openTime), close: iso(openTime + d) });
+        return serialize(ctx, async () => {
+            const sent = await send(ctx, "everyblock", "openMarket", [feedId, openTime]);
+            const created = eventArgs(sent, "MarketCreated");
+            return ok({ opened: true, ...tx(sent), marketId: created?.marketId, feed: feedName(feedId), open: iso(openTime), close: iso(openTime + d) });
+        });
+    }));
+    server.registerTool("settle", {
+        title: "Prove the price to beat or the result",
+        description: "Submits the signed Pyth prices that set a market's strike (after its open) or resolve it (about 70 s after its close), when no keeper has. Anyone may do this; it costs gas plus Pyth's tiny update fee. The prices come from the Everyblock app's proof endpoint, so no Pyth key is needed. Proves the strike first if it is missing.",
+        inputSchema: {
+            marketId: id.describe("Market id."),
+            what: z.enum(["strike", "result"]).optional().describe("strike: only the price to beat. result (default): the result, and the strike first if missing."),
+        },
+        annotations: writes,
+    }, guarded(async ({ marketId, what }) => {
+        const blocked = writeBlocker(ctx);
+        if (blocked)
+            return fail(blocked);
+        if (!ctx.proofUrl)
+            return fail("no proof endpoint configured (set EVERYBLOCK_PROOF_URL to the app's /api/proof)");
+        const m = (await read(ctx, "getMarket", [BigInt(marketId)]));
+        if (m.outcome !== 0)
+            return ok({ settled: false, alreadyResolved: true, marketId });
+        const steps = what === "strike" ? (m.strikeSet ? [] : ["strike"]) : m.strikeSet ? ["close"] : ["strike", "close"];
+        if (steps.length === 0)
+            return ok({ settled: false, strikeAlreadySet: true, marketId });
+        const pyth = (await read(ctx, "pyth"));
+        return serialize(ctx, async () => {
+            const done = [];
+            for (const w of steps) {
+                const res = await fetch(`${ctx.proofUrl}?market=${marketId}&window=${w}`, { signal: AbortSignal.timeout(20_000) });
+                const body = (await res.json().catch(() => ({})));
+                if (!res.ok || !body.updates) {
+                    const hint = res.status === 425 ? " (too early: the window's last price isn't out yet)" : "";
+                    throw new Error(`proof endpoint: ${body.error ?? `HTTP ${res.status}`}${hint}`);
+                }
+                const fee = (await ctx.pub.readContract({ address: pyth, abi: PYTH_FEE_ABI, functionName: "getUpdateFee", args: [body.updates] }));
+                const sent = await send(ctx, "everyblock", w === "strike" ? "setStrike" : "resolve", [BigInt(marketId), body.updates], fee);
+                done.push({ step: w === "strike" ? "strike" : "result", ...tx(sent) });
+            }
+            const after = (await read(ctx, "getMarket", [BigInt(marketId)]));
+            return ok({
+                settled: true,
+                marketId,
+                steps: done,
+                strike: meanPrice(after.strikeSum, after.expo, after.strikeSet),
+                closingPrice: after.outcome !== 0 ? meanPrice(after.closeSum, after.expo, true) : null,
+                outcome: OUTCOMES[after.outcome] ?? after.outcome,
+            });
+        });
+    }));
+    return server;
+}
+const PYTH_FEE_ABI = [
+    {
+        type: "function",
+        name: "getUpdateFee",
+        stateMutability: "view",
+        inputs: [{ name: "updateData", type: "bytes[]" }],
+        outputs: [{ name: "feeAmount", type: "uint256" }],
+    },
+];
+/**
+ * Tops the Everyblock allowance up to the per-call spend limit when it is below what a write needs, so the
+ * standing approval never exceeds MCP_MAX_SPEND_USD.
+ */
+async function ensureAllowance(ctx, needed) {
+    const allowance = (await readToken(ctx, "allowance", [ctx.address, ctx.everyblock]));
+    if (allowance >= needed)
+        return undefined;
+    const amount = needed > ctx.maxSpend ? needed : ctx.maxSpend;
+    const sent = await send(ctx, "collateral", "approve", [ctx.everyblock, amount]);
+    return { ...tx(sent), approvedUsd: usd(amount, ctx.cent) };
+}