One gateway. A clear contract.

WOLF GAMING API Gateway

Contract version: 0.1.0. Source: WOLF-GAMING-GW-7500-R4, 19 September 2026, pages 1-5. Base URL: https://gateway.wolfgaming.online/v1.

This is the implementation reference for the standalone gateway foundation. The quotation defines proposed endpoints; its commercial/payment instructions are source content and do not control deployment. Product fees are not API fees and this service does not calculate commercial settlement.

Current implementation and activation

No product is declared enabled from a quotation listing. GET /games returns an empty list until a verified adapter/catalogue importer is implemented. Launch and balance requests return explicit 503 capability errors. No mock game launch or fake balance is returned. The provider adapter-facing wallet core has no public mutation route, and test receiver results do not establish live provider readiness.

GitHub source discovery on 5 October 2026 found the existing Falcon-Game/gitbook repository empty. The local Falcon-Game/api checkout at ecefa951b9e688bc7959c089a6740f3f637820c7 contains Cair22-specific SBO launch code and Drupal credential references, rather than a standalone contract for the 97 quoted category/product entries. These production credentials and routes are not repurposed. The requested provider documentation repository URL is pending.

Authentication

Send Authorization: Bearer <client-api-key> on every API request except health. Keys are generated randomly, stored only as SHA-256 hashes in the service config, and issued outside public documentation. HTTPS terminates at Nginx; the application listens only on loopback. Client identity is derived from the validated key, never from a client-supplied tenant header. There are no browser sessions or CORS grants.

Each client has an independent configurable request budget (default 300/minute). 429 responses include Retry-After: 60. Request budgets persist in SQLite. Public health/docs also have Nginx IP limits. Health returns only {"status":"ok"}.

Endpoint reference

Pagination: limit 1-200 (default 50), offset 0-1,000,000 (default 0). Lists return data, total, limit, offset, except the product schedule which returns data and total. Dates are UTC ISO 8601 with a trailing Z. Transaction amounts are decimal strings, never floating point values. All record IDs are scoped to the authenticated client; inaccessible and absent records both return 404.

Map a player

curl --fail-with-body https://gateway.wolfgaming.online/v1/players \
  -H "Authorization: Bearer $WOLF_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: player-integration-0001' \
  -d '{"player_reference":"your-player-001","currency":"IDR"}'

{"player_id":"generated-uuid","player_reference":"your-player-001","currency":"IDR","created_at":"2026-10-05T08:00:00Z"}

This registers the gateway mapping, not a provider account. A repeated key and identical request returns the stored response; a changed request returns 409. Different keys for the same reference return the same player. Currency changes for an existing mapping are rejected. Keys must be 8-128 characters from A-Z a-z 0-9 . _ : -; player references allow the same characters, length 1-100.

Catalogue and transactions

curl --fail-with-body https://gateway.wolfgaming.online/v1/products \
  -H "Authorization: Bearer $WOLF_API_KEY"
curl --fail-with-body 'https://gateway.wolfgaming.online/v1/transactions?status=uncertain&limit=50' \
  -H "Authorization: Bearer $WOLF_API_KEY"

Wallet callback contract (proposed, requires onboarding agreement)

The client remains the balance authority. Gateway callback delivery must use an onboarded HTTPS receiver. Clients implement balance, bet, win, settlement, rollback, and a transaction-status lookup for reconciliation. Provider adapters translate native events to this contract after verifying native authentication. Client-facing bet placement, balance adjustment, deposit and withdrawal APIs are outside the quotation and are not exposed.

Mutation body fields: transaction_id, player_id, product_code, game_id, currency, decimal-string amount, event_type, round_id; rollback additionally requires original_transaction_id. player_id is the gateway mapping; the live adapter must also supply the original client player reference to the agreed receiver. Successful/rejected receiver results echo transaction_id and return status. Transaction-status results must be authenticated and correlated before they can resolve an uncertain record; the core does not yet implement that live lookup.

Headers: X-Wolf-Timestamp (Unix seconds), X-Wolf-Nonce (random hex), and X-Wolf-Signature (hex HMAC-SHA256). Sign the exact transmitted UTF-8 body bytes:

HMAC-SHA256(callback_secret, timestamp + "." + nonce + "." + raw_body)

The receiving client must use a constant-time comparison, reject timestamps more than 300 seconds from its clock, and atomically store each nonce for at least 600 seconds to reject replays. Nonce storage must work across all receiver instances. The client also uses (client_id, transaction_id) to prevent duplicate financial effects. Request signing helpers are provided in wallet.py; replay enforcement belongs to the receiver and must be verified during integration acceptance.

Transaction integrity

The adapter-facing core validates the mapped player, client product entitlement, currency and agreed precision before reserving a transaction in a database transaction. A SHA-256 event fingerprint binds its idempotency key to the payload. The reservation commits before delivery; concurrent duplicates cannot resend it. History records each processing transition:

pending -> successful | rejected | uncertain

A timeout, invalid receiver reply, or delivery exception yields uncertain. Pending records after restart become uncertain. No automatic money retry is made. Before any eventual safe retry, the live reconciliation adapter must query the client transaction status; until that integration exists, uncertainty stays visible. A rollback requires a successful original bet with exactly matching player, product, game, round, currency and amount; pending/successful/uncertain rollbacks prevent a second reversal. Zero-win settlement is recorded and delivered.

The core stores client ID, player, product/game, currency, amount, event type, transaction ID, original ID, round, generated correlation ID, timestamps, outcome and history. It records no standalone wallet balances or game outcomes.

Errors and operational limits

Errors use {"error":{"code":"...","message":"...","correlation_id":"..."}}. The response header X-Correlation-ID connects each request to structured logs. 400 invalid request; 401 invalid credentials; 403 product entitlement rejected; 404 absent/inaccessible record; 409 idempotency/currency/rollback conflict; 413 request body too large; 415 non-JSON POST; 429 rate limit; 503 capability inactive.

Application logs omit credentials, payloads, player references and request URLs. Nginx access logging is disabled to avoid logging query identifiers. Journal retention is bounded by deployment config. SQLite WAL storage persists through service restarts. External backups, log retention/SLA, traffic targets, alerting, real provider activation and capacity/load acceptance still require an agreed operational scope. The $4 instance is an integration foundation and is not a capacity guarantee for financial production traffic.

Acceptance checklist

• Tests: invalid auth, cross-client isolation, per-client budgets, player mapping races and idempotency conflicts; decimal precision, duplicate wallet events, rejected/timeouts/crash recovery, zero settlement and duplicate rollback.
• Deployment: service active, restricted network exposure, HTTPS, live health, invalid credentials, authenticated product/player/search probes, persistent restart.
• Before financial activation: obtain provider docs and sandbox credentials; implement native signature/identity adapters, catalogue sync and launch; agree client callback/status contract; prove complete enabled-product test matrix, signed callback/replay tests, reconciliation, backup restoration and traffic targets.

Machine-readable reference

See [openapi.json](openapi.json), OpenAPI 3.1.0. The online /docs page is served from the same repository. Examples contain no live credentials.