Bid on a Cashout Auction

curl -X PUT https://api.totalis.trade/v1/mm/cashout-requests/$CASHOUT_REQUEST_ID/quote \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price_micro": 1990000, "expires_in_ms": 15000}'

const res = await fetch(
  `https://api.totalis.trade/v1/mm/cashout-requests/${cashoutRequestId}/quote`,
  {
    method: 'PUT',
    headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
    // price_micro is what the USER receives, all-in, in micro-USDC
    body: JSON.stringify({ price_micro: 1_990_000, expires_in_ms: 15_000 }),
  },
);

import requests

requests.put(
    f'https://api.totalis.trade/v1/mm/cashout-requests/{cashout_request_id}/quote',
    headers={'X-API-Key': API_KEY},
    # price_micro is what the USER receives, all-in, in micro-USDC
    json={'price_micro': 1_990_000, 'expires_in_ms': 15_000},
)

{
  "data": {
    "quote": {
      "id": "<string>",
      "cashout_request_id": "<string>",
      "market_maker_id": "<string>",
      "price_micro": 123,
      "valid_until": "<string>",
      "status": "<string>"
    },
    "book_seq": 123,
    "replaced": true
  }
}

PUT

cashout-requests

{id}

quote

curl -X PUT https://api.totalis.trade/v1/mm/cashout-requests/$CASHOUT_REQUEST_ID/quote \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price_micro": 1990000, "expires_in_ms": 15000}'

const res = await fetch(
  `https://api.totalis.trade/v1/mm/cashout-requests/${cashoutRequestId}/quote`,
  {
    method: 'PUT',
    headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
    // price_micro is what the USER receives, all-in, in micro-USDC
    body: JSON.stringify({ price_micro: 1_990_000, expires_in_ms: 15_000 }),
  },
);

import requests

requests.put(
    f'https://api.totalis.trade/v1/mm/cashout-requests/{cashout_request_id}/quote',
    headers={'X-API-Key': API_KEY},
    # price_micro is what the USER receives, all-in, in micro-USDC
    json={'price_micro': 1_990_000, 'expires_in_ms': 15_000},
)

{
  "data": {
    "quote": {
      "id": "<string>",
      "cashout_request_id": "<string>",
      "market_maker_id": "<string>",
      "price_micro": 123,
      "valid_until": "<string>",
      "status": "<string>"
    },
    "book_seq": 123,
    "replaced": true
  }
}

Submit or replace your bid on an early cashout auction. Auctions arrive on the MM stream you already subscribe to as a cashout_request event, and are broadcast to every market maker — including positions you do not back. Bid one all-in price_micro: the micro-USDC the user receives. There is no direction field and no fee term. The highest live bid wins and ties go to the earliest bid. To pass, submit nothing — there is no decline endpoint. Re-submitting replaces your own bid atomically, but it also re-times it: your replacement is a new submission, so re-sending the same price puts you behind any bid that has since matched it. Do not re-PUT an unchanged price just to refresh the TTL — you would hand away a tie you were winning. The auction lives about 10 seconds. A win closes the position if you back it (a closing exit carries the profit fee on your side) or acquires it if you do not (no fee applies). For the payload and auction mechanics, see Early cashout.

Authentication

API key required, with the mm:quote scope. Pass it in the X-API-Key header.

X-API-Key: <key>

Path parameters

string

required

The cashout request ID (UUID) — cashout_request_id on the push.

Request body

integer

required

The all-in amount the user receives, in micro-USDC (1_000_000 = $1.00). Integer, minimum 1. May be below the user’s stake — a losing parlay exits for less than it cost.Two ceilings apply, and both compare against micro-USDC. user_stake and total_payout arrive as decimal USDC on the push, so scale them by 1e6 first.Every bid must satisfy price_micro <= round(total_payout * 1e6) (price_above_max_payout). If you are the position’s current counterparty, a tighter fee-aware ceiling binds (price_above_buyback_bound), derived from total_payout - user_stake rather than from the mm_risk field — the two drift by up to 0.0001 USDC, so use the subtraction:

