Get Cashout Request

curl https://api.totalis.trade/v1/cashout-requests/c3d4e5f6-7890-abcd-ef12-34567890abcd \
  -H "X-API-Key: $TOTALIS_API_KEY"

{
  "data": {
    "cashout_request": {
      "id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
      "user_id": "did:privy:cm3abc...",
      "target_mm_id": "mm-uuid-1234",
      "position_id": "9f86d08818844f86d08818844f86d088",
      "position_pda": "7Xc3...PDA",
      "user_stake": 24.75,
      "total_payout": 100,
      "version": 1,
      "book_seq": 3,
      "status": "active",
      "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" }
      ]
    },
    "best_quote": {
      "id": "q1w2e3r4-5678-90ab-cdef-1234567890ab",
      "market_maker_id": "mm-uuid-1234",
      "buyback_price": 41.5,
      "mm_pays_user": true,
      "valid_until": "2026-06-01T18:45:45.000Z",
      "net_received": 66.25
    }
  }
}

GET

cashout-requests

{id}

curl https://api.totalis.trade/v1/cashout-requests/c3d4e5f6-7890-abcd-ef12-34567890abcd \
  -H "X-API-Key: $TOTALIS_API_KEY"

{
  "data": {
    "cashout_request": {
      "id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
      "user_id": "did:privy:cm3abc...",
      "target_mm_id": "mm-uuid-1234",
      "position_id": "9f86d08818844f86d08818844f86d088",
      "position_pda": "7Xc3...PDA",
      "user_stake": 24.75,
      "total_payout": 100,
      "version": 1,
      "book_seq": 3,
      "status": "active",
      "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" }
      ]
    },
    "best_quote": {
      "id": "q1w2e3r4-5678-90ab-cdef-1234567890ab",
      "market_maker_id": "mm-uuid-1234",
      "buyback_price": 41.5,
      "mm_pays_user": true,
      "valid_until": "2026-06-01T18:45:45.000Z",
      "net_received": 66.25
    }
  }
}

This endpoint mirrors Get quote request and reuses the cashout request and quote fields documented in Create cashout request and Stream cashout quote — but its response shape has not been verified against the live API. Confirm field names and shapes with engineering before treating this page as authoritative.

Retrieve a cashout request by ID. The response includes the full cashout request object and its current best (buyback) quote, if one is live. Use this endpoint to check the current state of a cashout request. For real time updates, use the SSE stream instead.

Authentication

API key required. Pass your API key in the X-API-Key header. The key needs the positions:read scope.

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).

Response

data

object

Show data

cashout_request

object

The cashout request object.

Show cashout_request

string

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

user_id

string

Your user ID.

target_mm_id

string

The position’s maker — the single MM this request is offered to.

position_id

string

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

position_pda

string

On chain position address, or null.

user_stake

number

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

total_payout

number

The position’s total payout (USDC).

version

integer

Request version.

book_seq

integer

Quote book sequence number.

status

string

active, committing, committed, declined, expired, or cancelled.

expires_at

string

ISO 8601 TTL horizon of the cashout request (~90 s), distinct from the position expiry.

position_expires_at

string

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

legs

array

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

best_quote

object

The market maker’s current buyback quote, or null if none is live.

Show best_quote

string

Quote UUID.

market_maker_id

string

The backing market maker’s ID.

buyback_price

number

The directional buyback amount the MM quoted (USDC, ≥ 0), gross of the profit fee.

mm_pays_user

boolean

true when the MM pays the user (position is in profit); false when the user pays the MM.

valid_until

string

ISO 8601 timestamp when this quote expires.

net_received

number

The net cash the user walks away with after the buyback (USDC, ≥ 0). Present only when computable; omitted otherwise.

Errors

Status	Code	Description
401	`UNAUTHORIZED`	Missing or invalid API key.
403	`FORBIDDEN`	You do not own this cashout request.
404	`NOT_FOUND`	Cashout request not found.

curl https://api.totalis.trade/v1/cashout-requests/c3d4e5f6-7890-abcd-ef12-34567890abcd \
  -H "X-API-Key: $TOTALIS_API_KEY"

{
  "data": {
    "cashout_request": {
      "id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
      "user_id": "did:privy:cm3abc...",
      "target_mm_id": "mm-uuid-1234",
      "position_id": "9f86d08818844f86d08818844f86d088",
      "position_pda": "7Xc3...PDA",
      "user_stake": 24.75,
      "total_payout": 100,
      "version": 1,
      "book_seq": 3,
      "status": "active",
      "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" }
      ]
    },
    "best_quote": {
      "id": "q1w2e3r4-5678-90ab-cdef-1234567890ab",
      "market_maker_id": "mm-uuid-1234",
      "buyback_price": 41.5,
      "mm_pays_user": true,
      "valid_until": "2026-06-01T18:45:45.000Z",
      "net_received": 66.25
    }
  }
}

Create Cashout Request Stream Cashout Quote

⌘I

​Authentication

​Path parameters

​Response

​Errors

Authentication

Path parameters

Response

Errors