Callback Methods

This page documents every S2S callback method. Each method includes the request and response JSON, field descriptions, and behavioral notes. Your callback endpoint must handle all eight methods.

PING

Health check callback. Predictu sends this during operator onboarding, periodic monitoring, and when an admin clicks "Test Connection" in the God Mode dashboard. No player context - just verify connectivity and JWT validation.

Request

{
  "method": "PING",
  "timestamp": "2026-03-19T14:30:00.000Z",
  "request_id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
  "operator_id": "op_abc123",
  "params": {}
}

Response

{
  "status": "OK"
}

The params object is intentionally empty. Your handler should verify the JWT signature, confirm the operator_id is recognized, and return OK. No balance or transaction ID is needed.

BALANCE

Fetch a player's current wallet balance. Called before every trade to validate sufficient funds, and whenever the UI needs to display an up-to-date balance. This callback has no side effects - it is a read-only query.

Request

{
  "method": "BALANCE",
  "timestamp": "2026-03-19T14:30:00.000Z",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "operator_id": "op_abc123",
  "params": {
    "player_id": "player_456",
    "currency": "USD"
  }
}

Params

Response

{
  "status": "OK",
  "balance": 1000000
}

Return the player's current balance in subunits. If the player_id is not found, you may either return PLAYER_NOT_FOUND or auto-create the player with a default balance (the reference implementation auto-creates with 10,000.00 = 1,000,000 subunits).

BET_MAKE

Debit a player's wallet for a new prediction market bet. This is the most critical callback - it must be atomic and idempotent. If the debit succeeds, Predictu records the trade and updates the player's position. If the debit fails, no trade is recorded.

Request

{
  "method": "BET_MAKE",
  "timestamp": "2026-03-19T14:30:00.000Z",
  "request_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "operator_id": "op_abc123",
  "params": {
    "player_id": "player_456",
    "transaction_id": "tx_pred_001",
    "amount": 5200,
    "currency": "USD",
    "bet": {
      "market_id": "mkt_btc_100k",
      "market_title": "Will Bitcoin exceed $100k by June 2026?",
      "outcome": "yes",
      "odds": 1.92,
      "shares": 100,
      "execution_price": 52
    }
  }
}

Params

Bet Object

The bet object provides full context about the prediction market bet. This is informational for the operator's records and reporting - the debit amount is what matters for the wallet operation.

Response

// Success
{
  "status": "OK",
  "balance": 948000,
  "transaction_id": "op-tx-bet-001"
}

// Insufficient funds
{
  "status": "INSUFFICIENT_FUNDS",
  "balance": 3200,
  "error_message": "Player balance 3200 < debit amount 5200"
}

// Player not found
{
  "status": "PLAYER_NOT_FOUND",
  "error_message": "No player with ID player_456"
}

BET_WIN

Credit a player's wallet after their bet wins. Sent when a market resolves and the player's chosen outcome is correct. The credit amount equals shares × 100subunits ($1.00 per share).

Request

{
  "method": "BET_WIN",
  "timestamp": "2026-03-19T14:30:00.000Z",
  "request_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "operator_id": "op_abc123",
  "params": {
    "player_id": "player_456",
    "transaction_id": "tx_pred_002",
    "parent_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "amount": 10000,
    "currency": "USD",
    "settlement": {
      "market_id": "mkt_btc_100k",
      "market_title": "Will Bitcoin exceed $100k by June 2026?",
      "winning_outcome": "yes",
      "shares": 100,
      "cost_basis": 5200,
      "profit": 4800
    }
  }
}

Params

Settlement Object

Response

{
  "status": "OK",
  "balance": 1048000,
  "transaction_id": "op-tx-win-001"
}

BET_LOST

Notification that a player's bet has lost after market resolution. This callback has no money movement - the amount is always 0. It exists purely for bookkeeping so the operator can close the bet in their records and update reporting.

Request

{
  "method": "BET_LOST",
  "timestamp": "2026-03-19T14:30:00.000Z",
  "request_id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
  "operator_id": "op_abc123",
  "params": {
    "player_id": "player_456",
    "transaction_id": "tx_pred_003",
    "parent_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "amount": 0,
    "currency": "USD",
    "settlement": {
      "market_id": "mkt_btc_100k",
      "market_title": "Will Bitcoin exceed $100k by June 2026?",
      "winning_outcome": "no",
      "player_outcome": "yes",
      "shares": 100,
      "cost_basis": 5200
    }
  }
}

Settlement Object

