> ## 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 (buyback) request for an on chain position.

Open a **cashout request** to close an active on chain position early instead of waiting for settlement. The request is offered to the position's single counterparty market maker, who responds with a live buyback quote on the [stream](/api-reference/quote-service/cashout-stream). Accepting that quote via [Commit](/api-reference/quote-service/cashout-commit) drives the buyback on chain and flips the RFQ to `bought_back`.

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](/guides/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="target_mm_id" type="string">The position's maker — the single MM this request is offered to.</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, or `null`.</ResponseField>
        <ResponseField name="user_stake" type="number">Your net stake on the position (USDC). Always refunded on a buyback.</ResponseField>
        <ResponseField name="total_payout" type="number">The position's total payout (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="expires_at" type="string">ISO 8601 TTL horizon of the cashout request (\~90 s), distinct from the position expiry.</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>

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

<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...",
        "target_mm_id": "mm-uuid-1234",
        "position_id": "9f86d08818844f86d08818844f86d088",
        "position_pda": "7Xc3...PDA",
        "user_stake": 24.75,
        "total_payout": 100,
        "version": 1,
        "book_seq": 0,
        "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" },
          { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "market_ticker": "KXBTC-26JUN01-T73000", "event_ticker": "KXBTC-26JUN01", "side": "no", "venue": "kalshi" }
        ]
      }
    }
  }
  ```
</ResponseExample>