@unhedged/mcp 0.1.2

package/dist/tools/orders.js

@@ -0,0 +1,256 @@
+import { z } from 'zod';
+import { defineTool, READ_ONLY } from './types.js';
+import { UnhedgedApiError } from '../client/errors.js';
+import { SpendCapExceededError } from '../safety/spend-cap.js';
+const LIST_DESCRIPTION = `
+List the user's open **order-book orders**. (Parimutuel bets show up under \`list_bets\` instead.)
+
+Filters:
+- **marketId** (optional): restrict to one market. Omit it to enumerate open orders account-wide.
+- **outcome** (optional): filter by outcome label, e.g. \`"YES"\`, \`"$95k - $100k"\`. Requires \`marketId\`.
+- **limit**: 1-500, default 100.
+- **cursor**: opaque pagination cursor from the preceding response.
+- **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.
+
+Only works on CLOB markets — parimutuel markets won't have any orders to return.
+
+Requires scope: \`order:read\`.
+
+### Examples
+All open orders on a market:
+\`\`\`json
+{ "marketId": "clxabc123..." }
+\`\`\`
+
+All open orders across the account:
+\`\`\`json
+{ "limit": 500, "includeTotal": true, "includeMarketDetails": true }
+\`\`\`
+
+Only the user's bids on the YES outcome:
+\`\`\`json
+{ "marketId": "clxabc123...", "outcome": "YES" }
+\`\`\`
+`.trim();
+const PLACE_DESCRIPTION = `
+Place an **order on a CLOB market**. Use this for limit/market/stop orders on order-book markets only — parimutuel markets use \`place_bet\`.
+
+Required parameters:
+- **marketId**: which market.
+- **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.
+
+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.
+
+The MCP server automatically adds an \`Idempotency-Key\`.
+
+Requires scope: \`order:place\`.
+
+### Safety
+- If a **session spend cap** is configured, \`bid\` orders contribute to the cap (estimated notional = \`quoteQuantity\` if given, else \`price × quantity\` for limit orders). Ask orders are not counted (they reduce exposure).
+- For \`bid\` \`Market\` orders **without** \`quoteQuantity\`, the notional can't be estimated client-side. Either set \`quoteQuantity\` or use a limit order so the spend cap can supervise.
+
+### Example
+Buy 5 contracts of YES at probability 0.55:
+\`\`\`json
+{
+  "marketId": "clxabc123...",
+  "outcome": "YES",
+  "side": "bid",
+  "type": "Limit",
+  "price": "0.55",
+  "quantity": 5
+}
+\`\`\`
+
+Sell $3.00 of NO at market:
+\`\`\`json
+{
+  "marketId": "clxabc123...",
+  "outcome": "NO",
+  "side": "ask",
+  "type": "Market",
+  "quoteQuantity": "3.00"
+}
+\`\`\`
+`.trim();
+const CANCEL_DESCRIPTION = `
+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.**
+
+Returns \`{ result }\` with engine-side per-order outcomes.
+
+The market must still be ACTIVE and before the trading cutoff (\`scheduledResolutionTime\` or \`endTime\`); cancelling on a closed market is rejected.
+
+The MCP server adds an \`Idempotency-Key\` automatically.
+
+Requires scope: \`order:cancel\`.
+
+### Examples
+Cancel two specific orders:
+\`\`\`json
+{ "marketId": "clxabc123...", "orderIds": ["1042", "1051"] }
+\`\`\`
+
+Cancel **all** open orders on this market:
+\`\`\`json
+{ "marketId": "clxabc123...", "orderIds": [] }
+\`\`\`
+`.trim();
+const listSchema = {
+    marketId: z.string().min(1).optional().describe('Optional market ID. Omit for account-wide open orders.'),
+    outcome: z.string().optional().describe('Outcome label filter. Requires marketId.'),
+    limit: z.number().int().min(1).max(500).optional(),
+    cursor: z.string().min(1).optional().describe('Opaque nextCursor from the preceding page.'),
+    includeTotal: z.boolean().optional(),
+    includeMarketDetails: z.boolean().optional(),
+};
+const probabilityStringSchema = z
+    .string()
+    .regex(/^(?:0|[1-9]\d*)\.\d{2}$/)
+    .refine((value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 && n < 1;
+});
+const positiveDecimalStringSchema = z
+    .string()
+    .regex(/^(?:0|[1-9]\d*)\.\d{2}$/)
+    .refine((value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0;
+});
+const placeSchema = {
+    marketId: z.string().min(1),
+    outcome: z.string().min(1).describe('Outcome label, e.g. "YES" or "$95k - $100k".'),
+    side: z.enum(['bid', 'ask']),
+    type: z.enum(['Limit', 'Market', 'StopLoss', 'TakeProfit']),
+    price: probabilityStringSchema
+        .optional()
+        .describe('Probability price decimal string between 0 and 1 with exactly 2 decimals. Required for Limit orders.'),
+    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()
+        .optional()
+        .describe('Number of contracts as a positive integer.'),
+    quoteQuantity: positiveDecimalStringSchema
+        .optional()
+        .describe('USD notional string with exactly 2 decimals. Use INSTEAD of quantity.'),
+};
+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.'),
+};
+/**
+ * Best-effort client-side notional estimate for the spend cap.
+ * Returns `null` when we can't estimate (e.g. unsized market bid).
+ */
+function estimateBidNotional(args) {
+    if (args.side !== 'bid')
+        return 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 null;
+        return price * args.quantity;
+    }
+    return null;
+}
+export const orderTools = [
+    defineTool({
+        name: 'list_orders',
+        title: 'List open orders',
+        description: LIST_DESCRIPTION,
+        inputSchema: listSchema,
+        annotations: READ_ONLY,
+        handler: async (args, ctx) => {
+            if (args.outcome !== undefined && args.marketId === undefined) {
+                throw new Error('marketId is required when filtering orders by outcome.');
+            }
+            return ctx.client.request({
+                method: 'GET',
+                path: '/api/v1/orders',
+                query: args,
+            });
+        },
+    }),
+    defineTool({
+        name: 'place_order',
+        title: 'Place an order-book order',
+        description: PLACE_DESCRIPTION,
+        inputSchema: placeSchema,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        handler: async (args, ctx) => {
+            // Cross-field rules the per-field zod schema can't express. Enforced
+            // before submitting the order.
+            if ((args.quantity === undefined) === (args.quoteQuantity === undefined)) {
+                throw new Error('Provide exactly one of quantity or quoteQuantity.');
+            }
+            if (args.type === 'Limit' && args.price === undefined) {
+                throw new Error('price is required for Limit orders.');
+            }
+            if ((args.type === 'StopLoss' || args.type === 'TakeProfit') && args.triggerPrice === undefined) {
+                throw new Error(`triggerPrice is required for ${args.type} orders.`);
+            }
+            let reserved = 0;
+            if (ctx.spendCap.effectiveCap() !== null) {
+                const notional = estimateBidNotional(args);
+                if (notional === null) {
+                    throw new SpendCapExceededError(`Refusing place_order: a session spend cap is configured but the notional for this order can't be estimated client-side ` +
+                        `(${args.type} ${args.side} without quoteQuantity). Set quoteQuantity, or use a Limit order with an explicit price+quantity, so the cap can supervise.`, ctx.spendCap.totalSpent(), ctx.spendCap.effectiveCap());
+                }
+                ctx.spendCap.reserve(notional, 'place_order');
+                reserved = notional;
+            }
+            try {
+                return await ctx.client.request({
+                    method: 'POST',
+                    path: '/api/v1/orders',
+                    body: args,
+                });
+            }
+            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) {
+                    ctx.spendCap.release(reserved);
+                }
+                throw err;
+            }
+        },
+    }),
+    defineTool({
+        name: 'cancel_order',
+        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 },
+        handler: async (args, ctx) => {
+            return ctx.client.request({
+                method: 'DELETE',
+                path: '/api/v1/orders',
+                body: args,
+            });
+        },
+    }),
+];

