S2S Protocol
Reference Implementation
Predictu provides a complete, working reference implementation that demonstrates how to integrate with the S2S callback protocol. This ready-to-run starter project handles every callback type, giving your engineering team a tested foundation to build on rather than starting from scratch.
Accelerate your integration. The reference implementation covers the full S2S protocol surface area. Use it as a learning tool, a test harness, or the starting point for your production integration.
What It Includes
The reference implementation is a self-contained server that acts as a fully functional casino operator backend. It includes:
- Complete callback handler — receives and processes all eight S2S callback types (health check, balance inquiry, bet placement, win settlement, loss notification, position sale, refund, and rollback).
- Signature verification — validates the cryptographic signature on every incoming callback to confirm authenticity.
- Idempotency checking — detects and correctly handles duplicate requests, preventing double-debits during retries.
- Wallet operations — atomic debit and credit operations with proper balance validation and error handling.
- Transaction recording — full audit trail of every callback processed, with the request identifier stored for idempotency.
- Replay protection — tracks processed token identifiers to prevent replay attacks.
- Casino frontend — a simple web page that embeds the Predictu widget via iframe and implements the real-time communication bridge.
How It Works
1
The casino page loads — A web page is served that embeds the Predictu prediction market widget. The page implements the communication bridge to initialize player sessions and receive trade events.
2
A player places a trade — When the player interacts with the widget, Predictu's backend sends a signed callback to the reference server's callback endpoint.
3
The server processes the callback — The reference implementation verifies the signature, checks for duplicates, performs the wallet operation (debit or credit), records the transaction, and returns a response.
4
The player sees the result — The widget updates with the player's new balance and position, and the casino shell receives a trade confirmation event.
Callback Handling Pattern
Every incoming callback follows the same three-step processing pattern:
1
Verify — Validate the cryptographic signature. Reject the request if verification fails.
2
Deduplicate — Check if this request has already been processed. If so, return the cached result without re-processing.
3
Process — Route to the appropriate handler based on the callback type. Perform the wallet operation, record the transaction, and return the result.
Wallet Operations
The reference implementation demonstrates two core wallet operations:
| Operation | Used By | Behavior |
|---|---|---|
| Debit | Bet placement | Checks the player exists, verifies sufficient funds, subtracts the amount, and returns the updated balance. Returns a specific error status if the player is not found or lacks sufficient funds. |
| Credit | Win, sale, refund, rollback | Checks the player exists, adds the amount, and returns the updated balance. Credits always succeed as long as the player exists. |
Adapting for Production
The reference implementation is intentionally simplified for clarity. When building your production integration, you will want to adapt several areas to match your existing infrastructure:
| Reference Simplification | Production Recommendation |
|---|---|
| Lightweight embedded database | Use your existing production database with proper row-level locking for concurrent access. |
| Optional signature bypass for local testing | Always verify signatures in production. Never disable cryptographic verification. |
| Open admin endpoints | Protect management and reporting endpoints with your existing authentication system. |
| Auto-create players on first contact | Map Predictu player identifiers to your existing user system. Reject unknown players. |
| Demo starting balance | Use real player balances from your existing wallet system. |
| Single-process server | Deploy behind a load balancer with a shared database for horizontal scaling. |
| No rate limiting | Add rate limiting on the callback endpoint to protect against abuse. |
| Console logging | Use structured logging with request identifiers for production observability. |
| No IP restrictions | Restrict your callback endpoint to Predictu's IP addresses (provided during onboarding). |
Protocol, not infrastructure. The changes above are operational hardening, not protocol changes. The callback handling logic — verify, deduplicate, process — remains exactly the same in production. The reference implementation covers the full protocol surface area.
Key Benefits
- Reduced integration time — start with a working implementation instead of building from scratch. Your team can focus on adapting the patterns to your existing systems rather than interpreting protocol documentation.
- Tested patterns — the reference implementation handles edge cases like duplicate requests, insufficient funds, player not found, and rollback scenarios. These patterns are battle-tested and ready to adopt.
- Easy to adapt — the callback handling logic is straightforward and language-agnostic. The patterns translate directly to any backend technology stack your team uses.
- Complete coverage — every callback type is implemented, so you can see exactly how each one should be handled before writing your own version.
- Built-in test harness — the included casino frontend lets you trigger real callbacks end-to-end, making it easy to test your understanding of the protocol before connecting to your production systems.