preview_order

Computes the summary the user is meant to confirm before taking a position, and — when the order is currently possible — mints the confirm_token place_order needs. Scope: write · Annotations: readOnlyHint REST equivalent: POST /open/v1/topics/{id}/order-preview

This tool charges nothing and does not reserve anything. It counts against the read window only, so an agent can freely price a few options before asking.

Parameters

Name	Type	Required	Default	Notes
`topic_id`	string (uuid)	✅	—	`v21_lmsr` topics only
`option_id`	string (uuid)	✅	—	From the topic’s `options`
`language`	see languages		`en`

Returns

Every v21_lmsr order is a fixed 100 coins. payout_if_correct_rubies is what the option pays if it turns out correct — that many rubies, with the 100-coin stake not returned. price_after is where the option’s price lands once this order joins the book. avg_price is coins paid per ruby (stake / units). It always sits above price_now and below price_after, since the order moves the price up as it fills. It carries 6 decimal places — the one field that departs from the 4-decimal convention, because it is a ratio rather than a price. Captured live:

{
  "can_place": true,
  "summary": {
    "topic_title": "Will the Fed cut rates at the November 2026 meeting?",
    "option_label": "Yes",
    "stake_coins": "100.0000",
    "balance_before": "5000.0000",
    "balance_after": "4900.0000",
    "price_now": "0.5000",
    "price_after": "0.5244",
    "payout_if_correct_rubies": "195.2372",
    "avg_price": "0.512197",
    "close_time": "2026-10-06T23:34:02.46058Z",
    "mechanism": "v21_lmsr"
  },
  "confirm_token": "oc1.eyJhIjoicGxhY2Vfb3JkZXIi…YP6hrtHyqIdsOX_s",
  "expires_at": "2026-09-08T23:39:11.993467Z"
}

Show the summary to the user and get their explicit confirmation before calling the execute tool. The token is what proves a preview happened — it is not a substitute for asking.

When the order can’t be placed

can_place is false, reason says why, and no token is issued:

`reason`	Meaning
`TOPIC_CLOSED`	Past `close_time`, or a ruling has started
`ALREADY_STAKED`	The owner already holds a position — one order per topic, no adding or switching
`INSUFFICIENT_BALANCE`	Fewer than 100 coins
`MECHANISM_UNSUPPORTED`	A legacy `v2_share` topic; this surface only trades `v21_lmsr`

The summary is still returned so the agent can explain the situation with real numbers:

{
  "can_place": false,
  "reason": "ALREADY_STAKED",
  "summary": {
    "topic_title": "Will the Fed cut rates at the November 2026 meeting?",
    "option_label": "Yes",
    "stake_coins": "100.0000",
    "balance_before": "4899.0000",
    "balance_after": "4899.0000",
    "price_now": "0.4988",
    "price_after": "0.5233",
    "payout_if_correct_rubies": "195.6806",
    "avg_price": "0.511037",
    "close_time": "2026-10-06T23:34:02.46058Z",
    "mechanism": "v21_lmsr"
  }
}

With MECHANISM_UNSUPPORTED the summary is partial — only topic_title, option_label, stake_coins, the balances, price_now, close_time and mechanism are meaningful.

Example prompts

“What would it cost me to back Yes on the Fed market?”
“If I’m right on this one, what do I get?”

place_order · get_topic · list_my_positions

Getting Started

MCP Server

Platform

Parameters

Returns

When the order can’t be placed

Example prompts

​Parameters

​Returns

​When the order can’t be placed

​Example prompts

​Related

Parameters

Returns

When the order can’t be placed

Example prompts

Related