Place a paper order
MCP tool: place_paper_order
A paper order places no real order and moves no money, and it needs no connected venue account. It is priced against the venue's live order book with the venue's own taker fee, so it fills where a real market order would.
Only what the book can fill right now is recorded. Nothing rests: whatever the book could not fill comes back as unfilledShares and is dropped.
A buy takes usdAmount. A sell takes contracts, and can only close paper you bought by hand; a bot's paper position belongs to the bot. There is no shorting.
The position settles by itself when the market resolves. Read it back from the portfolio endpoint with paper set to true.
Requires a key with the write scope.
Body parameters
marketRefstringrequiredHandle of the one outcome to trade, from the feed or market search.
sidestringrequired"yes" or "no".
actionstring"buy" (the default) or "sell".
usdAmountnumberDollars to spend. Required for a buy.
contractsnumberContracts to sell. Required for a sell.
clientRequestIdstringA UUID naming this order, so a retry does not fill twice.
Response
price is what each share cost with the fee included. A marketRef that names a market with several outcomes is refused; use the marketRef of one outcome.
curl -X POST https://api.rivo.markets/v1/paper-orders \
-H "Authorization: Bearer rivo_live_..." \
-H "Content-Type: application/json" \
-d '{
"marketRef": "a2Fsc2hpOm1hcmtldDpL...",
"side": "yes",
"usdAmount": 100
}'import requests
r = requests.post(
"https://api.rivo.markets/v1/paper-orders",
headers={"Authorization": "Bearer rivo_live_..."},
json={
"marketRef": "a2Fsc2hpOm1hcmtldDpL...",
"side": "yes",
"usdAmount": 100,
},
)
print(r.json()["data"])const res = await fetch("https://api.rivo.markets/v1/paper-orders", {
method: "POST",
headers: {
Authorization: "Bearer rivo_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({
marketRef: "a2Fsc2hpOm1hcmtldDpL...",
side: "yes",
usdAmount: 100,
}),
});
const { data } = await res.json();{
"success": true,
"data": {
"id": "0f6c2a51-6f0f-4a0e-9a53-2f1c7d0c3b11",
"platform": "kalshi",
"marketRef": "a2Fsc2hpOm1hcmtldDpL...",
"marketTitle": "Will the Fed cut in December?",
"outcome": "YES",
"action": "buy",
"shares": 176,
"price": 0.5673,
"totalUsd": 99.85,
"unfilledShares": 0,
"at": 1791255600000
}
}