S2S Protocol

Wallet Callback Methods

Predictu communicates with your backend through eight distinct callback methods. Each method represents a specific wallet operation or lifecycle event. Your single callback endpoint receives all methods and routes them to the appropriate handler based on the operation type.

All monetary values use integer subunits. Amounts are expressed in the smallest currency unit (e.g., cents for USD) to eliminate floating-point precision issues. All callbacks are cryptographically signed and delivered to your registered endpoint.

Health Check

A connectivity and configuration test. Predictu sends this during operator onboarding, periodic monitoring, and when testing the connection from the admin interface. Your handler simply verifies the signature and confirms the connection is working.

No player context is included.
No wallet operation is performed.
Useful for validating that your signature verification is working correctly before testing with real financial operations.

Balance Check

Fetches a player's current wallet balance. This is a read-only query with no side effects — your backend simply looks up the player and returns their current balance.

Called before every trade to validate sufficient funds.
Called whenever the widget needs to display an up-to-date balance.
Your response should include the player's current balance in subunits.

Bet Placement

The most critical callback. Debits a player's wallet when they place a new prediction market bet. Your handler must be atomic (either the full debit succeeds or nothing changes) and idempotent (processing the same request twice produces the same result without double-debiting).

Includes the amount to debit and full context about the bet — which market, which outcome, the odds, number of shares, and execution price.
If the player lacks sufficient funds, respond with a business-level insufficient funds status. Predictu will not retry this.
If the request identifier has already been processed, respond with a duplicate status and the cached result. This prevents double-debits when retries occur.

Win Settlement

Credits a player's wallet after their bet wins. Sent when a market resolves and the player's chosen outcome is correct.

Includes the credit amount, a reference to the original bet placement, and full settlement details (market, winning outcome, shares, cost basis, and profit).
The credit amount represents the full payout for the player's winning shares.

Loss Notification

Notifies your backend that a player's bet has lost after market resolution. This is purely informational — there is no money movement because the funds were already debited at bet placement.

The amount is always zero.
Includes a reference to the original bet and settlement details so your system can close the bet in its records.
Useful for reporting and reconciliation.

Position Sale

Credits a player for selling their position before the market resolves. Unlike a win settlement, the credit amount reflects the current market price at the time of sale (minus spread), not the full share value. The player may realize a profit or a loss depending on how the price has moved since they purchased.

Includes details about the sale — market, outcome, shares sold, execution price, and the realized profit or loss.
Links back to the original bet placement for audit trail continuity.

Refund

Fully refunds the original bet cost. Triggered when a market is voided, cancelled, or determined to be invalid. The refund amount equals the exact amount debited during the original bet placement, making the player completely whole.

Includes a human-readable reason for the refund, useful for audit trails and customer support.
Links back to the original bet placement being refunded.

Rollback

Reverses a bet placement debit that succeeded on your side but failed downstream on Predictu's side. This is the compensating transaction that ensures atomicity across the distributed system.

If you receive a rollback, it means the debit was processed successfully but the trade could not be completed. You must credit the amount back.
Includes a technical reason explaining why the rollback was necessary.
Failing to process a rollback leaves the player's balance permanently incorrect.

Rollbacks are critical. Always process rollback callbacks promptly. They represent a situation where money was debited from the player but no corresponding trade was recorded. The player must be made whole.

Request and Response Lifecycle

Every callback follows the same lifecycle:

Predictu sends a signed request — The callback arrives at your registered endpoint with a cryptographic signature and a unique request identifier.

You verify the signature — Confirm the request is authentic and has not been tampered with.

You check for duplicates — If you have already processed this request identifier, return the cached result immediately without re-processing.

You process the wallet operation — Perform the debit, credit, or balance lookup as appropriate for the callback type.

You return a response — Send back a status indicating success or the specific failure reason, along with the player's updated balance and your internal transaction identifier.

Reliability Features

Feature	Description
Automatic retry	Network failures and temporary errors trigger automatic retries with exponential backoff. Duplicate detection on your side prevents double-processing.
Idempotent design	Every request includes a unique identifier. Processing the same request twice always produces the same result without unwanted side effects.
Smart error handling	Business-level errors (insufficient funds, player not found) are never retried. Only infrastructure failures trigger retry logic.
Configurable timeouts	Request timeout, maximum retry attempts, and backoff intervals are all configurable per operator to match your infrastructure characteristics.

Method Summary

Callback	Wallet Operation	Links to Original Bet
Health check	None	No
Balance check	Read only	No
Bet placement	Debit	No (this is the original bet)
Win settlement	Credit	Yes
Loss notification	None (informational)	Yes
Position sale	Credit	Yes
Refund	Credit	Yes
Rollback	Credit	Yes