Response

{
  "status": "OK",
  "balance": 948000,
  "transaction_id": "op-tx-loss-001"
}

BET_REFUND

Fully refund a player's bet. Triggered when a market is voided, cancelled by an admin, or determined to be invalid. The refund amount equals the original BET_MAKEdebit - the player is made completely whole.

Request

{
  "method": "BET_REFUND",
  "timestamp": "2026-03-19T14:30:00.000Z",
  "request_id": "e5f6a7b8-c9d0-1234-ef01-567890abcdef",
  "operator_id": "op_abc123",
  "params": {
    "player_id": "player_456",
    "transaction_id": "tx_pred_004",
    "parent_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "amount": 5200,
    "currency": "USD",
    "reason": "Market voided: ambiguous resolution criteria"
  }
}

Params

Response

{
  "status": "OK",
  "balance": 1000000,
  "transaction_id": "op-tx-refund-001"
}

BET_ROLLBACK

Reverse a BET_MAKE debit that succeeded at the operator but failed on Predictu's side (e.g., the trade recording or position update failed after the debit). This is the compensating transaction that ensures atomicity across the distributed system.

Request

{
  "method": "BET_ROLLBACK",
  "timestamp": "2026-03-19T14:30:01.000Z",
  "request_id": "f6a7b8c9-d0e1-2345-f012-678901abcdef",
  "operator_id": "op_abc123",
  "params": {
    "player_id": "player_456",
    "transaction_id": "tx_pred_005",
    "parent_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "amount": 5200,
    "currency": "USD",
    "reason": "Buy failed after debit - Failed to record trade: unique constraint violation"
  }
}

Params

Response

{
  "status": "OK",
  "balance": 1000000,
  "transaction_id": "op-tx-rollback-001"
}

BET_SELL

Credit a player for selling a position before market resolution. Unlike BET_WIN, the credit amount is based on the current market price (minus spread), not the full share value. The player may realize a profit or a loss depending on price movement.

Request

{
  "method": "BET_SELL",
  "timestamp": "2026-03-19T14:30:00.000Z",
  "request_id": "a7b8c9d0-e1f2-3456-0123-789012abcdef",
  "operator_id": "op_abc123",
  "params": {
    "player_id": "player_456",
    "transaction_id": "tx_pred_006",
    "parent_transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "amount": 6340,
    "currency": "USD",
    "sale": {
      "market_id": "mkt_btc_100k",
      "market_title": "Will Bitcoin exceed $100k by June 2026?",
      "outcome": "yes",
      "shares_sold": 100,
      "execution_price": 65,
      "realized_pnl": 1140
    }
  }
}

Sale Object

Response

{
  "status": "OK",
  "balance": 1006340,
  "transaction_id": "op-tx-sell-001"
}

P&L Examples

* Sell proceeds include spread. Even at the same mid price, the sell price (bid) is lower than the buy price (ask) due to spread, so the player realizes a small loss on an immediate round-trip.

Idempotency & Duplicate Handling

Every S2S request includes a unique request_id (UUID v4). This serves as the idempotency key. Your callback handler must implement duplicate detection.

Implementation Flow

// Idempotency check (reference implementation)
const existingTx = findTransactionByRequestId(request_id);
if (existingTx) {
  console.log("Duplicate request_id, returning cached result");
  const player = getPlayer(params.player_id);
  return {
    status: "DUPLICATE_TRANSACTION",
    balance: player.balance,
    transaction_id: existingTx.id,
  };
}

Error Handling Best Practices

Operator Side

• Always return valid JSON, even for errors. Predictu parses the response as JSON.
• Use the correct status codes: INSUFFICIENT_FUNDS for balance issues, PLAYER_NOT_FOUND for missing players, ERROR for everything else.
• Include balance in every response when possible, even error responses. This helps Predictu keep the UI in sync.
• Log every callback with the request_id for troubleshooting.
• Implement a transaction table with predictu_request_id as a unique index for idempotency.

Predictu Side

• OK and DUPLICATE_TRANSACTION are treated as success - the trade proceeds.
• INSUFFICIENT_FUNDS and PLAYER_NOT_FOUND are non-retryable business errors.
• ERROR status and HTTP failures (timeouts, 5xx) trigger exponential backoff retries.
• Non-JSON responses are treated as ERROR.
• After all retry attempts are exhausted, the transaction is marked as failed.

Method Summary Reference

* BET_MAKE retries use the same request_id, so idempotent duplicate detection prevents double-debits.