everyblock-mcp 0.2.0 → 0.4.0

package/README.md

@@ -26,6 +26,7 @@ With neither `RPC_URL` nor `EVERYBLOCK` set it talks to the live Monad testnet d
 | `split` / `merge` | yes | Mints complete sets (1 UP + 1 DOWN for $1.00), or burns them back into collateral. |
 | `faucet` | yes | Mints TestUSD collateral (testnet and local only). |
 | `open_market` | yes | Opens the current (or next) market for a feed when no keeper has; returns the existing id if it is open. |
+| `register_agent` | signs | Signs "I am an agent called X" with the wallet and registers it with the app, so the leaderboard shows the name with an Agent badge. No transaction. |
 | `settle` | yes | Proves a market's price to beat and/or its result with signed Pyth prices from the app's `/api/proof` (no Pyth key needed), paying Pyth's update fee. |
 
 Every write returns the transaction hash and the decoded result (events and amounts). Writes run one at a time.

package/dist/abi.js

@@ -22,10 +22,28 @@ export const everyblockAbi = [
                 "name": "owner_",
                 "type": "address",
                 "internalType": "address"
+            },
+            {
+                "name": "batchSeconds_",
+                "type": "uint256",
+                "internalType": "uint256"
             }
         ],
         "stateMutability": "nonpayable"
     },
+    {
+        "type": "function",
+        "name": "BATCH_SECONDS",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint256",
+                "internalType": "uint256"
+            }
+        ],
+        "stateMutability": "view"
+    },
     {
         "type": "function",
         "name": "CENT",
@@ -130,6 +148,30 @@ export const everyblockAbi = [
         ],
         "stateMutability": "view"
     },
+    {
+        "type": "function",
+        "name": "batchWindow",
+        "inputs": [
+            {
+                "name": "batchId",
+                "type": "uint256",
+                "internalType": "uint256"
+            }
+        ],
+        "outputs": [
+            {
+                "name": "start",
+                "type": "uint256",
+                "internalType": "uint256"
+            },
+            {
+                "name": "end",
+                "type": "uint256",
+                "internalType": "uint256"
+            }
+        ],
+        "stateMutability": "view"
+    },
     {
         "type": "function",
         "name": "claim",
@@ -238,6 +280,19 @@ export const everyblockAbi = [
         ],
         "stateMutability": "nonpayable"
     },
+    {
+        "type": "function",
+        "name": "currentBatch",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint256",
+                "internalType": "uint256"
+            }
+        ],
+        "stateMutability": "view"
+    },
     {
         "type": "function",
         "name": "downBalance",
@@ -1358,6 +1413,11 @@ export const everyblockAbi = [
         "name": "AlreadyResolved",
         "inputs": []
     },
+    {
+        "type": "error",
+        "name": "BadBatchSeconds",
+        "inputs": []
+    },
     {
         "type": "error",
         "name": "BadPrice",

package/dist/chain.js

@@ -14,7 +14,7 @@ export const MONAD_MAINNET = 143;
 export const MONAD_TESTNET = 10143;
 /** The live Monad testnet deployment (docs/SUBMISSION.md, "Deployed contracts"). */
 export const TESTNET_RPC = "https://testnet-rpc.monad.xyz";
-export const TESTNET_EVERYBLOCK = "0x034ebcA29FcAdDF0F434Dd63C75e719b1dC62dB5";
+export const TESTNET_EVERYBLOCK = "0x3aB7904B9Be8c70f2084082b0230238727cC8C3B";
 /** The hosted web app's proof endpoint for the testnet deployment. */
 export const TESTNET_PROOF_URL = "https://everyblock-gray.vercel.app/api/proof";
 export const ANVIL = 31337;
@@ -87,9 +87,11 @@ export async function connect(cfg) {
         account = cfg.unlockedAccount;
     }
     const wallet = account ? createWalletClient({ transport: http(cfg.rpcUrl) }) : null;
-    const [collateral, cent] = await Promise.all([
+    const [collateral, cent, batchSeconds] = await Promise.all([
         pub.readContract({ address: cfg.everyblock, abi: everyblockAbi, functionName: "collateral" }),
         pub.readContract({ address: cfg.everyblock, abi: everyblockAbi, functionName: "CENT" }),
+        // Deployments from before batch windows have no BATCH_SECONDS: there a batch is one block.
+        pub.readContract({ address: cfg.everyblock, abi: everyblockAbi, functionName: "BATCH_SECONDS" }).catch(() => 0n),
     ]);
     const share = 100n * cent;
     const digits = String(share).length - 1;
@@ -112,6 +114,7 @@ export async function connect(cfg) {
         maxSpend,
         logRange: cfg.logRange,
         logLookback: cfg.logLookback,
+        batchSeconds: Number(batchSeconds),
         proofUrl: cfg.proofUrl === undefined ? (chainId === MONAD_TESTNET ? TESTNET_PROOF_URL : undefined) : cfg.proofUrl || undefined,
         queue: Promise.resolve(),
     };
@@ -200,3 +203,5 @@ export function reason(e) {
     }
     return e instanceof Error ? e.message.split("\n")[0] : String(e);
 }
+/** The batch an order sent now joins: the time window, or the block on per-block deployments. */
+export const batchAt = (ctx, t) => ctx.batchSeconds ? t.timestamp / BigInt(ctx.batchSeconds) : t.number;

package/dist/server.js

@@ -3,15 +3,15 @@ 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 { FEED_NAMES, feeBps, MONAD_MAINNET, now, read, readToken, reason, send, serialize, writeBlocker, batchAt, } 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).
+- There is no continuous order book. All orders sent in the same batch window (a few seconds: the contract's BATCH_SECONDS; one block on older deployments) form one batch that clears at ONE uniform price after the window ends, so being first or fast inside it 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 batch. After its window ends, 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.
 
@@ -231,7 +231,7 @@ async function quote(ctx, a) {
             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.",
+            note: "The order joins the current batch and clears at one price for everyone once the batch's window ends; you never pay more than your limit. Claim it with its nonce afterwards.",
         },
     };
 }
@@ -298,8 +298,8 @@ export function createServer(ctx) {
     }));
     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).") },