S = round(user_stake * 1e6)
M = round((total_payout - user_stake) * 1e6)
price_micro <= S + M - floor(M * fee_bps / 10_000)

integer

default:"15000"

How long your bid stays live, in milliseconds. Range 5000-60000. A bid may outlive the auction; one that lapses mid-auction stops being the best bid. Nothing tells you when it lapses, so age bids out locally.

The body is strict — an unknown field is a 400.

Withdrawing a bid

DELETE /v1/mm/cashout-requests/{id}/quote pulls your live bid. It is idempotent: 204 No Content when a bid was removed, 200 OK with {"status": "already_withdrawn"} when yours had already lapsed (not an error), 409 once the auction is no longer active, 404 if the auction is unknown. There is no partial withdraw — re-PUT to change a price.

Response

Returns 201 Created for your first bid on an auction, or 200 OK when replacing your own.

object

Show data

object

The submitted bid.

Show quote

string

Bid UUID.

string

The auction this bid is for.

string

Your market maker ID.

integer

The all-in micro-USDC you bid.

string

ISO 8601 timestamp when this bid expires.

string

"active"

integer

The auction’s new book sequence number.

boolean

true if this replaced your previous bid.

Errors

Status	`details.reason`	Description
400	validation	Non-integer or non-positive `price_micro`, `expires_in_ms` out of range, unknown field, or malformed JSON.
400	`price_above_max_payout`	Bid exceeds the position’s `total_payout`. Response carries `max_price_micro`.
400	`price_above_buyback_bound`	You back this position and the bid exceeds what your locked collateral covers after the profit fee. Skipped when the fee rate is briefly unavailable; the commit then re-checks it and rejects with `amount_over_bound`.
401	`UNAUTHORIZED`	Missing or invalid API key.
429	`RATE_LIMITED`	Too many requests. Honour `Retry-After`.
403	`insufficient_scope`	Key lacks `mm:quote`. Response carries `required_scope`.
404	—	Auction unknown, or already evicted at its TTL. The ordinary “too slow” outcome, not a fault.
409	`self_quote`	You opened this auction (you are the seller). Bidding on a position you back is allowed and is the closing case.
409	`not_active`	The auction was committed or cancelled before your bid landed.
409	`expired`	The auction expired as your bid landed.
409	`MARKET_NEAR_CLOSE`	The underlying market is too close to close to exit.
409	`buyback_wallet_missing`	You back this position but no wallet is on record, so a closing exit cannot be built. Only your own bids fail; other market makers can still win the same auction by acquiring the position.

Winning is not the same as being paid. The user is only ever filled at a price they explicitly accepted, so a fill can fail if the book moves down between their tap and their commit. And if you win by acquiring a position, your funding and eligibility are checked at that commit rather than when you bid — an underfunded or ineligible winning bid fails there with insufficient_buyer_balance, buyer_no_vault or buyer_is_counterparty.

curl -X PUT https://api.totalis.trade/v1/mm/cashout-requests/$CASHOUT_REQUEST_ID/quote \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price_micro": 1990000, "expires_in_ms": 15000}'

const res = await fetch(
  `https://api.totalis.trade/v1/mm/cashout-requests/${cashoutRequestId}/quote`,
  {
    method: 'PUT',
    headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
    // price_micro is what the USER receives, all-in, in micro-USDC
    body: JSON.stringify({ price_micro: 1_990_000, expires_in_ms: 15_000 }),
  },
);

import requests

requests.put(
    f'https://api.totalis.trade/v1/mm/cashout-requests/{cashout_request_id}/quote',
    headers={'X-API-Key': API_KEY},
    # price_micro is what the USER receives, all-in, in micro-USDC
    json={'price_micro': 1_990_000, 'expires_in_ms': 15_000},
)

⌘I

Overview

Quote service

Market maker

Markets

Parlays

Account

API keys

Funds & vault

Webhooks

Bid on a Cashout Auction

Authentication

Path parameters

Request body

Withdrawing a bid

Response

Errors

​Authentication

​Path parameters

​Request body

​Withdrawing a bid

​Response

​Errors

Authentication

Path parameters

Request body

Withdrawing a bid

Response

Errors