Create Cashout Request

curl -X POST https://api.totalis.trade/v1/cashout-requests \
  -H "X-API-Key: $TOTALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "position_id": "9f86d08818844f86d08818844f86d088" }'

{
  "data": {
    "cashout_request": {
      "id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
      "user_id": "did:privy:cm3abc...",
      "counterparty_mm_id": "mm-uuid-1234",
      "position_id": "9f86d08818844f86d08818844f86d088",
      "position_pda": "7Xc3...PDA",
      "db_position_id": "3f1c9e88-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
      "user_wallet": "5Hs9...UserWallet",
      "mm_wallet": "47NS...MmWallet",
      "user_stake": 24.75,
      "mm_risk": 75.25,
      "mm_collateral_locked": 75.25,
      "total_payout": 100,
      "taker_fee_locked": 0.25,
      "version": 1,
      "book_seq": 0,
      "status": "active",
      "created_at": "2026-06-01T18:45:30.000Z",
      "updated_at": "2026-06-01T18:45:30.000Z",
      "expires_at": "2026-06-01T18:46:00.000Z",
      "position_expires_at": "2026-06-02T00:00:00.000Z",
      "legs": [
        { "id": "8ccf2c5d-3a61-4707-93f2-b6f0a0f0c0c6", "market_ticker": "KXBTC-26JUN01-T72500", "event_ticker": "KXBTC-26JUN01", "side": "yes", "venue": "kalshi" },
        { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "market_ticker": "KXBTC-26JUN01-T73000", "event_ticker": "KXBTC-26JUN01", "side": "no", "venue": "kalshi" }
      ]
    }
  }
}

POST

cashout-requests

curl -X POST https://api.totalis.trade/v1/cashout-requests \
  -H "X-API-Key: $TOTALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "position_id": "9f86d08818844f86d08818844f86d088" }'

{
  "data": {
    "cashout_request": {
      "id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
      "user_id": "did:privy:cm3abc...",
      "counterparty_mm_id": "mm-uuid-1234",
      "position_id": "9f86d08818844f86d08818844f86d088",
      "position_pda": "7Xc3...PDA",
      "db_position_id": "3f1c9e88-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
      "user_wallet": "5Hs9...UserWallet",
      "mm_wallet": "47NS...MmWallet",
      "user_stake": 24.75,
      "mm_risk": 75.25,
      "mm_collateral_locked": 75.25,
      "total_payout": 100,
      "taker_fee_locked": 0.25,
      "version": 1,
      "book_seq": 0,
      "status": "active",
      "created_at": "2026-06-01T18:45:30.000Z",
      "updated_at": "2026-06-01T18:45:30.000Z",
      "expires_at": "2026-06-01T18:46:00.000Z",
      "position_expires_at": "2026-06-02T00:00:00.000Z",
      "legs": [
        { "id": "8ccf2c5d-3a61-4707-93f2-b6f0a0f0c0c6", "market_ticker": "KXBTC-26JUN01-T72500", "event_ticker": "KXBTC-26JUN01", "side": "yes", "venue": "kalshi" },
        { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "market_ticker": "KXBTC-26JUN01-T73000", "event_ticker": "KXBTC-26JUN01", "side": "no", "venue": "kalshi" }
      ]
    }
  }
}

Open an early cashout auction on an active on-chain position instead of waiting for settlement. The auction is broadcast to every market maker, and each may bid one all-in price. The stream surfaces the highest live bid; ties go to the earliest. Accepting it via Commit drives the exit on-chain at that price or better. The request is keyed on the position’s on-chain position_id — a 16-byte hex string (the 0x prefix is optional). The position must be active (executed), owned by you, have a counterparty MM assigned, and not be within the near-expiry buffer of its market end.

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.

Request body

string

required

The position’s on-chain id — a 16-byte hex string (32 hex chars), with or without a 0x prefix.

Response

object

Show data

object

The opened cashout request.

Show cashout_request

string

