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

# API Overview

> Architecture of the PlayStarters integration: Operator API for catalog and game launch, Seamless Wallet API for balance and transactions.

The PlayStarters integration is split into two complementary APIs:

| API                     | Direction                   | Purpose                                                                                        |
| ----------------------- | --------------------------- | ---------------------------------------------------------------------------------------------- |
| **Operator API**        | Your backend → PlayStarters | Fetch providers, list games, generate game launch URLs.                                        |
| **Seamless Wallet API** | PlayStarters → Your backend | Read player balance and process financial transactions (`BET`, `WIN`, `VOID`) during gameplay. |

## Operator API

You call PlayStarters' REST endpoints to integrate the catalog and game launch into your site.

* **Base URL** — [https://api.playstarters.io](https://api.playstarters.io)
* **Authentication** — `Authorization: ApiKey ps_<your_api_key>` header.
* **Format** — JSON request and response bodies.

See [Authentication](/api/authentication) and the Operator API reference: [Providers](/api/operator/providers), [Games](/api/operator/games), [Launch](/api/operator/launch).

## Seamless Wallet API

You expose a single `POST` endpoint that PlayStarters calls during gameplay.

* **Base URL** — provided by you (e.g. `https://api.yoursite.com/wallet-callback`).
* **Authentication** — PlayStarters sends `Authorization: Bearer <your_api_key>` (your same API key, sent as a Bearer token).
* **HTTP method** — always `POST`.
* **Operation type** — identified by the `type` field in the request body (`BALANCE`, `BET`, `WIN`, `VOID`).

Every successful response must return HTTP `200 OK` with the updated balance:

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

See the Wallet API reference: [Overview](/api/wallet/overview), [Balance](/api/wallet/balance), [Transactions](/api/wallet/transactions), [Idempotency](/api/wallet/idempotency).

## Currency and amounts

* Amounts are decimal numbers in the player's wallet currency (e.g. `10.0`, `150.50`).
* The `currency` field uses ISO 4217 codes (e.g. `EUR`, `USD`, `BRL`).
* Player and transaction IDs are strings (UUIDs from PlayStarters, your own player IDs are passed back unchanged).

<Note>
  Keep your API key secret at all times. Never expose it in client-side code, public repositories, or browser-accessible configuration files.
</Note>

<Danger>
  **Reliability note:**\
  Playstarters does not implement automatic retries with backoff.\
  \
  If your wallet endpoint returns an error (non-2xx) or times out (> 10 seconds), the error is propagated to the game provider.\
  \
  The provider may retry according to its own policy. Your wallet endpoint **must be idempotent** (via `requestId`) to safely handle provider-level retries.
</Danger>