package/dist/tools/portfolio.d.ts

@@ -0,0 +1,2 @@
+import { type AnyToolDefinition } from './types.js';
+export declare const portfolioTools: AnyToolDefinition[];

package/dist/tools/portfolio.js

@@ -0,0 +1,34 @@
+import { defineTool, READ_ONLY } from './types.js';
+const DESCRIPTION = `
+Read a summary of the user's portfolio: total bets, win rate, ROI, active-position exposure, pending order-book exposure, and recent payouts.
+
+Returns a \`portfolio\` object with:
+- \`summary\`: aggregate metrics — \`totalBets\`, \`totalWagered\`, \`totalWins\`, \`totalLosses\`, \`pendingBets\`, \`pendingOrderBookPositions\`, \`pendingOrderBookCostBasis\`, \`totalPayouts\`, \`totalProfit\`, \`winRate\` and \`roi\`. The last two are already percentage points (e.g. \`40\` means 40%); do not multiply them by 100.
+- \`positions\`: a preview of up to 50 active/ended positions across markets, one entry per outcome held. This array is not a complete inventory when \`positionsTotal\` is greater than its length.
+- \`positionsTotal\`: the complete active/ended position-row count available from the paginated REST endpoint \`/api/v1/portfolio/me/positions\`.
+- \`recentPayouts\`: the 10 most recent settled payouts.
+
+This MCP tool intentionally returns the bounded preview only; it has no position-pagination input. Use the paginated REST \`/api/v1/portfolio/me/positions\` and \`/api/v1/portfolio/me/history\` endpoints through an authorized API client when a complete inventory or historical result is required.
+
+Cached at the API for ~30s so calling this repeatedly is cheap.
+
+Requires scope: \`portfolio:read\`.
+
+### When to use
+For periodic "how am I doing?" check-ins. As the first step in the \`portfolio-review\` workflow. Before recommending a \`cash-out\` to highlight the user's biggest exposures.
+`.trim();
+export const portfolioTools = [
+    defineTool({
+        name: 'get_portfolio',
+        title: 'Get portfolio summary',
+        description: DESCRIPTION,
+        inputSchema: {},
+        annotations: READ_ONLY,
+        handler: async (_args, ctx) => {
+            return ctx.client.request({
+                method: 'GET',
+                path: '/api/v1/portfolio/me',
+            });
+        },
+    }),
+];