UUID of the cashout request. Use it on the stream, commit, and MM endpoints.

string

Your user ID.

string

The position’s original counterparty market maker. Informational only: the auction is broadcast to every market maker, and a winning bid from this one closes the position rather than transferring it.

string

The on-chain position id (hex), normalized without the 0x prefix.

string

On-chain position address, or null.

string

Internal UUID of the position record — distinct from the on-chain position_id hex.

string

Your wallet address on the position.

string

The counterparty market maker’s wallet address.

number

Your net stake on the position (USDC). Always refunded on a buyback.

number

The counterparty’s risk on the position (USDC): total_payout − user_stake.

number

Collateral the counterparty has locked on-chain against the position (USDC).

number

The position’s total payout (USDC).

number

The taker fee locked when the position was created (USDC).

integer

Request version, starts at 1.

integer

Quote book sequence number, starts at 0.

string

"active"

string

ISO 8601 time the cashout request was opened.

string

ISO 8601 time of the last update to the request.

string

ISO 8601 close time of the auction (~10 s), distinct from the position expiry. Open a fresh auction if it lapses before you commit.

string

The underlying position’s market-end horizon, or null.

array

The position’s legs (ticker, side, venue, and resolution where known).

Response codes

201 Created opens a new auction. 200 OK returns the auction that was already live for this position — opening is idempotent per (position, user), so a double-tap resumes the existing auction rather than splitting bidder attention across two. Check the status code, or expires_at, before assuming you have a fresh ~10 s window.

Errors

Status	Code	Description
400	`VALIDATION_ERROR`	Body is not valid JSON, or `position_id` is not a 16-byte hex string. See `details.issues`.
401	`UNAUTHORIZED`	Missing or invalid API key.
404	`NOT_FOUND`	Position not found, or not owned by you.
409	`CONFLICT`	Position is not active, too close to expiry, or has no counterparty MM wallet assigned yet.
503	`SERVICE_UNAVAILABLE`	Eligibility/economics read failed, or no counterparty MM is resolvable yet; retry.

curl -X POST https://api.totalis.trade/v1/cashout-requests \
  -H "X-API-Key: $TOTALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "position_id": "9f86d08818844f86d08818844f86d088" }'

{
  "data": {
    "cashout_request": {
      "id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
      "user_id": "did:privy:cm3abc...",
      "counterparty_mm_id": "mm-uuid-1234",
      "position_id": "9f86d08818844f86d08818844f86d088",
      "position_pda": "7Xc3...PDA",
      "db_position_id": "3f1c9e88-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
      "user_wallet": "5Hs9...UserWallet",
      "mm_wallet": "47NS...MmWallet",
      "user_stake": 24.75,
      "mm_risk": 75.25,
      "mm_collateral_locked": 75.25,
      "total_payout": 100,
      "taker_fee_locked": 0.25,
      "version": 1,
      "book_seq": 0,
      "status": "active",
      "created_at": "2026-06-01T18:45:30.000Z",
      "updated_at": "2026-06-01T18:45:30.000Z",
      "expires_at": "2026-06-01T18:46:00.000Z",
      "position_expires_at": "2026-06-02T00:00:00.000Z",
      "legs": [
        { "id": "8ccf2c5d-3a61-4707-93f2-b6f0a0f0c0c6", "market_ticker": "KXBTC-26JUN01-T72500", "event_ticker": "KXBTC-26JUN01", "side": "yes", "venue": "kalshi" },
        { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "market_ticker": "KXBTC-26JUN01-T73000", "event_ticker": "KXBTC-26JUN01", "side": "no", "venue": "kalshi" }
      ]
    }
  }
}

⌘I

Overview

Quote service

Market maker

Markets

Parlays

Account

API keys

Funds & vault

Webhooks

Create Cashout Request

Authentication

Request body

Response

Response codes

Errors

​Authentication

​Request body

​Response

​Response codes

​Errors

Authentication

Request body

Response

Response codes

Errors