S2S Protocol

Server-to-Server Protocol

The Predictu S2S (Server-to-Server) protocol ensures that your casino always remains in full control of player wallets. Every financial operation — from bet placement to settlement — flows through secure, cryptographically signed callbacks to your backend. Predictu never stores or controls real player funds.

You own the wallet. We own the game logic. Every debit, credit, and balance check is delegated to your backend via a signed HTTP callback. Your existing wallet infrastructure stays exactly as it is.

How It Works

When a player interacts with the Predictu prediction market widget on your casino site, every financial operation triggers a secure server-to-server callback from Predictu to your registered endpoint. Your backend processes the request, updates the player's wallet, and returns a response. The widget then updates the player's UI in real time.

Player takes an action — A player places a trade, sells a position, or triggers any other financial event inside the prediction market widget on your casino site.

Predictu validates and prices — The trading engine validates the request, checks risk limits, and calculates the final execution price including spread.

Predictu sends a signed callback — A cryptographically signed request is sent to your registered callback endpoint containing the player identifier, amount, and full context about the operation.

Your backend processes the request — You verify the cryptographic signature, check for duplicate requests, update the player's wallet, and return a response with the updated balance.

Predictu records the outcome — On receiving your confirmation, Predictu records the trade, updates the player's position, and adjusts exposure tracking.

Player sees the result — The widget shows the player their new position and updated balance in real time.

Callback Types

The protocol covers the full lifecycle of a prediction market bet — from placement through settlement or early sale. Eight callback types handle every possible scenario:

Callback	Direction	Description
Health check	No money movement	Verifies connectivity between Predictu and your backend. Used during onboarding and ongoing monitoring.
Balance inquiry	No money movement	Fetches a player's current wallet balance. Called before trades to validate sufficient funds.
Bet placement	Debit from player	Debits the player's wallet for a new prediction market bet. Includes full bet context — market, outcome, odds, and shares.
Win settlement	Credit to player	Credits the player's wallet after their prediction is correct and the market resolves in their favor.
Loss notification	No money movement	Notifies your backend that a player's bet has lost. Informational only — the funds were already debited at bet placement.
Position sale	Credit to player	Credits the player for selling their position before the market resolves. The payout reflects the current market price.
Refund	Credit to player	Fully refunds the original bet cost when a market is voided or cancelled. The player is made completely whole.
Rollback	Credit to player	Reverses a debit that succeeded on your side but failed on Predictu's side. Ensures atomicity across the distributed system.

Bet Lifecycle

Every prediction market bet follows one of several paths after placement. Each path starts with a bet placement callback and ends with exactly one terminal callback:

Winning bet: Bet placed, market resolves in the player's favor, winnings credited.
Losing bet: Bet placed, market resolves against the player, loss notification sent.
Early sale: Bet placed, player sells their position before the market resolves, sale proceeds credited.
Voided market: Bet placed, market is cancelled or voided, original bet amount fully refunded.
Failed trade: Bet placed (debit succeeds), but a downstream error prevents the trade from completing. The debit is automatically rolled back.

Reliability and Retry Logic

The S2S protocol is designed for reliability. If a callback fails due to a network error or a temporary issue on your backend, Predictu automatically retries with exponential backoff. This ensures that transient failures do not result in lost transactions.

Retries use the same unique request identifier, so your idempotency logic prevents duplicate processing.
Business-level errors (such as insufficient funds) are never retried — only infrastructure failures trigger retries.
Retry timing, maximum attempts, and request timeouts are all configurable per operator.

Full Audit Trail

Every callback — both the outbound request and your response — is recorded with full detail. This comprehensive audit trail includes request payloads, response payloads, timing data, and retry history. It serves as the foundation for reconciliation, debugging, and operator support.

Key Benefits

You own the wallet — Predictu never holds or controls player funds. Your existing wallet system remains the single source of truth.
Cryptographic verification — every callback is signed so you can verify it genuinely originated from Predictu and has not been tampered with.
Full audit trail — complete records of every callback for reconciliation, compliance, and debugging.
Automatic retry — transient failures are handled automatically with configurable retry policies.
Industry-standard architecture — the callback-based model follows established patterns used by leading gaming platforms, making integration familiar for experienced teams.

Next Steps

Wallet Callback Methods — detailed overview of each callback type and the request/response lifecycle.
Cryptographic Security — how callbacks are signed and how to verify them.
Reference Implementation — a working starter project to accelerate your integration.