Commit Cashout

curl -X POST https://api.totalis.trade/v1/cashout-requests/c3d4e5f6-7890-abcd-ef12-34567890abcd/commit \
  -H "X-API-Key: $TOTALIS_API_KEY"   -H "Content-Type: application/json"   -d '{"min_price_micro": 1990000}'

{
  "data": {
    "cashout_request_id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
    "status": "committed",
    "chain_sig": "5Nx7...buybackSig"
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Cashout is being processed; please check back",
    "details": { "reason": "COMMIT_UNREACHABLE", "indeterminate": true }
  }
}

POST

cashout-requests

{id}

commit

curl -X POST https://api.totalis.trade/v1/cashout-requests/c3d4e5f6-7890-abcd-ef12-34567890abcd/commit \
  -H "X-API-Key: $TOTALIS_API_KEY"   -H "Content-Type: application/json"   -d '{"min_price_micro": 1990000}'

{
  "data": {
    "cashout_request_id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
    "status": "committed",
    "chain_sig": "5Nx7...buybackSig"
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Cashout is being processed; please check back",
    "details": { "reason": "COMMIT_UNREACHABLE", "indeterminate": true }
  }
}

Accept the winning bid on the user’s early cashout auction and drive it on-chain. The bid is the price — there is no MM-confirm round-trip. You must echo back the price the user accepted (see the request body); the exit is only ever filled at or above it. Signatures are obtained server-side via Privy at execution. On success you receive min_price_micro (or better) either way, but the position ends up in one of two states, decided server-side by who won: if the winning bid came from the position’s own counterparty the position closes — your stake is released and the RFQ flips to bought_back. If it came from any other market maker the position transfers to them and stays open under new ownership; you are out of it, and the RFQ does not become bought_back. This endpoint is idempotent per (request, user): a committed result is cached for 5 minutes and replayed with 200 OK. The replay returns the original outcome verbatim — a retry that sends a different min_price_micro still gets the first commit’s result, and the new floor is not re-evaluated. Retry with the same value you first sent.

Indeterminate commits never double-spend. If the on-chain outcome is unknown (timeout or transient RPC failure), the request stays committing and returns 503 with details.indeterminate: true. Branch on that boolean, not on details.reason — the reason is a coarse execution-layer code and is not a stable taxonomy. A reconciler resolves it against on-chain state — do not treat a 503 as a failure or assume nothing happened. Reopen the stream and wait for the terminal status. A determinate failure (409) means nothing landed. Most are retryable against a live book, but already_transferred is terminal for the position — stop, and re-read the position rather than reopening an auction.

Authentication

API key required. Pass your API key in the X-API-Key header.

X-API-Key: <your-api-key>

A Privy JWT (Authorization: Bearer <jwt>) is also accepted — see Authentication.

Path parameters

string

required

The cashout request ID (UUID).

Request body

integer

required

The price the user accepted on screen, in micro-USDC — echo back the price_micro from the best_quote frame you displayed. Required: a commit that does not state the accepted price is a 400, because nothing is ever filled at a price the user did not see.The fill uses the best live bid at commit time, floored at this value: a better bid fills at the better price, and a book that has moved below it fails with 409 price_below_accepted (the response carries best_price_micro) leaving the auction open to re-tap.

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

Response

Returns 201 Created on a fresh commit, or 200 OK when replaying a cached idempotent result.

object

Show data

string

The cashout request UUID.

string

"committed"

string

The on-chain transaction signature — a buy_back_position signature when the position closed, a transfer_position one when it transferred.

Errors

Status	Code	Description
400	`VALIDATION_ERROR`	Missing or invalid `min_price_micro` (must be an integer >= 1), or an unknown field.
401	`UNAUTHORIZED`	Missing or invalid API key.
403	`FORBIDDEN`	You do not own this cashout request (`details.reason: not_owner`).
404	`NOT_FOUND`	Cashout request not found.
409	`CONFLICT`	See `details.reason`: `price_below_accepted` (the best live bid is below `min_price_micro`; carries `best_price_micro`), `quote_expired` (no live bid left), `not_active`, `locked` (a commit for this auction is already in flight), `missing_wallet`, `amount_over_bound` (the winning counterparty bid failed the collateral re-check at commit), `already_transferred` (terminal — the position has already moved), or a buyer-side rejection when the winner is acquiring it (`insufficient_buyer_balance`, `buyer_no_vault`, `buyer_is_seller`, `buyer_is_counterparty`).
410	`GONE`	The auction expired before commit. Open a fresh one.
429	`RATE_LIMITED`	Too many requests. Honour `Retry-After`.
503	`SERVICE_UNAVAILABLE`	Branch on `details.indeterminate`, never on the message. `true` — the exit may have landed. `details.reason` is the execution-layer code, typically `COMMIT_UNREACHABLE` (the lane was not reached), `BAD_RESPONSE` (it answered unusably), or the lane’s own error code; treat them identically. Do not retry: reopen the stream and wait for the terminal `status`. `false` — only `fee_unavailable`, meaning the profit-fee rate could not be read. Nothing landed, the auction is still open, and an immediate retry is safe.

curl -X POST https://api.totalis.trade/v1/cashout-requests/c3d4e5f6-7890-abcd-ef12-34567890abcd/commit \
  -H "X-API-Key: $TOTALIS_API_KEY"   -H "Content-Type: application/json"   -d '{"min_price_micro": 1990000}'

{
  "data": {
    "cashout_request_id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
    "status": "committed",
    "chain_sig": "5Nx7...buybackSig"
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Cashout is being processed; please check back",
    "details": { "reason": "COMMIT_UNREACHABLE", "indeterminate": true }
  }
}

⌘I

Overview

Quote service

Market maker

Markets

Parlays

Account

API keys

Funds & vault

Webhooks

Authentication

Path parameters

Request body

Response

Errors

​Authentication

​Path parameters

​Request body

​Response

​Errors

Authentication

Path parameters

Request body

Response

Errors