Market-Maker Runbook

                 place / replace / cancel
   Market  ────────────────────────────────►  Monaco
   maker      MCP command plane (one-shot)     matching
    ▲                                           engine
    │        orders · orderbook · trades          │
    └──────────────────────────────────────────────┘
            Core SDK WebSocket state plane (live)

import { MonacoSDK, createMonacoWebSocket, resolveWsUrl } from "@0xmonaco/core";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { seiTestnet } from "viem/chains";

const NETWORK = "staging";
const account = privateKeyToAccount(process.env.MM_PRIVATE_KEY as `0x${string}`);
const walletClient = createWalletClient({ account, chain: seiTestnet, transport: http() });

const sdk = new MonacoSDK({
  walletClient,
  network: NETWORK,
  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com", // use a private provider in production
});

// Session-key auth: the wallet authorizes an ed25519 session keypair.
const authState = await sdk.login(process.env.MONACO_CLIENT_ID as string);

// Resolve the market you will quote (perps use MARGIN mode).
const pair = await sdk.market.getTradingPairBySymbol("BTC/USDC");
if (!pair) throw new Error("BTC/USDC not found"); // getTradingPairBySymbol returns undefined for an unknown symbol
const mode = "MARGIN"; // "SPOT" for spot markets

// Initial snapshot — equivalent MCP tools: get_orders, get_positions, get_balances.
// Resting orders are SUBMITTED or PARTIALLY_FILLED; an array matches any of them.
const openOrders = await sdk.trading.getPaginatedOrders({ status: ["SUBMITTED", "PARTIALLY_FILLED"] });
const positions = await sdk.positions.listPositions();
const balances = await sdk.profile.getUserBalances();

// Seed your local view keyed by id from the paginated snapshot. The state
// plane (step 2) keeps this view current after the initial seed — there is no
// separate live-cache set to merge in. On a later reconnect you merge a fresh
// snapshot into this map on `(id, version)` rather than replacing it (step 4),
// so the stream never has to pause.
const orderState = new Map(openOrders.orders.map((o) => [o.id, o]));

const session = {
  publicKey: authState.sessionPublicKey,
  privateKey: authState.sessionPrivateKey,
};

// When the socket dropped. Step 4's gap recovery pages the trade tape back
// only this far, so it has to be recorded where the drop is observed — by the
// time `onResync` fires, the reconnect has already happened.
let disconnectedAt = new Date();

const ws = createMonacoWebSocket(resolveWsUrl(NETWORK), {
  session,
  onStatusChange: (status) => {
    if (status !== "connected") disconnectedAt = new Date();
    console.log("ws status:", status);
  },
  onResync: async ({ code, slowClient }) => {
    await resync(code, slowClient, disconnectedAt); // defined in step 4
  },
});

await ws.connect();

// State plane: consume fills, cancels, and order-state changes here — do NOT
// poll get_orders to find out what filled.
//
// Apply events as they arrive, including across a reconnect: each one carries
// the `version` that step 4's snapshot merge compares against, so there is no
// window in which the stream has to be paused or buffered.
const unsubOrders = ws.orders(pair.id, mode, (event) => {
  // OrderPlaced / OrderMatched / OrderFilled / OrderPartiallyFilled /
  // OrderCancelled / OrderRejected / OrderExpired
  applyOrderEvent(event);
});

const unsubBook = ws.orderbook(pair.id, mode, 1, "BASE", (event) => {
  onBookMove(event.bestBid, event.bestAsk);
});

const unsubTrades = ws.trades(pair.id, (event) => {
  onTrade(event.data.price, event.data.quantity, event.data.makerSide);
});

const unsubBalances = ws.balances((event) => onBalance(event.data));
const unsubMovements = ws.movements((event) => onMovement(event.data));

// Live position state — size, mark price, unrealized PnL, liquidation price.
// Omit the pair to stream every pair, or pass pair.id to filter.
const unsubPositions = ws.positions((event) => onPosition(event.data));

// Liquidation alerts — your account crossed a maintenance threshold.
const unsubLiquidations = ws.liquidations((event) => onLiquidation(event.data));

// Place a resting quote — MCP: place_limit_order.
const bid = await sdk.trading.placeLimitOrder(pair.id, "BUY", "0.10", "60000", {
  tradingMode: mode,
  timeInForce: "GTC",
});

// Re-price an existing quote in place — MCP: replace_order.
await sdk.trading.replaceOrder(bid.orderId, { price: "60050" });

// Pull a quote — MCP: cancel_order.
await sdk.trading.cancelOrder(bid.orderId);

