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

# Seamless Wallet Overview

> The webhook endpoint your backend exposes so PlayStarters can read balances and process transactions during gameplay.

The Seamless Wallet API lets PlayStarters use your existing player balances as the source of truth during gameplay. You expose **a single `POST` endpoint** that handles all operation types, identified by the `type` field in the request body.

## Endpoint contract

| Property                | Value                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **URL**                 | Provided by you (e.g. `https://api.yoursite.com/wallet-callback`).                  |
| **HTTP method**         | Always `POST`.                                                                      |
| **Authentication**      | `Authorization: Bearer <your_api_key>` (your same API key, sent as a Bearer token). |
| **Request body**        | JSON, with `type` indicating the operation.                                         |
| **Successful response** | HTTP `200 OK` with the updated balance: `{ "balance": 100.50 }`.                    |

## Supported operation types

| `type`    | Description                                       | Reference                                |
| --------- | ------------------------------------------------- | ---------------------------------------- |
| `BALANCE` | Read the current balance for a player.            | [Balance Read](/api/wallet/balance)      |
| `BET`     | Deduct the bet amount from the player's balance.  | [Transactions](/api/wallet/transactions) |
| `WIN`     | Credit the win amount to the player's balance.    | [Transactions](/api/wallet/transactions) |
| `VOID`    | Refund a previously placed bet (round cancelled). | [Transactions](/api/wallet/transactions) |

## Common request fields

Every call from PlayStarters to your endpoint includes the following fields:

<ResponseField name="playerId" type="string">
  Your unique identifier for the player (the same value you passed as `playerId` to [`POST /operator/launch`](/api/operator/launch)).
</ResponseField>

<ResponseField name="type" type="string">
  Operation type. One of `BALANCE`, `BET`, `WIN`, `VOID`.
</ResponseField>

<ResponseField name="amount" type="number">
  Transaction amount in the player's currency. `0` for `BALANCE` operations.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code (e.g. `EUR`).
</ResponseField>

<ResponseField name="requestId" type="string">
  Unique identifier for this request. Use it for [idempotency](/api/wallet/idempotency).
</ResponseField>

<ResponseField name="gameId" type="string">
  UUID of the game the transaction belongs to. Not sent for `BALANCE` operations.
</ResponseField>

<ResponseField name="roundId" type="string">
  Identifier for the game round. Groups related BET/WIN/VOID transactions together. Not sent for `BALANCE` operations.
</ResponseField>

<ResponseField name="parentTransactionId" type="string">
  Present only on `WIN` and `VOID`. Correlates the transaction with the original `BET`'s `requestId`.
</ResponseField>

## Successful response

Always return HTTP `200 OK` with the player's updated balance:

```json theme={null}
{ "balance": 100.50 }
```

## Error response

The only error response PlayStarters expects is **insufficient funds** on a `BET`. See [Transactions](/api/wallet/transactions#insufficient-funds) for the exact format.

<Warning>
  Always verify the `Authorization` header on every incoming request. Never trust the body fields without authenticating the caller first.
</Warning>