> ## Documentation Index
> Fetch the complete documentation index at: https://docs.totalis.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Create cashout request

> Open an early cashout auction for an on-chain position.

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](/solana/api-reference/quote-service/cashout-stream) shows the highest live bid, and ties go to the earliest. Accept it with [Commit cashout](/solana/api-reference/quote-service/cashout-commit) to exit on-chain at that price or better.

You identify the position by its on-chain [`position_id`](/solana/glossary#identifiers). 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](/solana/limits-and-fees#timing))

## 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](/solana/authentication).

## Request body

<ParamField body="position_id" type="string" required>
  The position's on-chain id. A 16-byte hex string (32 hex chars), with or without a `0x` prefix.
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="cashout_request" type="object">
      The opened cashout request.

      <Expandable title="cashout_request">
        <ResponseField name="id" type="string">UUID of the cashout request. Use it on the stream, commit, and MM endpoints.</ResponseField>
        <ResponseField name="user_id" type="string">Your user ID.</ResponseField>
        <ResponseField name="counterparty_mm_id" type="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.</ResponseField>
        <ResponseField name="position_id" type="string">The on-chain position id (hex), normalized without the `0x` prefix.</ResponseField>
        <ResponseField name="position_pda" type="string">On-chain position address ([PDA](/solana/glossary#custody-terms)), or `null`.</ResponseField>
        <ResponseField name="db_position_id" type="string">Internal UUID of the position record. Distinct from the on-chain `position_id` hex.</ResponseField>
        <ResponseField name="user_wallet" type="string">Your wallet address on the position.</ResponseField>
        <ResponseField name="mm_wallet" type="string">The counterparty market maker's wallet address.</ResponseField>
        <ResponseField name="user_stake" type="number">Your net stake on the position (USDC). Always refunded on a buyback.</ResponseField>
        <ResponseField name="mm_risk" type="number">The counterparty's risk on the position (USDC): `total_payout - user_stake`.</ResponseField>
        <ResponseField name="mm_collateral_locked" type="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`.</ResponseField>
        <ResponseField name="total_payout" type="number">The position's total payout (USDC).</ResponseField>
        <ResponseField name="taker_fee_locked" type="number">The taker fee locked when the position was created (USDC).</ResponseField>
        <ResponseField name="version" type="integer">Request version, starts at `1`.</ResponseField>
        <ResponseField name="book_seq" type="integer">Quote book sequence number, starts at `0`.</ResponseField>
        <ResponseField name="status" type="string">`"active"`</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 time the cashout request was opened.</ResponseField>
        <ResponseField name="updated_at" type="string">ISO 8601 time of the last update to the request.</ResponseField>
        <ResponseField name="expires_at" type="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.</ResponseField>
        <ResponseField name="position_expires_at" type="string">The underlying position's market-end horizon, or `null`.</ResponseField>
        <ResponseField name="legs" type="array">The position's legs (ticker, side, venue, and resolution where known).</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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

<RequestExample>
  ```bash theme={null}
  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" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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" }
        ]
      }
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.