// Wallet-wide default — covers every subaccount and application on this
// wallet. No MCP tool for this; use the SDK or raw REST:
// GET/PUT /api/v1/accounts/self-trade-prevention.
await sdk.profile.setSelfTradePreventionDefault("SKIP");

// snapshot.version >= local.version  →  take the snapshot
// otherwise                          →  keep local

async function resync(code: number, slowClient: boolean, disconnectedAt: Date) {
  // slowClient === true means the server shed the connection with close code
  // 1013: its broadcast receiver missed events. This closes every subscription
  // on that socket, including positions and other absolute-state channels;
  // a dropped key or terminal update may never have a later replacement.
  console.warn(`resync after close ${code}${slowClient ? " (slow-client gap)" : ""}`);

  const [orders, positions, balances] = await Promise.all([
    sdk.trading.getPaginatedOrders({ status: ["SUBMITTED", "PARTIALLY_FILLED"] }),
    sdk.positions.listPositions(),
    sdk.profile.getUserBalances(),
  ]);

  // Merge, do not replace: events kept arriving while this was in flight, and
  // for those orders local state is the newer of the two.
  const snapshotIds = new Set<string>();
  for (const order of orders.orders) {
    snapshotIds.add(order.id);
    const local = orderState.get(order.id);
    if (takeSnapshot(order, local)) {
      orderState.set(order.id, order);
    }
  }

  // The resting snapshot cannot show what stopped resting during the gap —
  // see the next section for both halves of that. Both are required: the
  // snapshot frame and this merge do NOT close a reconnect gap on their own.
  const gapTrades = await recoverGapFills(disconnectedAt);
  // UserTrade carries tradeId, not orderId. Merge execution history by tradeId;
  // the missing-resting-order pass below repairs each terminal order itself.
  reconcileTrades(gapTrades);
  await recoverOrdersThatLeftTheBook(snapshotIds);

  reconcilePositions(positions);
  reconcileBalances(balances);
}

// Orders neither side can rank, collected for the fallback below.
const needsReplay = new Set<string>();

// Absent means unknown, not zero: treating it as zero would make a legacy row
// look older than everything. So rather than compare and guess, decide per
// side which one is rankable.
function takeSnapshot(snapshot: Order, local?: Order): boolean {
  // Nothing local, or local was seeded without a version (a pre-feature order,
  // or an event that carried none). A comparison against `undefined` can never
  // be true, so comparing here would freeze that order out of every future
  // resync — silently, and permanently. REST is the only rankable side: take it.
  if (!local || local.version === undefined) return true;
  // The snapshot has no version but local does: this one genuinely cannot be
  // ordered, and taking the older-looking side could revert newer stream
  // state. Hand it to the buffer-and-replay fallback instead of guessing.
  if (snapshot.version === undefined) {
    needsReplay.add(snapshot.id);
    return false;
  }
  return snapshot.version >= local.version;
}

// An order still eligible to rest on the book. Anything else has reached a
// terminal state and cannot come back, so absence from the snapshot says
// nothing about it.
function isResting(order: Order): boolean {
  return order.status === "SUBMITTED" || order.status === "PARTIALLY_FILLED";
}

// Every fill you missed, bounded by the gap rather than by history depth.
async function recoverGapFills(disconnectedAt: Date) {
const missed = [];
let cursor: string | undefined;
outer: while (true) {
  const page = await sdk.profile.getUserTrades({ pageToken: cursor, pageSize: 100 });
  for (const trade of page.trades) {
    if (new Date(trade.executedAt) < disconnectedAt) break outer;
    missed.push(trade);
  }
  if (!page.nextPageToken) break;
  cursor = page.nextPageToken;
}
return missed;
}

async function recoverOrdersThatLeftTheBook(snapshotIds: Set<string>) {
for (const [id, local] of orderState) {
  if (!isResting(local)) continue;
  if (snapshotIds.has(id)) continue;
  // Absence can mean termination or persistence lag. Compare against the
  // current local row AFTER awaiting: a newer event may arrive during the read.
  const order = await sdk.trading.getOrder(id);
  if (takeSnapshot(order, orderState.get(id))) {
    orderState.set(id, order);
  }
}
}

// Cancel every resting order — MCP: batch_cancel_all_orders.
// Pass a tradingPairId to scope it to one market, or omit for all markets.
await sdk.trading.batchCancelAll();

// Close every open position — MCP: batch_close_all_positions.
await sdk.positions.batchCloseAllPositions();

unsubOrders();
unsubBook();
unsubTrades();
unsubBalances();
unsubMovements();
unsubPositions();
unsubLiquidations();
ws.disconnect();
await sdk.logout(); // revokes the session key