+        description: "The order book of one batch (a market's orders from one batch window: batchId = floor(time / BATCH_SECONDS), or the block number on older deployments): 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("The batch id (from place_order or get_positions).") },
         annotations: readOnly,
     }, guarded(async ({ marketId, batchId }) => ok(await batchView(ctx, BigInt(marketId), BigInt(batchId)))));
     server.registerTool("get_positions", {
@@ -354,7 +354,7 @@ export function createServer(ctx) {
                 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",
+                status: cleared ? "cleared: claim it" : BigInt(batchId) === batchAt(ctx, { timestamp, number }) ? "in the current batch" : "waiting to clear (claiming clears it)",
                 claim,
             });
         }
@@ -400,7 +400,7 @@ export function createServer(ctx) {
     }, 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.",
+        description: "Sends a limit order into the current 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. The order lives one batch: once its window ends, 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) => {
@@ -423,13 +423,13 @@ export function createServer(ctx) {
                 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).`,
+                next: `Batch ${ev?.batchId} clears once its window has passed${ctx.batchSeconds ? ` (${ctx.batchSeconds} s batches)` : ""}. 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.",
+        description: "Settles your orders whose batch window has ended (clearing the batch first if nobody has): 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 }) => {
@@ -613,8 +613,37 @@ export function createServer(ctx) {
             });
         });
     }));
+    server.registerTool("register_agent", {
+        title: "Register as an agent",
+        description: "Signs a message with this server's wallet saying it is an AI agent with the given name, and registers it with the Everyblock app, so the leaderboard shows the name with an Agent badge and in the Agents tab. Costs nothing (a signature, not a transaction). Run it again to change the name.",
+        inputSchema: { name: z.string().describe("2-32 characters: letters, digits, spaces, _ . or -. Shown on the leaderboard.") },
+        annotations: { ...writes, idempotentHint: true },
+    }, guarded(async ({ name }) => {
+        if (!ctx.wallet || !ctx.account || !ctx.address)
+            return fail("this server is read-only: set MCP_PRIVATE_KEY to register a wallet");
+        if (!ctx.proofUrl)
+            return fail("no app endpoint configured (set EVERYBLOCK_PROOF_URL to the app's /api/proof)");
+        const clean = name.trim();
+        if (!AGENT_NAME_RE.test(clean))
+            return fail("name must be 2-32 letters, digits, spaces, _ . or -");
+        const message = `Register on Everyblock as an AI agent\nName: ${clean}\nAddress: ${ctx.address.toLowerCase()}`;
+        const signature = await ctx.wallet.signMessage({ account: ctx.account, message });
+        const url = new URL("/api/agents", ctx.proofUrl).toString();
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ address: ctx.address, name: clean, signature }),
+            signal: AbortSignal.timeout(20_000),
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            return fail(`registry: ${body.error ?? `HTTP ${res.status}`}`);
+        return ok({ registered: true, agent: body.agent, leaderboard: new URL("/leaderboard", ctx.proofUrl).toString() });
+    }));
     return server;
 }
+/** Mirrors web/lib/agents.ts NAME_RE; the app checks again. The signed message must match agentMessage() there. */
+const AGENT_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9 _.\-]{1,31}$/;
 const PYTH_FEE_ABI = [
     {
         type: "function",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "everyblock-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "MCP server that lets any AI agent read, quote and trade Everyblock's per-block UP/DOWN markets.",
   "engines": {