## ARENA BATTLE — SITE WALLET CONFIGURATION (R24)

## 1. Install the operator callback receiver
Follow SEAMLESS-WALLET.en.txt and `slot-battles-seamless-wallet.mjs`.
Expose one POST endpoint that handles balance, entry, settlement and
refund operations using your authoritative wallet ledger. Do not use
transfer funding and a single site wallet for the same account.

## 2. Configure the provider console
Connected sites > site > Settings > Site wallet > Wallet connection.
Select Single site wallet, enter the full HTTPS callback URL, then save.
Timeout: 1,000–15,000 ms, default 8,000 ms. The first save returns the
generated signing secret only once. Store it in the operator server's
secret environment. Never expose it to players or an iframe. The
operator portal receives only the model, endpoint and request status.

## 3. Changing models safely
Generic tenant editing cannot change the wallet model. Open rooms,
reserved funds, pending wallet commands/settlement jobs or existing
transfer balances prevent changes. Reconcile with the original model;
never reset funds to migrate. Seamless mode disables guest accounts and
opening balances. Persistent player identities remain unchanged.
URL, timeout and secret changes also require pending work to finish.

## 4. Signatures and network
Both request and response are signed with HMAC-SHA256 over the timestamp and exact raw JSON body. The following is the signature formula, not a standalone program:

```text Signature formula
signature = HMAC_SHA256(secret, timestamp + "." + rawBody)
```

Use these headers. Replace placeholders with the timestamp and signature produced by the wallet SDK:

```http Signature headers
X-Slot-Wallet-Timestamp: <unix-milliseconds>
X-Slot-Wallet-Signature: <lowercase-hex-hmac-sha256>
```

Maximum accepted clock skew: 60 seconds. Retries retain the transaction ID. A repeated ID must never change money twice, and reusing an ID with different contents must fail. Network failure is not a new payment.

Use public HTTPS endpoints with no redirects, credentials, query or fragment. A development server may explicitly permit HTTP loopback 127.0.0.1 / localhost / ::1. This exception never permits private/LAN IPs.

## 5. Administration API
Read the configuration:

```http
GET /control/api/tenants/:id/wallet
```

Update the wallet connection:

```http
PATCH /control/api/tenants/:id/wallet
```

```json Wallet configuration body
{
  "mode": "seamless",
  "url": "https://operator.example/api/slot-wallet",
  "timeoutMs": 8000
}
```

Rotate the signing secret:

```http
POST /control/api/tenants/:id/wallet/rotate
```

```json Rotation body
{}
```

Replace :id with the assigned tenant ID. Reads require `sites.read`. Writes require `sites.manage`, an authenticated admin session and its CSRF header, not an operator API key. GET never returns a secret. Only the first PATCH and secret rotation return it once. Preserve both the control database and `tenant-wallet-master.key` together in backups.

## 6. Operator portal
API & integration shows the actual wallet model, callback endpoint,
configuration state and last request time. Use the separate API key for
launch, player and history endpoints. Never create money movements in
the browser. Follow SEAMLESS-WALLET.en.txt for wallet operations,
transaction history and retry reconciliation.
