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
Choosing the stake: ask, don’t guess
The stake is the user’s decision. Before calling this tool:- The user named an amount (“put 300 coins on Yes”) → pass exactly that as
amount_coins. Don’t round it or nudge it into range. - The user didn’t name an amount (“back Yes on this one”) → ask them how many coins to stake first. Never choose, infer or default an amount on their behalf.
stake_rules on
get_topic: min_coins..max_coins, inclusive, whole
coins. Each topic fixes its range when it is created — older topics accept
exactly 100, newer ones typically 1 to 10,000. Mention the range when you ask.
If amount_coins is omitted the order stakes stake_rules.default_coins
(100, moved into the topic’s range). That is a fallback for older
integrations, not a recommendation — an agent that follows the rule above
never relies on it.
The amount is bound into the confirm_token. To change it, preview again;
place_order takes no amount of its own and spends
exactly the previewed stake_coins.
Returns
stake_coins is what the order spends. payout_if_correct_rubies is what the
option pays if it turns out correct — that many rubies, with the stake
not returned. It already includes any live ruby boost: ruby_multiplier is
the boost on the topic right now ("1.0000" without one). So while a boost
runs, payout_if_correct_rubies is a multiple of the order’s unit count.
It is a guaranteed minimum, not the final amount: if the topic settles
while a ruby boost is live, the order pays at the higher multiplier. Present it
as “at least N rubies if correct”. See
Rubies and positions.
price_after is where the option’s price lands once this order joins the
book. avg_price is coins paid per unit (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.
Example — 300 coins on Yes during a 2× ruby boost:
When the order can’t be placed
can_place is false, reason says why, and no token is issued:
Precedence:
TOPIC_CLOSED and ALREADY_STAKED outrank STAKE_OUT_OF_RANGE,
which outranks INSUFFICIENT_BALANCE — changing the amount cannot fix a closed
topic or an existing order. When an out-of-range amount meets a closed topic
or an existing order, the reason is TOPIC_CLOSED / ALREADY_STAKED, there is
no details, and the summary has the out-of-range shape described below.
The summary is still returned so the agent can explain the situation with real
numbers:
STAKE_OUT_OF_RANGE, summary.stake_coins echoes the amount that was
asked for (unclamped), balance_after equals balance_before, price_now is
the current price, and the fields that need a quote — price_after,
payout_if_correct_rubies, ruby_multiplier, avg_price — are empty strings:
With
MECHANISM_UNSUPPORTED the summary is partial — only topic_title,
option_label, stake_coins, the balances, price_now, close_time and
mechanism are meaningful.Input errors
Anamount_coins that is not a positive whole number is an input error, not a
preview reason. Over REST it must be a JSON integer — a quoted string such
as "100", a fraction, zero or a negative number answers
400 INVALID_ARGUMENT with details.field = "amount_coins". Over MCP a
non-integer is rejected by the tool schema, and zero or a negative number fails
with amount_coins: must be a positive whole number of coins.
Example prompts
- “Put 300 coins on Yes on the Fed market.” →
amount_coins: 300 - “Back Yes on this one.” → ask how many coins first, then preview
- “If I’m right on this one, what do I get?”
Related
place_order ·
get_topic ·
list_my_positions ·
Rubies and positions