package/dist/tools/types.d.ts

@@ -0,0 +1,44 @@
+import type { z, ZodRawShape } from 'zod';
+import type { UnhedgedHttpClient } from '../client/http.js';
+import type { UnhedgedMcpConfig } from '../config.js';
+import type { SpendCapTracker } from '../safety/spend-cap.js';
+export interface ToolContext {
+    client: UnhedgedHttpClient;
+    config: UnhedgedMcpConfig;
+    spendCap: SpendCapTracker;
+}
+/**
+ * MCP behavior hints (spec `ToolAnnotations`). Clients use these to gate
+ * approval flows — e.g. auto-approving read-only tools while requiring
+ * explicit confirmation for destructive ones.
+ */
+export interface ToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+export interface ToolDefinition<Shape extends ZodRawShape = ZodRawShape> {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Shape;
+    annotations: ToolAnnotations;
+    handler: (args: z.infer<z.ZodObject<Shape>>, ctx: ToolContext) => Promise<unknown>;
+}
+export type AnyToolDefinition = {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: ZodRawShape;
+    annotations: ToolAnnotations;
+    handler: (args: unknown, ctx: ToolContext) => Promise<unknown>;
+};
+/** All Unhedged tools talk to a single closed API, never an open world. */
+export declare const READ_ONLY: ToolAnnotations;
+/**
+ * Define a tool with a narrow input schema while exposing it under the loose
+ * `AnyToolDefinition` shape used by the registry. The handler is type-safe
+ * because the cast happens once at registration time, not at each call site.
+ */
+export declare function defineTool<Shape extends ZodRawShape>(def: ToolDefinition<Shape>): AnyToolDefinition;

