@unhedged/mcp 0.1.3 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@ Model Context Protocol server for the [Unhedged](https://unhedged.gg) prediction
 
 ## What it does
 
-- Exposes 12 MCP **tools** over the Unhedged v1 REST API: search markets, read balances and portfolio, place bets and orders, cancel orders, request withdrawals, and read a market-maker profile.
+- Exposes MCP **tools** over the Unhedged v1 REST API: search markets, read balances and portfolio, place bets and orders (including batch place/replace), cancel orders, request withdrawals, and read a market-maker profile.
 - Ships 6 MCP **prompts** ("skills") — opinionated markdown workflows the agent can execute end-to-end (e.g. `place-hedged-position`, `cash-out`, `portfolio-review`).
 - Auto-generates an `Idempotency-Key` for every state-changing call. Each new call uses a fresh key, so ambiguous failures are not retried automatically. Check the account's transaction history before repeating a mutation; open orders and balances cannot rule out a filled order or completed withdrawal. Ask the user if the outcome remains uncertain.
 - Declares MCP tool annotations (`readOnlyHint`, `destructiveHint`); bets, orders, cancellations, and withdrawals are marked destructive. Confirmation behavior depends on the client.
@@ -20,6 +20,27 @@ The init wizard asks which client to wire up (Claude Desktop, Cursor, Claude CLI
 
 Mint an API key at <https://unhedged.gg/account/api-keys>. See the [API key minting walkthrough](#api-key-minting) below for recommended scope sets.
 
+## Upgrading from 0.1.3 to 0.2.0
+
+Version 0.2.0 adds centi-share support. MCP order quantities now use **two-decimal strings** in human shares, with a minimum of `"0.01"`. This is a breaking change from 0.1.3's integer quantity inputs.
+
+| Tool | Quantity format |
+|---|---|
+| `place_order` | `quantity: "1.00"` |
+| `batch_place_orders` | `quantity: "1.00"` in each order |
+| `replace_order` | `quantity: "1.00"` |
+| `batch_replace_orders` | `quantity: "1.00"` in each replacement |
+
+Use `"0.01"` for one hundredth of a share, `"1.00"` for one share, or `"1.25"` for one and a quarter shares. Order responses also return share quantities as decimal strings. REST's support for whole-number numeric inputs does not apply to these MCP tool schemas.
+
+To pin the release, configure your MCP client to launch:
+
+```bash
+npx -y @unhedged/mcp@0.2.0
+```
+
+Keep the existing API-key environment setting, then restart the MCP server or client to load the new version and tool schemas. See the [order API reference](https://unhedged.gg/docs/api#place-order) for REST request and response examples.
+
 ## Environment variables
 
 | Variable | Required | Description |
@@ -61,7 +82,10 @@ Tool descriptions are available in your MCP client. Quick reference:
 | `place_bet` | `bet:place` | yes |
 | `list_orders` | `order:read` | n/a |
 | `place_order` | `order:place` | yes |
+| `batch_place_orders` | `order:place` | yes |
 | `cancel_order` | `order:cancel` | yes |
+| `replace_order` | `order:place` + `order:cancel` | yes |
+| `batch_replace_orders` | `order:place` + `order:cancel` | yes |
 | `request_withdrawal` | `balance:withdraw` | yes |
 | `get_market_maker_profile` | `portfolio:read` | n/a |
 

package/dist/client/errors.js

@@ -18,6 +18,14 @@ export class UnhedgedApiError extends Error {
         this.retryable = args.status >= 500 || args.status === 429 || args.status === 0;
     }
     toAgentMessage(stateChanging = false) {
+        if (stateChanging && this.status === 400 &&
+            this.responseBody != null && typeof this.responseBody === 'object' &&
+            'results' in this.responseBody && Array.isArray(this.responseBody.results)) {
+            return (`Unhedged API returned 400: ${this.message}. The batch transaction committed. ` +
+                `Successful legs remain committed; failed replacements may have cancelled their source orders. ` +
+                `Do not repeat successful legs. Inspect each result before retrying or replacing orders.\n` +
+                JSON.stringify({ results: this.responseBody.results }, null, 2));
+        }
         if (this.missingScope) {
             return (`Unhedged API rejected the call (${this.status}): the API key is missing scope ` +
                 `"${this.missingScope}". Mint a new key including this scope at ` +

package/dist/client/types.d.ts

@@ -97,6 +97,7 @@ export interface PlaceBetResponse {
 }
 export interface MEOrder {
     id?: string | number;
+    client_order_id?: string | null;
     marketId: string;
     outcome: string;
     side: 'bid' | 'ask';
@@ -105,6 +106,10 @@ export interface MEOrder {
     triggerPrice?: string;
     quantity?: number;
     quoteQuantity?: string;
+    /** Filled contracts; remaining size is `quantity - cum_quantity`. */
+    cum_quantity?: number;
+    /** Filled quote notional string; remaining quote is `quote_quantity - cum_quote_quantity`. */
+    cum_quote_quantity?: string;
     status?: string;
     [key: string]: unknown;
 }
@@ -117,9 +122,21 @@ export interface ListOrdersResponse {
 export interface PlaceOrderResponse {
     order: MEOrder;
 }
+export interface BatchPlaceOrderResponse {
+    results: Array<{
+        order?: MEOrder;
+        err?: unknown;
+    }>;
+}
 export interface CancelOrderResponse {
     result: unknown;
 }
+export interface ReplaceOrderResponse {
+    result: unknown;
+}
+export interface BatchReplaceOrderResponse {
+    results: unknown[];
+}
 export interface EthereumWithdrawQuoteResponse {
     quote: {
         quoteId: string;

package/dist/safety/spend-cap.d.ts

@@ -1,7 +1,9 @@
+import BigNumber from 'bignumber.js';
 /**
  * In-process session spend cap. Tracks how much an agent has committed across
- * `place_bet` and `place_order` (bid side) calls within a single server
- * lifetime, and refuses further spend once the configured cap is reached.
+ * `place_bet`, `place_order` / `batch_place_orders` (bid side), and incremental
+ * bid notional from `replace_order` / `batch_replace_orders` within a single
+ * server lifetime, and refuses further spend once the configured cap is reached.
  *
  * Independent of (additive to) any rate or balance limits the backend enforces.
  * Resets when the process restarts.
@@ -16,15 +18,15 @@ export declare class SpendCapTracker {
     effectiveCap(): number | null;
     /**
      * Throws SpendCapExceededError if `amount` would push cumulative spend over
-     * the cap. If the cap is null, this is a no-op. Calls `commit` on success.
+     * the cap. If the cap is null, this is a no-op.
      */
-    reserve(amount: number, toolName: string): void;
+    reserve(amount: BigNumber.Value, toolName: string): void;
     /**
      * Return a previously reserved amount to the cap, e.g. when the backend
      * definitively rejected the placement (4xx) so nothing was actually spent.
      * Ambiguous failures (network errors, 5xx) should NOT be released.
      */
-    release(amount: number): void;
+    release(amount: BigNumber.Value): void;
 }
 export declare class SpendCapExceededError extends Error {
     readonly spent: number;

package/dist/safety/spend-cap.js

@@ -1,20 +1,22 @@
+import BigNumber from 'bignumber.js';
 /**
  * In-process session spend cap. Tracks how much an agent has committed across
- * `place_bet` and `place_order` (bid side) calls within a single server
- * lifetime, and refuses further spend once the configured cap is reached.
+ * `place_bet`, `place_order` / `batch_place_orders` (bid side), and incremental
+ * bid notional from `replace_order` / `batch_replace_orders` within a single
+ * server lifetime, and refuses further spend once the configured cap is reached.
  *
  * Independent of (additive to) any rate or balance limits the backend enforces.
  * Resets when the process restarts.
  */
 export class SpendCapTracker {
     cap;
-    spent = 0;
+    spent = new BigNumber(0);
     constructor(cap) {
         this.cap = cap;
     }
     /** How much has been committed so far (USD). */
     totalSpent() {
-        return this.spent;
+        return this.spent.toNumber();
     }
     /** Effective cap, or `null` if unset. */
     effectiveCap() {
@@ -22,22 +24,24 @@ export class SpendCapTracker {
     }
     /**
      * Throws SpendCapExceededError if `amount` would push cumulative spend over
-     * the cap. If the cap is null, this is a no-op. Calls `commit` on success.
+     * the cap. If the cap is null, this is a no-op.
      */
     reserve(amount, toolName) {
         if (this.cap === null)
             return;
-        if (!Number.isFinite(amount) || amount < 0) {
+        const value = new BigNumber(amount);
+        if (!value.isFinite() || value.lt(0)) {
             throw new SpendCapExceededError(`Tool ${toolName} attempted to reserve a negative or non-finite amount (${amount}). ` +
-                `Refusing as a safety measure.`, this.spent, this.cap);
+                `Refusing as a safety measure.`, this.totalSpent(), this.cap);
         }
-        if (this.spent + amount > this.cap) {
-            throw new SpendCapExceededError(`Refusing ${toolName}: this call would commit ${amount.toFixed(2)} USD, bringing the ` +
-                `session total to ${(this.spent + amount).toFixed(2)} USD and exceeding the configured ` +
+        const next = this.spent.plus(value);
+        if (next.gt(this.cap)) {
+            throw new SpendCapExceededError(`Refusing ${toolName}: this call would commit ${value.toFixed(2)} USD, bringing the ` +
+                `session total to ${next.toFixed(2)} USD and exceeding the configured ` +
                 `cap of ${this.cap.toFixed(2)} USD (UNHEDGED_MAX_SPEND_PER_SESSION). ` +
-                `Restart the MCP server or raise the cap to continue.`, this.spent, this.cap);
+                `Restart the MCP server or raise the cap to continue.`, this.totalSpent(), this.cap);
         }
-        this.spent += amount;
+        this.spent = next;
     }
     /**
      * Return a previously reserved amount to the cap, e.g. when the backend
@@ -47,9 +51,10 @@ export class SpendCapTracker {
     release(amount) {
         if (this.cap === null)
             return;
-        if (!Number.isFinite(amount) || amount <= 0)
+        const value = new BigNumber(amount);
+        if (!value.isFinite() || value.lte(0))
             return;
-        this.spent = Math.max(0, this.spent - amount);
+        this.spent = BigNumber.maximum(0, this.spent.minus(value));
     }
 }
 export class SpendCapExceededError extends Error {

package/dist/tools/orders.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import BigNumber from 'bignumber.js';
 import { defineTool, READ_ONLY } from './types.js';
 import { UnhedgedApiError } from '../client/errors.js';
 import { SpendCapExceededError } from '../safety/spend-cap.js';
@@ -13,7 +14,7 @@ Filters:
 - **includeTotal**: include an exact account-wide total.
 - **includeMarketDetails**: include compact market metadata for account-wide rows.
 
-Returns \`{ orders, nextCursor }\` and, when requested, \`total\` / \`markets\`. Follow \`nextCursor\` until it is null when a complete account-wide inventory is required. Each order has \`id\`, \`marketId\`, \`outcome\`, \`side\` (\`bid\` or \`ask\`), \`type\` (\`Limit | Market | StopLoss | TakeProfit\`), \`price\`, \`quantity\` or \`quoteQuantity\`, and status.
+Returns \`{ orders, nextCursor }\` and, when requested, \`total\` / \`markets\`. Follow \`nextCursor\` until it is null when a complete account-wide inventory is required. Each order has \`id\`, optional \`client_order_id\`, \`market_id\`, \`outcome\`, \`side\` (\`bid\` or \`ask\`), \`type\` (\`Limit | Market | StopLoss | TakeProfit\`), \`price\`, \`quantity\` or \`quote_quantity\`, and status. Pending conditional orders (StopLoss/TakeProfit) are included while open.
 
 Only works on CLOB markets — parimutuel markets won't have any orders to return.
 
@@ -43,15 +44,20 @@ Required parameters:
 - **outcome**: outcome label, e.g. \`"YES"\`, \`"NO"\`, \`"$95k - $100k"\`. Match exactly the labels from \`get_market\`.
 - **side**: \`"bid"\` to buy a contract on this outcome, \`"ask"\` to sell.
 - **type**: \`"Limit"\`, \`"Market"\`, \`"StopLoss"\`, or \`"TakeProfit"\`.
-- **One of** \`quantity\` (positive integer contract count, e.g. \`5\`) **or** \`quoteQuantity\` (decimal USD notional string with exactly 2 decimals). Not both.
+- **One of** \`quantity\` (contracts as a 2-decimal string, min \`"0.01"\`, e.g. \`"5.00"\`) **or** \`quoteQuantity\` (decimal USD notional string with exactly 2 decimals). Not both.
 
 Conditional parameters:
 - **price**: required for \`Limit\`. Decimal string with exactly 2 decimals, strictly between 0 and 1 (probability).
 - **triggerPrice**: required for \`StopLoss\` and \`TakeProfit\`. Same bounds as price.
 
-Returns \`{ order: ... }\` with the engine-assigned ID, status, and any immediate fills.
+Optional:
+- **clientOrderId**: your own id for this open order (1–64 chars, \`[A-Za-z0-9._:-]\`, case preserved). Unique among **open** orders for this balance in this market (all outcomes and API keys share that namespace). Echoed on the order as \`client_order_id\`. After the order closes the alias may be reused — that does **not** make a timed-out placement safe to retry with the same id.
 
-The MCP server automatically adds an \`Idempotency-Key\`.
+Returns \`{ order: ... }\` with the engine-assigned ID, optional \`client_order_id\`, status, and any immediate fills.
+
+The MCP server automatically adds a fresh \`Idempotency-Key\` on each call. It
+does not retry automatically, so calling this tool again creates a new request
+rather than replaying the first.
 
 Requires scope: \`order:place\`.
 
@@ -68,7 +74,8 @@ Buy 5 contracts of YES at probability 0.55:
   "side": "bid",
   "type": "Limit",
   "price": "0.55",
-  "quantity": 5
+  "quantity": "5.00",
+  "clientOrderId": "bot-42"
 }
 \`\`\`
 
@@ -88,22 +95,36 @@ Cancel one, several, or all of the user's open orders on a single CLOB market.
 
 Required:
 - **marketId**: market to cancel on.
-- **orderIds**: array of order IDs (as strings) to cancel. **Pass an empty array \`[]\` to cancel all of the user's open orders on the market.**
+- **orderIds**: array of numeric order IDs (as strings). May be \`[]\` when cancelling only by \`clientOrderIds\`, or when cancelling all.
+
+Optional:
+- **clientOrderIds**: array of client order IDs (same charset/length as placement). Targets are the **union** of \`orderIds\` and resolved \`clientOrderIds\`. Unresolved client IDs are soft failures (continue cancelling the rest; first failure in \`err\`). Case is preserved.
+
+**Cancel-all** (every open order for this balance on the market) runs only when **both** \`orderIds\` and \`clientOrderIds\` are empty (omit \`clientOrderIds\` or pass \`[]\`). A nonempty \`clientOrderIds\` list with \`orderIds: []\` is a **targeted** cancel, not cancel-all.
+
+Numeric IDs and client IDs are best-effort (\`dropped\` plus \`err\` on partial success). An alias can be reused after an order closes, so a later cancel by the same string may hit a **different** open order — do not treat repeat cancel as a durable receipt for the original intent.
 
-Returns \`{ result }\` with engine-side per-order outcomes.
+Returns \`{ result }\` with engine-side outcomes (typically \`dropped\` order ids).
 
-The market must still be ACTIVE and before the trading cutoff (\`scheduledResolutionTime\` or \`endTime\`); cancelling on a closed market is rejected.
+If the market is not ACTIVE or the trading cutoff has passed, REST returns HTTP
+200 with an empty \`dropped\` list without calling the engine.
 
-The MCP server adds an \`Idempotency-Key\` automatically.
+The MCP server adds a fresh \`Idempotency-Key\` on each call. The API response
+cache excludes \`DELETE\`, so cancel requests are not replay-protected.
 
 Requires scope: \`order:cancel\`.
 
 ### Examples
-Cancel two specific orders:
+Cancel two specific orders by numeric id:
 \`\`\`json
 { "marketId": "clxabc123...", "orderIds": ["1042", "1051"] }
 \`\`\`
 
+Cancel by client id only:
+\`\`\`json
+{ "marketId": "clxabc123...", "orderIds": [], "clientOrderIds": ["bot-42"] }
+\`\`\`
+
 Cancel **all** open orders on this market:
 \`\`\`json
 { "marketId": "clxabc123...", "orderIds": [] }
@@ -131,6 +152,13 @@ const positiveDecimalStringSchema = z
     const n = Number(value);
     return Number.isFinite(n) && n > 0;
 });
+/** Matches REST `clientOrderId` / `clientOrderIds`: 1–64 of [A-Za-z0-9._:-], case preserved. */
+const clientOrderIdSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[A-Za-z0-9._:-]+$/)
+    .describe('Client order id (1–64 chars, letters/digits/._:-). Unique among open orders per balance+market.');
 const placeSchema = {
     marketId: z.string().min(1),
     outcome: z.string().min(1).describe('Outcome label, e.g. "YES" or "$95k - $100k".'),
@@ -142,21 +170,23 @@ const placeSchema = {
     triggerPrice: probabilityStringSchema
         .optional()
         .describe('Trigger probability decimal string between 0 and 1 with exactly 2 decimals. Required for StopLoss/TakeProfit.'),
-    quantity: z
-        .number()
-        .int()
-        .positive()
+    quantity: positiveDecimalStringSchema
         .optional()
-        .describe('Number of contracts as a positive integer.'),
+        .describe('Number of contracts as a 2-decimal string (min "0.01").'),
     quoteQuantity: positiveDecimalStringSchema
         .optional()
         .describe('USD notional string with exactly 2 decimals. Use INSTEAD of quantity.'),
+    clientOrderId: clientOrderIdSchema.optional(),
 };
 const cancelSchema = {
     marketId: z.string().min(1),
     orderIds: z
         .array(z.string())
-        .describe('Order IDs to cancel. Pass [] to cancel ALL of the user\'s orders on this market.'),
+        .describe('Numeric order IDs to cancel. Pass [] with clientOrderIds for client-only cancel, or [] alone (and empty/omitted clientOrderIds) for cancel-all.'),
+    clientOrderIds: z
+        .array(clientOrderIdSchema)
+        .optional()
+        .describe('Optional client order IDs to cancel (union with orderIds). Unknown ids reject the whole request. Both lists empty = cancel-all.'),
 };
 /**
  * Best-effort client-side notional estimate for the spend cap.
@@ -164,17 +194,175 @@ const cancelSchema = {
  */
 function estimateBidNotional(args) {
     if (args.side !== 'bid')
-        return 0;
+        return new BigNumber(0);
     if (typeof args.quoteQuantity === 'string')
-        return Number(args.quoteQuantity);
-    if (args.type === 'Limit' && typeof args.price === 'string' && typeof args.quantity === 'number') {
-        const price = Number(args.price);
-        if (!Number.isFinite(price))
+        return finiteDecimal(args.quoteQuantity) ?? null;
+    if (args.type === 'Limit' && typeof args.price === 'string' && args.quantity != null) {
+        const price = new BigNumber(args.price);
+        const qty = new BigNumber(args.quantity);
+        if (!price.isFinite() || !qty.isFinite())
             return null;
-        return price * args.quantity;
+        return price.times(qty);
     }
     return null;
 }
+function isRecord(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+function isInternalCancelStatus(status) {
+    if (status === 'InternalCancel')
+        return true;
+    return isRecord(status) && Object.prototype.hasOwnProperty.call(status, 'InternalCancel');
+}
+function positiveNumericField(record, field) {
+    const value = record[field];
+    if (typeof value === 'number')
+        return Number.isFinite(value) && value > 0;
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) && parsed > 0;
+    }
+    return false;
+}
+/** Match backend `hasExecutedFill`: either base or quote cumulative fill counts. */
+function orderHasExecutedFill(order) {
+    return (positiveNumericField(order, 'cum_quantity') ||
+        positiveNumericField(order, 'cumQuantity') ||
+        positiveNumericField(order, 'cum_quote_quantity') ||
+        positiveNumericField(order, 'cumQuoteQuantity'));
+}
+/** Per-leg outcomes from a committed batch returned with HTTP 400. */
+function resultsFromApiError(err) {
+    if (!isRecord(err.responseBody) || !Array.isArray(err.responseBody.results))
+        return null;
+    return err.responseBody.results;
+}
+/** True when a batch-place leg committed buy exposure we should keep reserved. */
+function batchPlaceLegConsumedSpend(result) {
+    if (result == null || result.order == null)
+        return false;
+    if (!isRecord(result.order))
+        return false;
+    // Soft InternalCancel with no fills: nothing locked/spent — release like `{ err }`.
+    if (isInternalCancelStatus(result.order.status)) {
+        return orderHasExecutedFill(result.order);
+    }
+    return true;
+}
+/**
+ * True when a replace outcome kept incremental buy exposure.
+ * Used for single `replace_order` results and batch-replace legs.
+ * Releases `{ err }`, `unchanged`, and zero-fill InternalCancel replacements.
+ */
+function batchReplaceLegConsumedSpend(result) {
+    if (!isRecord(result))
+        return false;
+    if ('err' in result)
+        return false;
+    if (result.status === 'unchanged')
+        return false;
+    const replacement = result.replacementOrder ?? result.replacement_order;
+    if (isRecord(replacement) && isInternalCancelStatus(replacement.status)) {
+        return orderHasExecutedFill(replacement);
+    }
+    return true;
+}
+function orderIdOf(order) {
+    if (order.id == null)
+        return undefined;
+    return String(order.id);
+}
+function clientOrderIdOf(order) {
+    const value = order.client_order_id ?? order.clientOrderId;
+    return typeof value === 'string' ? value : undefined;
+}
+function sideOf(order) {
+    return order.side === 'bid' || order.side === 'ask' ? order.side : null;
+}
+function quoteQuantityOf(order) {
+    const value = order.quoteQuantity ?? order.quote_quantity;
+    return typeof value === 'string' ? value : undefined;
+}
+function finiteDecimal(value) {
+    if (typeof value !== 'number' && typeof value !== 'string')
+        return undefined;
+    const parsed = new BigNumber(value);
+    return parsed.isFinite() ? parsed : undefined;
+}
+function orderTypeOf(order) {
+    const value = order.type;
+    if (value === 'Limit' || value === 'Market' || value === 'StopLoss' || value === 'TakeProfit') {
+        return value;
+    }
+    return 'Limit';
+}
+function findOpenOrder(orders, identity) {
+    if (identity.orderId != null) {
+        return orders.find((order) => orderIdOf(order) === identity.orderId);
+    }
+    if (identity.clientOrderId != null) {
+        return orders.find((order) => clientOrderIdOf(order) === identity.clientOrderId);
+    }
+    return undefined;
+}
+/**
+ * Estimated buy notional still locked by an open source bid (remaining size).
+ * Partially filled quantity orders use `quantity - cum_quantity`; quote-budget
+ * orders use leftover `quote_quantity - cum_quote_quantity`.
+ */
+function estimateSourceBidLockNotional(source) {
+    const quoteQuantity = quoteQuantityOf(source);
+    if (typeof quoteQuantity === 'string') {
+        const remainingQuote = new BigNumber(quoteQuantity).minus(finiteDecimal(source.cum_quote_quantity ?? source.cumQuoteQuantity) ?? 0);
+        if (!remainingQuote.isFinite())
+            return null;
+        return BigNumber.maximum(0, remainingQuote);
+    }
+    const quantity = finiteDecimal(source.quantity);
+    if (quantity === undefined)
+        return null;
+    const remainingQuantity = BigNumber.maximum(0, quantity.minus(finiteDecimal(source.cum_quantity ?? source.cumQuantity) ?? 0));
+    return estimateBidNotional({
+        side: 'bid',
+        type: orderTypeOf(source),
+        price: typeof source.price === 'string' ? source.price : undefined,
+        quantity: remainingQuantity,
+    });
+}
+/**
+ * Incremental buy notional a replace would add beyond the source order's
+ * current remaining estimated lock. Asks are 0. Returns `null` when
+ * side/exposure can't be determined from the open-order snapshot.
+ */
+function estimateReplacementSpendDelta(source, replacement) {
+    if (source == null)
+        return null;
+    const side = sideOf(source);
+    if (side == null)
+        return null;
+    if (side === 'ask')
+        return new BigNumber(0);
+    const oldNotional = estimateSourceBidLockNotional(source);
+    if (oldNotional === null)
+        return null;
+    const newNotional = estimateBidNotional({
+        side: 'bid',
+        type: 'Limit',
+        price: replacement.price,
+        quantity: replacement.quantity,
+    });
+    if (newNotional === null)
+        return null;
+    return BigNumber.maximum(0, newNotional.minus(oldNotional));
+}
+async function loadOpenOrdersForSpendCap(ctx, marketId) {
+    const response = await ctx.client.request({
+        method: 'GET',
+        path: '/api/v1/orders',
+        query: { marketId, limit: 500 },
+    });
+    return Array.isArray(response.orders) ? response.orders : [];
+}
 export const orderTools = [
     defineTool({
         name: 'list_orders',
@@ -211,7 +399,7 @@ export const orderTools = [
             if ((args.type === 'StopLoss' || args.type === 'TakeProfit') && args.triggerPrice === undefined) {
                 throw new Error(`triggerPrice is required for ${args.type} orders.`);
             }
-            let reserved = 0;
+            let reserved = new BigNumber(0);
             if (ctx.spendCap.effectiveCap() !== null) {
                 const notional = estimateBidNotional(args);
                 if (notional === null) {
@@ -222,16 +410,32 @@ export const orderTools = [
                 reserved = notional;
             }
             try {
+                const body = {
+                    marketId: args.marketId,
+                    outcome: args.outcome,
+                    side: args.side,
+                    type: args.type,
+                };
+                if (args.price !== undefined)
+                    body.price = args.price;
+                if (args.triggerPrice !== undefined)
+                    body.triggerPrice = args.triggerPrice;
+                if (args.quantity !== undefined)
+                    body.quantity = args.quantity;
+                if (args.quoteQuantity !== undefined)
+                    body.quoteQuantity = args.quoteQuantity;
+                if (args.clientOrderId !== undefined)
+                    body.clientOrderId = args.clientOrderId;
                 return await ctx.client.request({
                     method: 'POST',
                     path: '/api/v1/orders',
-                    body: args,
+                    body,
                 });
             }
             catch (err) {
                 // Definitive server-side rejection (4xx) — nothing was spent, so give
                 // the reservation back. Ambiguous outcomes keep it.
-                if (reserved > 0 && err instanceof UnhedgedApiError && err.status >= 400 && err.status < 500) {
+                if (reserved.gt(0) && err instanceof UnhedgedApiError && err.status >= 400 && err.status < 500) {
                     ctx.spendCap.release(reserved);
                 }
                 throw err;
@@ -243,14 +447,324 @@ export const orderTools = [
         title: 'Cancel one or more open orders',
         description: CANCEL_DESCRIPTION,
         inputSchema: cancelSchema,
-        // Destructive: an empty orderIds array cancels EVERY open order on the market.
-        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        // Destructive: both target lists empty cancels EVERY open order on the market.
+        // Not durable-idempotent for client aliases: after an order closes the same string
+        // can name a later open order.
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
         handler: async (args, ctx) => {
+            const body = {
+                marketId: args.marketId,
+                orderIds: args.orderIds,
+            };
+            if (args.clientOrderIds !== undefined) {
+                body.clientOrderIds = args.clientOrderIds;
+            }
             return ctx.client.request({
                 method: 'DELETE',
                 path: '/api/v1/orders',
-                body: args,
+                body,
             });
         },
     }),
+    defineTool({
+        name: 'batch_place_orders',
+        title: 'Batch-place order-book orders',
+        description: `
+Place 1–32 orders on one CLOB market in a single request (\`POST /api/v1/orders/batch\`).
+
+Required: **marketId**, **orders** (array of legs). Each leg matches \`place_order\` fields except marketId. **Market legs are not allowed**; use \`place_order\` for Market. Legs may fill. Self-trade follows the market setting.
+
+The engine transaction commits even if a leg fails. HTTP **400** with \`{ results }\` when any leg failed (insufficient balance, invalid leg); HTTP **201** when every leg succeeded. Invalid legs are rejected by HTTP before the engine runs.
+
+If a **session spend cap** is configured, estimated bid notional across all legs is reserved before the request (same rules as \`place_order\`). Ask legs do not count. HTTP 400 with results releases only failed legs; successful legs keep their reservation. A definitive HTTP 4xx without results releases the whole reservation.
+
+Requires scope: \`order:place\`. Counts as one write against rate limits.
+`.trim(),
+        inputSchema: {
+            marketId: z.string().min(1),
+            orders: z
+                .array(z.object({
+                outcome: placeSchema.outcome,
+                side: placeSchema.side,
+                type: z.enum(['Limit', 'StopLoss', 'TakeProfit']),
+                price: placeSchema.price,
+                triggerPrice: placeSchema.triggerPrice,
+                quantity: placeSchema.quantity,
+                quoteQuantity: placeSchema.quoteQuantity,
+                clientOrderId: placeSchema.clientOrderId,
+            }))
+                .min(1)
+                .max(32),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        handler: async (args, ctx) => {
+            for (const [i, leg] of args.orders.entries()) {
+                if ((leg.quantity === undefined) === (leg.quoteQuantity === undefined)) {
+                    throw new Error(`orders[${i}]: provide exactly one of quantity or quoteQuantity.`);
+                }
+                if (leg.type === 'Limit' && leg.price === undefined) {
+                    throw new Error(`orders[${i}]: price is required for Limit legs.`);
+                }
+                if ((leg.type === 'StopLoss' || leg.type === 'TakeProfit') &&
+                    leg.triggerPrice === undefined) {
+                    throw new Error(`orders[${i}]: triggerPrice is required for ${leg.type} legs.`);
+                }
+            }
+            // Parallel to args.orders: per-leg estimated bid notional (0 for asks).
+            // Used to release only failed legs after a committed partial batch.
+            let legNotionals = null;
+            let reserved = new BigNumber(0);
+            if (ctx.spendCap.effectiveCap() !== null) {
+                legNotionals = [];
+                for (const [i, leg] of args.orders.entries()) {
+                    const notional = estimateBidNotional(leg);
+                    if (notional === null) {
+                        throw new SpendCapExceededError(`Refusing batch_place_orders: a session spend cap is configured but orders[${i}] notional can't be estimated client-side ` +
+                            `(${leg.type} ${leg.side} without quoteQuantity). Set quoteQuantity, or use a Limit leg with price+quantity.`, ctx.spendCap.totalSpent(), ctx.spendCap.effectiveCap());
+                    }
+                    legNotionals.push(notional);
+                }
+                const total = legNotionals.reduce((sum, n) => sum.plus(n), new BigNumber(0));
+                if (total.gt(0)) {
+                    ctx.spendCap.reserve(total, 'batch_place_orders');
+                    reserved = total;
+                }
+            }
+            try {
+                const response = await ctx.client.request({
+                    method: 'POST',
+                    path: '/api/v1/orders/batch',
+                    body: {
+                        marketId: args.marketId,
+                        orders: args.orders,
+                    },
+                });
+                // Also support older API versions that return partial results with HTTP 201.
+                if (legNotionals !== null && Array.isArray(response.results)) {
+                    let toRelease = new BigNumber(0);
+                    const n = Math.min(legNotionals.length, response.results.length);
+                    for (let i = 0; i < n; i++) {
+                        if (!batchPlaceLegConsumedSpend(response.results[i])) {
+                            toRelease = toRelease.plus(legNotionals[i]);
+                        }
+                    }
+                    if (toRelease.gt(0))
+                        ctx.spendCap.release(toRelease);
+                }
+                return response;
+            }
+            catch (err) {
+                if (reserved.gt(0) && err instanceof UnhedgedApiError && err.status >= 400 && err.status < 500) {
+                    const results = resultsFromApiError(err);
+                    if (legNotionals !== null && results) {
+                        let toRelease = new BigNumber(0);
+                        const n = Math.min(legNotionals.length, results.length);
+                        for (let i = 0; i < n; i++) {
+                            if (!batchPlaceLegConsumedSpend(results[i])) {
+                                toRelease = toRelease.plus(legNotionals[i]);
+                            }
+                        }
+                        if (toRelease.gt(0))
+                            ctx.spendCap.release(toRelease);
+                    }
+                    else {
+                        ctx.spendCap.release(reserved);
+                    }
+                }
+                throw err;
+            }
+        },
+    }),
+    defineTool({
+        name: 'replace_order',
+        title: 'Replace an open Limit order',
+        description: `
+Atomically cancel one open Limit order and place a replacement (\`POST /api/v1/orders/replace\`).
+
+Required: **marketId**, **price**, **quantity**, and exactly one of **orderId** / **clientOrderId**.
+Optional: **replacementClientOrderId**.
+
+If a **session spend cap** is configured, the tool loads the source open order first. Ask replacements do not count. Bid replacements reserve only the **incremental** estimated notional (\`max(0, new − remaining old)\`), where the old lock uses remaining size after \`cum_quantity\` / \`cum_quote_quantity\`. If the source side or exposure cannot be determined (missing from \`list_orders\`, unknown side, or unsized), the call is refused before submit. A definitive HTTP 4xx releases the reservation. On success, the reservation is also released for \`unchanged\` and zero-fill \`InternalCancel\` outcomes (nothing incremental was locked).
+
+Requires scopes: \`order:place\` and \`order:cancel\` (plus \`order:read\` when a spend cap is set, to resolve the source).
+`.trim(),
+        inputSchema: {
+            marketId: z.string().min(1),
+            orderId: z.string().regex(/^[0-9]+$/).optional(),
+            clientOrderId: clientOrderIdSchema.optional(),
+            replacementClientOrderId: clientOrderIdSchema.optional(),
+            price: probabilityStringSchema,
+            quantity: positiveDecimalStringSchema,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        handler: async (args, ctx) => {
+            const hasOrderId = args.orderId != null;
+            const hasClientOrderId = args.clientOrderId != null;
+            if (hasOrderId === hasClientOrderId) {
+                throw new Error('Specify exactly one of orderId or clientOrderId.');
+            }
+            let reserved = new BigNumber(0);
+            if (ctx.spendCap.effectiveCap() !== null) {
+                const openOrders = await loadOpenOrdersForSpendCap(ctx, args.marketId);
+                const source = findOpenOrder(openOrders, {
+                    orderId: args.orderId,
+                    clientOrderId: args.clientOrderId,
+                });
+                const delta = estimateReplacementSpendDelta(source, {
+                    price: args.price,
+                    quantity: args.quantity,
+                });
+                if (delta === null) {
+                    const target = args.orderId != null ? `orderId=${args.orderId}` : `clientOrderId=${args.clientOrderId}`;
+                    throw new SpendCapExceededError(`Refusing replace_order: a session spend cap is configured but the source side/exposure for ${target} ` +
+                        `can't be determined from open orders on this market. Ensure the order is still open and the API key ` +
+                        `has order:read, then retry.`, ctx.spendCap.totalSpent(), ctx.spendCap.effectiveCap());
+                }
+                if (delta.gt(0)) {
+                    ctx.spendCap.reserve(delta, 'replace_order');
+                    reserved = delta;
+                }
+            }
+            const body = {
+                marketId: args.marketId,
+                price: args.price,
+                quantity: args.quantity,
+            };
+            if (args.orderId !== undefined)
+                body.orderId = args.orderId;
+            if (args.clientOrderId !== undefined)
+                body.clientOrderId = args.clientOrderId;
+            if (args.replacementClientOrderId !== undefined) {
+                body.replacementClientOrderId = args.replacementClientOrderId;
+            }
+            try {
+                const response = await ctx.client.request({
+                    method: 'POST',
+                    path: '/api/v1/orders/replace',
+                    body,
+                });
+                // Same no-spend outcomes as a batch-replace leg (`unchanged`, zero-fill IC).
+                if (reserved.gt(0) && !batchReplaceLegConsumedSpend(response.result)) {
+                    ctx.spendCap.release(reserved);
+                }
+                return response;
+            }
+            catch (err) {
+                if (reserved.gt(0) && err instanceof UnhedgedApiError && err.status >= 400 && err.status < 500) {
+                    ctx.spendCap.release(reserved);
+                }
+                throw err;
+            }
+        },
+    }),
+    defineTool({
+        name: 'batch_replace_orders',
+        title: 'Batch-replace open Limit orders',
+        description: `
+Replace 1–32 open Limit orders on one market (\`POST /api/v1/orders/replace/batch\`).
+
+The engine transaction commits even if a leg fails. A replacement may fill. Self-trade follows the market setting: disabled, it will not trade against the user's own orders. HTTP **400** with \`{ results }\` when any leg failed.
+
+If a **session spend cap** is configured, open orders on the market are loaded first. Each bid leg reserves incremental estimated notional (\`max(0, new − remaining old)\`, using remaining size after fills); asks are 0. Bids spanning different outcomes reserve full new notional because another replacement may fill a source before its leg executes. Any leg whose source side/exposure cannot be determined refuses the whole batch before submit. HTTP 400 with results releases failed or unchanged legs; successful replacements keep their reservation. A definitive HTTP 4xx without results releases the whole reservation.
+
+Requires scopes: \`order:place\` and \`order:cancel\` (plus \`order:read\` when a spend cap is set). One write rate-limit unit per call.
+`.trim(),
+        inputSchema: {
+            marketId: z.string().min(1),
+            replaces: z
+                .array(z.object({
+                orderId: z.string().regex(/^[0-9]+$/).optional(),
+                clientOrderId: clientOrderIdSchema.optional(),
+                replacementClientOrderId: clientOrderIdSchema.optional(),
+                price: probabilityStringSchema,
+                quantity: positiveDecimalStringSchema,
+            }))
+                .min(1)
+                .max(32),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        handler: async (args, ctx) => {
+            for (const [i, leg] of args.replaces.entries()) {
+                const hasOrderId = leg.orderId != null;
+                const hasClientOrderId = leg.clientOrderId != null;
+                if (hasOrderId === hasClientOrderId) {
+                    throw new Error(`replaces[${i}]: specify exactly one of orderId or clientOrderId.`);
+                }
+            }
+            let legDeltas = null;
+            let reserved = new BigNumber(0);
+            if (ctx.spendCap.effectiveCap() !== null) {
+                const openOrders = await loadOpenOrdersForSpendCap(ctx, args.marketId);
+                const sources = args.replaces.map((leg) => findOpenOrder(openOrders, leg));
+                legDeltas = [];
+                for (const [i, leg] of args.replaces.entries()) {
+                    const source = sources[i];
+                    let delta = estimateReplacementSpendDelta(source, {
+                        price: leg.price,
+                        quantity: leg.quantity,
+                    });
+                    if (delta === null) {
+                        const target = leg.orderId != null ? `orderId=${leg.orderId}` : `clientOrderId=${leg.clientOrderId}`;
+                        throw new SpendCapExceededError(`Refusing batch_replace_orders: a session spend cap is configured but replaces[${i}] source side/exposure ` +
+                            `for ${target} can't be determined from open orders on this market. Ensure the order is still open and ` +
+                            `the API key has order:read, then retry.`, ctx.spendCap.totalSpent(), ctx.spendCap.effectiveCap());
+                    }
+                    // Cross-outcome bid matches can spend a source's lock before its leg
+                    // executes. Do not credit that speculative lock toward the new order.
+                    if (source && sideOf(source) === 'bid' && sources.some((other, j) => j !== i && other && sideOf(other) === 'bid' &&
+                        (typeof source.outcome !== 'string' || typeof other.outcome !== 'string' ||
+                            source.outcome !== other.outcome))) {
+                        delta = new BigNumber(leg.price).times(leg.quantity);
+                    }
+                    legDeltas.push(delta);
+                }
+                const total = legDeltas.reduce((sum, n) => sum.plus(n), new BigNumber(0));
+                if (total.gt(0)) {
+                    ctx.spendCap.reserve(total, 'batch_replace_orders');
+                    reserved = total;
+                }
+            }
+            try {
+                const response = await ctx.client.request({
+                    method: 'POST',
+                    path: '/api/v1/orders/replace/batch',
+                    body: {
+                        marketId: args.marketId,
+                        replaces: args.replaces,
+                    },
+                });
+                if (legDeltas !== null && Array.isArray(response.results)) {
+                    let toRelease = new BigNumber(0);
+                    const n = Math.min(legDeltas.length, response.results.length);
+                    for (let i = 0; i < n; i++) {
+                        if (!batchReplaceLegConsumedSpend(response.results[i])) {
+                            toRelease = toRelease.plus(legDeltas[i]);
+                        }
+                    }
+                    if (toRelease.gt(0))
+                        ctx.spendCap.release(toRelease);
+                }
+                return response;
+            }
+            catch (err) {
+                if (reserved.gt(0) && err instanceof UnhedgedApiError && err.status >= 400 && err.status < 500) {
+                    const results = resultsFromApiError(err);
+                    if (legDeltas !== null && results) {
+                        let toRelease = new BigNumber(0);
+                        const n = Math.min(legDeltas.length, results.length);
+                        for (let i = 0; i < n; i++) {
+                            if (!batchReplaceLegConsumedSpend(results[i]))
+                                toRelease = toRelease.plus(legDeltas[i]);
+                        }
+                        if (toRelease.gt(0))
+                            ctx.spendCap.release(toRelease);
+                    }
+                    else {
+                        ctx.spendCap.release(reserved);
+                    }
+                }
+                throw err;
+            }
+        },
+    }),
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unhedged/mcp",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Model Context Protocol server for Unhedged. Connect Claude, Codex, Cursor, and other MCP clients to markets, balances, trading, and withdrawals through a scoped API key.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,6 +29,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "bignumber.js": "9.3.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/skills/market-maker-workflow.md

@@ -37,7 +37,7 @@ The user is quoting both sides of market **{{market_id}}**, outcome **{{outcome}
    - `price: fair_value - spread` (clamp to (0, 1) and round to 2 decimals)
    - `quoteQuantity: {{size_per_side}}` — must be a string with exactly two decimals, e.g. `"5.00"`
 
-5. **Place an ask** with `place_order`:
+5. **Place an ask** with `place_order` (or combine steps 4–5 into one **`batch_place_orders`** call with both bid and ask legs — legs may fill, including each other when self-trade is enabled; one write rate-limit unit):
    - `side: "ask"`
    - `type: "Limit"`
    - `price: fair_value + spread` (same clamp + rounding)
@@ -47,12 +47,22 @@ The user is quoting both sides of market **{{market_id}}**, outcome **{{outcome}
 
 ## Refresh loop
 
-If the user asks to "refresh" or "re-quote", repeat steps 2-6. Each tool invocation receives a fresh idempotency key. If a placement fails ambiguously, check the account's transaction history before trying again: a filled order will be absent from open orders. Stop and ask the user if the outcome remains uncertain.
+If the user asks to "refresh" or "re-quote":
+
+- Prefer **`batch_replace_orders`** when both sides already have open Limit orders with known `orderId` / `clientOrderId` values: one call can move bid and ask together (replacements may fill; self-trade follows the market setting). The transaction commits even if a leg fails; HTTP 400 when any leg failed.
+- Otherwise repeat steps 2–6 (`cancel_order` then place). Each tool invocation receives a fresh idempotency key. If a placement fails ambiguously, check the account's transaction history before trying again: a filled order will be absent from open orders. Stop and ask the user if the outcome remains uncertain.
 
 ## Guardrails
 
 - This is single-outcome, single-pair quoting. If the user wants to quote multiple outcomes simultaneously, run this skill once per outcome.
-- The session spend cap counts the bid side notional but not the ask side. Make sure the cap (`UNHEDGED_MAX_SPEND_PER_SESSION`) is generous enough for the planned cycle of re-quotes.
+- The session spend cap counts bid-side place notional and **incremental** bid
+  notional on replace against the source's **remaining** lock (asks are free).
+  Same-size re-quotes of an unfilled order do not consume more of the cap;
+  size/price increases and replaces that rebuild after partial fills do.
+  Soft no-spend outcomes (`{ err }`, unchanged replace, zero-fill
+  `InternalCancel`) release their reservation so later quotes can reuse it.
+  Make sure `UNHEDGED_MAX_SPEND_PER_SESSION` covers the planned cycle of bid
+  upsizes.
 - Do **not** widen the spread silently to chase a fill. Tell the user what spread you're using and what the bid/ask resolve to.
 - A 403 with "missing required scope: `order:place`" means the API key wasn't minted with that scope. Tell the user to mint a new key with `order:place` and `order:cancel`.
 - **Cancel-on-disconnect (bots):** if an admin enabled `cancelOnDisconnect` on the account, long-running agents should call `POST /api/v1/orders/session/connect` at startup (UUID `sessionId`), `POST .../session/heartbeat` every ~30s, and `POST .../session/disconnect` on shutdown. API-key auth with `order:cancel` is required because the session lifecycle can cancel open CLOB orders when the last session ends.