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": "did:privy:cm3mm...",
      "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": 74.25,
      "mm_collateral_locked": 74.25,
      "total_payout": 99,
      "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:45:40.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": "did:privy:cm3mm...",
      "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": 74.25,
      "mm_collateral_locked": 74.25,
      "total_payout": 99,
      "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:45:40.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 to exit an active on-chain position before settlement. Every market maker may bid one all-in price. The stream shows the highest live bid, and ties go to the earliest. Accept it with Commit cashout to exit on-chain at that price or better. You identify the position by its on-chain position_id. The position must:

be active (executed)
be owned by you
have a counterparty market maker assigned
not be within the near-expiry buffer of its market end (the cashout cutoff on Limits and fees)

Authentication

Send your API key in the X-API-Key header. The key needs the trading:write scope.

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: every market maker can bid, and a win by this one closes the position instead of transferring it.

string

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

string

On-chain position address (PDA), 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 backing maker locked for this position when it opened (USDC). Makers are margined across their whole book, so it can be less than mm_risk.

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. If it lapses before you commit, open a fresh auction.

string

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

array

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

Response codes

Status	Meaning
`201 Created`	A new auction opened.
`200 OK`	An auction was already live for this position, and you get that one back.

Opening is idempotent per (position, user), so a double-tap resumes the live auction instead of splitting bids across two. Check the status code or expires_at before you assume a fresh 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 or 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": "did:privy:cm3mm...",
      "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": 74.25,
      "mm_collateral_locked": 74.25,
      "total_payout": 99,
      "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:45:40.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" }
      ]
    }
  }
}

Overview

Quote service

Market maker

Markets

Parlays

Account

API keys

Funds and 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