package/dist/tools/types.js

@@ -0,0 +1,10 @@
+/** All Unhedged tools talk to a single closed API, never an open world. */
+export const READ_ONLY = { readOnlyHint: true, openWorldHint: false };
+/**
+ * Define a tool with a narrow input schema while exposing it under the loose
+ * `AnyToolDefinition` shape used by the registry. The handler is type-safe
+ * because the cast happens once at registration time, not at each call site.
+ */
+export function defineTool(def) {
+    return def;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@unhedged/mcp",
+  "version": "0.1.2",
+  "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",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "unhedged-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prepublishOnly": "node scripts/prepublish-check.mjs && npm run build",
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "check": "tsc --noEmit",
+    "test": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "lint": "eslint src tests"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.62.1",
+    "eslint": "^10.8.1",
+    "tsx": "^4.23.12",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "unhedged",
+    "prediction-markets",
+    "ai-agent",
+    "claude",
+    "codex"
+  ],
+  "license": "MIT",
+  "homepage": "https://unhedged.gg/mcp"
+}

package/skills/cash-out.md

@@ -0,0 +1,51 @@
+---
+name: cash-out
+description: Close open orders, optionally sell open positions at market, and prepare for withdrawal.
+arguments:
+  - name: withdraw_to_wallet
+    description: If "true", actually request a withdrawal after closing. If "false" or omitted, stop after closing and let the user decide.
+    required: false
+  - name: destination_party_id
+    description: Canton party ID for the withdrawal (web2 users only). Ignored if withdraw_to_wallet is not "true".
+    required: false
+---
+
+# Cash-out workflow
+
+The user wants to wind down activity on Unhedged. Your job:
+1. Cancel every open order across every market.
+2. Optionally sell open CLOB positions at market.
+3. Optionally request a withdrawal.
+
+Each step requires explicit confirmation before proceeding to the next, unless the user has clearly said "do it all".
+
+## Steps
+
+1. **Discover positions and every open order**.
+   - Call `get_portfolio` and note:
+     - `summary.pendingOrderBookPositions` — open CLOB positions.
+     - `summary.pendingBets` — open parimutuel bets (these can't be cashed out early; they wait for resolution).
+     - `positionsTotal` and `positions.length` — the portfolio tool returns only a preview of up to 50 active/ended rows, so do not treat that array as a complete CLOB inventory.
+   - Independently call `list_orders` without `marketId`, using `limit: 500` and `includeTotal: true`. Follow `nextCursor` until it is null. Do not infer the order inventory solely from portfolio positions: a completely unfilled resting bid can lock funds without creating a share position.
+
+2. **Cancel every resting order**. Group the account-wide order inventory by `marketId`. For each market, call `cancel_order` with `orderIds: []` (cancel-all on that market). Report back which markets were touched and how many orders were cancelled.
+
+3. **Sell CLOB positions** (only if the user said to). Obtain the complete CLOB position inventory first; `get_portfolio.positions` is only a preview and the current MCP toolset has no position-pagination input. Use an authorized REST client to page `/api/v1/portfolio/me/positions?marketType=ORDER_BOOK&limit=500&offset=...`, or stop and ask the user if that inventory is unavailable. For each open CLOB position, call `place_order` with:
+   - `side: "ask"`
+   - `type: "Market"`
+   - `quantity` set to the position's contract count.
+   Confirm with the user **before** issuing market sells — fills can be poor.
+
+4. **Wait for orders to clear**. Call `get_balance` and verify `lockedEngine` has dropped close to zero. If it has not, list orders account-wide again and cancel any remaining markets before rechecking. Don't withdraw while engine funds are still locked — the request will fail or be undersized.
+
+5. **Withdraw** if `withdraw_to_wallet` is `"true"`:
+   - Call `get_balance` to get current `available` and `withdrawalMinAmount`.
+   - Call `request_withdrawal` with `amount: available - withdrawalFee` and `destinationPartyId: {{destination_party_id}}` if supplied. Use the full available balance unless the user specified otherwise.
+   - Report the withdrawal ID and the queued status; settlement is asynchronous on-chain.
+
+6. **Confirm**. Summarize: orders cancelled, positions sold (if any), balance change, withdrawal queued (if any).
+
+## Guardrails
+
+- **Parimutuel bets cannot be unwound** before market resolution. Don't try to "cancel" them — there's no API for it. Tell the user they're locked until the market resolves.
+- If the API key lacks `balance:withdraw`, step 5 will return a 403. That's a *good* default — encourage the user to mint a new key with that scope only when they're ready.

package/skills/market-creator-assistant.md

@@ -0,0 +1,45 @@
+---
+name: market-creator-assistant
+description: Draft a new prediction market with appropriate outcomes, resolution rules, and metadata, then guide the user through submission.
+arguments:
+  - name: idea
+    description: The user's idea for the market, in plain English (e.g. "will ETH ETF launch before July?").
+    required: true
+---
+
+# Market creator workflow
+
+> ⚠️ **Requirements:** This skill requires the `MARKET_CREATOR` role on the user's Unhedged account. The Role enum in the platform's database is `USER | MARKET_CREATOR | MARKET_MAKER | WHALEPLAY | SUPER_ADMIN`; if the user is just a `USER`, market creation endpoints return 403. Direct them to <contact@unhedged.gg> to request the role.
+
+The user wants to create a market for: **{{idea}}**.
+
+Note: this MCP package does **not** ship dedicated market-creation tools in v1 — those endpoints sit under `/api/v1/creator/*` and require additional metadata (image uploads, category tagging) that don't fit a single tool call. This skill walks the user through preparing the spec so they can submit it via the web UI at <https://unhedged.gg/creators/manage/create>.
+
+## Steps
+
+1. **Refine the question**. Reframe the user's idea as a single yes/no or multi-outcome question that has an objectively verifiable answer. Bad: "Will ETH do well in 2026?" Good: "Will the spot ETH price on Coinbase be above $5,000 USD at 00:00 UTC on 2026-12-31?"
+
+2. **Define outcomes**. For a binary market, that's YES and NO. For a range market, propose 3-5 buckets covering the realistic range plus an "Other / above" bucket. Show the user the outcome list and let them adjust.
+
+3. **Pick a resolution source**. For crypto prices, the standard is exchange 1-minute kline (candle) data via the platform's `exchange-kline` resolver. For sports, StatPal feeds. Esports resolve via GRID feeds, and there are dedicated resolvers for F1, golf, cricket, horse racing, and macro data (CPI, Fed rate, unemployment). For political / event markets, manual resolution by a moderator is the default. Recommend one and explain how the auto-resolver will read it.
+
+4. **Set the timeline**. `scheduledResolutionTime` is when the question is settled. `endTime` is when trading closes (often the same instant for time-based crypto questions; earlier for sports where the game outcome is known some minutes before resolution can complete).
+
+5. **Recommend a category and tags** drawn from the existing taxonomy: `crypto`, `sports`, `esports`, `politics`, `entertainment`, `tech`. Tags should be searchable terms users would type (e.g. "BTC", "ETH", "ETF", "NBA-finals").
+
+6. **Compose the spec** and present it to the user, ready to paste into <https://unhedged.gg/creators/manage/create>:
+   ```
+   Question: ...
+   Outcomes: ...
+   Resolution source: ... (specifics)
+   Resolution time: ... UTC
+   End time: ... UTC
+   Category: ...
+   Tags: [..., ...]
+   ```
+
+## Guardrails
+
+- Don't promise the market will be approved — depending on platform policy, MARKET_CREATOR submissions may still go through a moderation queue.
+- For oracle-resolved markets, the price source has to match a data feed the platform supports. Don't invent feed identifiers; if you're unsure, recommend the user check the docs at <https://unhedged.gg/docs>.
+- Refuse to draft markets that obviously violate platform terms (markets on individuals' deaths, markets that would constitute insider trading on private events, etc.).

package/skills/market-maker-workflow.md

@@ -0,0 +1,58 @@
+---
+name: market-maker-workflow
+description: Quote both sides of an Unhedged CLOB order book around a chosen fair value, refreshing as the market moves.
+arguments:
+  - name: market_id
+    description: The CLOB market to make on. Parimutuel markets are not supported by this skill.
+    required: true
+  - name: outcome
+    description: The outcome label to quote (e.g. "YES" or "$95k - $100k").
+    required: true
+  - name: fair_value
+    description: The user's estimated fair probability for the outcome (between 0 and 1).
+    required: true
+  - name: spread
+    description: Half-spread in probability points. e.g. 0.02 = ±2%. Default 0.02.
+    required: false
+  - name: size_per_side
+    description: Notional USD per side, formatted as a string with exactly two decimals (e.g. "5.00"). Default "5.00".
+    required: false
+---
+
+# Market-maker workflow
+
+The user is quoting both sides of market **{{market_id}}**, outcome **{{outcome}}**, around fair value **{{fair_value}}** with a half-spread of {{spread}} and {{size_per_side}} USD per side.
+
+## Steps
+
+1. **Read the market-maker profile first**. Call `get_market_maker_profile` (no arguments). Confirm `approvalStatus` is `APPROVED`, and read `currentTier`, `effectiveMakerFee`/`effectiveTakerFee`, and `rebateRate` — use these to sanity-check that the chosen spread keeps quotes profitable after fees, and widen the half-spread toward the maker fee if the requested spread is too tight. Also note `orderRateLimit` so the refresh loop stays within it. If `approvalStatus` is not `APPROVED` (or the call 403s), stop and tell the user the account isn't an active market maker.
+
+2. **Snapshot the book**. Call `list_orders` with `marketId: "{{market_id}}"` and `outcome: "{{outcome}}"`. Note the user's current open orders on this outcome — you'll need to refresh them, not duplicate them.
+
+3. **Cancel stale quotes** with `cancel_order`. Pass the IDs of the user's existing orders on this outcome. If there are none, skip this step.
+
+4. **Place a bid** with `place_order`:
+   - `side: "bid"`
+   - `type: "Limit"`
+   - `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`:
+   - `side: "ask"`
+   - `type: "Limit"`
+   - `price: fair_value + spread` (same clamp + rounding)
+   - `quoteQuantity: {{size_per_side}}` — same two-decimal string format
+
+6. **Confirm** by listing orders again and reporting back the two new orders with their IDs, prices, and sizes.
+
+## 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.
+
+## 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.
+- 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.

package/skills/market-research.md

@@ -0,0 +1,42 @@
+---
+name: market-research
+description: Find Unhedged prediction markets matching a topic and summarize their odds, volume, and resolution rules.
+arguments:
+  - name: topic
+    description: The topic or keyword to research (e.g. "BTC price 2026", "NBA finals", "US election").
+    required: true
+  - name: max_results
+    description: Maximum number of markets to summarize. Default 10.
+    required: false
+---
+
+# Market research workflow
+
+You are helping the user understand the prediction-market landscape on Unhedged around the topic: **{{topic}}**.
+
+## Steps
+
+1. **Search** with `search_markets` using `search: "{{topic}}"` and `limit` set to `max_results` (default 10). By default this returns ACTIVE and ENDED markets. Use `status: "ACTIVE"` for markets open to trading, or explicitly request `status: "RESOLVED"` for historical context.
+
+2. For the top markets returned, call `get_market` to pull the full outcome list and resolution rules. Pay attention to:
+   - The market `question` (this is what determines winning, not your interpretation).
+   - The `outcomes` array, with their indexes and labels.
+   - `autoResolutionConfig` if present — this tells you how the market resolves automatically (Pyth oracle, sports API, manual, etc).
+   - `scheduledResolutionTime` or `endTime` — when the market closes.
+
+3. For the most interesting candidates, call `get_market_stats` to retrieve current implied probabilities per outcome plus volume.
+
+4. **Summarize back to the user** in this shape:
+
+   For each market, present:
+   - The question, one line.
+   - Status + resolution time (relative, e.g. "resolves in 3 days").
+   - The outcomes with current implied probability (%) and notional pool size.
+   - One sentence on how it resolves (manual / oracle / sport feed / etc).
+   - One sentence on whether the odds look interesting, biased, or noisy — keep this honest, not promotional.
+
+## Guardrails
+
+- Don't fabricate market IDs or outcome labels. If a market doesn't appear in the search results, say so.
+- Don't recommend bets. This skill is **information-only**. If the user wants to actually place a position, escalate to the `place-hedged-position` skill.
+- The market category may not exactly match the topic (e.g. "BTC" sits under `crypto`, "NBA" under `sports`). Use `search` rather than guessing categories.

package/skills/place-hedged-position.md

@@ -0,0 +1,51 @@
+---
+name: place-hedged-position
+description: Calculate and place a hedged position across multiple outcomes of an Unhedged market.
+arguments:
+  - name: market_id
+    description: The market to take a position on. The user can find this via the market-research skill.
+    required: true
+  - name: total_budget
+    description: Total USD to commit across the position. Must fit the available platform balance.
+    required: true
+  - name: thesis
+    description: One-line description of the user's thesis (e.g. "BTC closes above 100k by Sunday"). Used only in confirmation prose.
+    required: false
+---
+
+# Hedged position workflow
+
+The user wants to place a position on market **{{market_id}}** with a budget of **{{total_budget}} USD**. Their thesis: {{thesis}}.
+
+A "hedged" position here means allocating across multiple outcomes — typically a primary bet on the thesis plus a smaller bet on the opposite outcome to cap downside. Your job is to size it sensibly and execute.
+
+## Steps
+
+1. **Pull the market**. Call `get_market` with `id: "{{market_id}}"` and `get_market_stats` for the current implied probabilities. Read out:
+   - The outcome labels and their indexes.
+   - Current implied probability per outcome (from stats).
+   - Whether the market is parimutuel (no order book, just pool sizes) or CLOB (has limit orders). The presence of `outcomeStats[].matchingEngineId` is a strong signal it's CLOB.
+
+2. **Check the user's balance**. Call `get_balance`. Confirm `available >= {{total_budget}}`. If not, say so and stop — do not place any partial position without checking with the user.
+
+3. **Compute the split**. A simple default:
+   - 70% on the thesis-aligned outcome.
+   - 20% on the most likely "hedge" outcome (usually the negation of the thesis).
+   - 10% reserved (do not place; just leave in available balance).
+   Adjust based on the implied probabilities: if the thesis-aligned outcome already trades at >75%, the hedge becomes less useful — propose dialling the hedge down to 10% and reserving 20%. If it trades below 50%, the hedge becomes more useful — propose 60/30/10.
+   Always show the user the proposed split **before** placing anything.
+
+4. **Place the bets**.
+   - For **parimutuel markets**: call `place_bet` once per outcome you're allocating to.
+   - For **CLOB markets**: call `place_order` with `type: "Limit"` and a price close to the current implied probability. Don't use `Market` orders for hedged positions — limit orders give the user a known cost basis.
+   The MCP server adds an `Idempotency-Key` automatically but does not retry ambiguous failures. If a call times out, check `list_bets` or `list_orders` to see whether it landed, then ask the user before retrying.
+
+5. **Confirm**. After both legs are placed (or attempted), call `get_balance` again and report:
+   - The new available balance.
+   - The two positions just opened, with their outcome labels and amounts.
+   - The total at risk and the maximum payout under each resolution.
+
+## Guardrails
+
+- **Never** place a bet larger than the user explicitly authorized. If your split math suggests a leg larger than `total_budget`, stop and ask.
+- If a tool returns a `SpendCapExceededError`, do not retry. The cap exists for a reason. Tell the user, summarize what's been placed so far, and stop.