Reconciliation & History API

Operator endpoints for auditing rounds and reconciling wallet transactions. Both endpoints require HMAC-SHA256 authentication.

Authentication

Same pattern as the Game Launch API:

message = "api_key|round_id|timestamp"
signature = HMAC-SHA256(api_secret, message)

Timestamp Validation

Requests with timestamps older than 5 minutes are rejected with TIMESTAMP_EXPIRED. Ensure your system clock is synchronized (NTP recommended).

Endpoints

POST /v1/reconciliation/round

Returns all wallet transactions (debits, credits, rollbacks) for a given round.

Request:

{
  "api_key": "your-api-key",
  "round_id": 184721,
  "signature": "hmac-sha256-hex...",
  "timestamp": "1711234567"
}

Response:

{
  "round": {
    "id": 184721,
    "asset": "BTC",
    "entry_price": 71284.50,
    "settlement_price": 71310.25,
    "result": "up",
    "status": "settled",
    "start_time": "2026-03-19T14:00:00Z",
    "end_time": "2026-03-19T14:05:00Z"
  },
  "transactions": [
    {
      "id": "tx-uuid-1",
      "tx_type": "debit",
      "amount": 100.00,
      "idempotency_key": "bet-uuid-1",
      "status": "completed",
      "bet_id": "bet-uuid-1",
      "player_id": "player-uuid-1",
      "created_at": "2026-03-19T14:01:12Z"
    },
    {
      "id": "tx-uuid-2",
      "tx_type": "credit",
      "amount": 182.00,
      "idempotency_key": "credit-bet-uuid-1",
      "status": "completed",
      "bet_id": "bet-uuid-1",
      "player_id": "player-uuid-1",
      "created_at": "2026-03-19T14:05:01Z"
    }
  ]
}

Reconciliation Strategy

Every debit will have exactly one matching credit (win, loss with amount 0, or cashout). Use the idempotency_key to match transactions. A rollback replaces its corresponding debit.

---

POST /v1/history

Returns round details and all bets for compliance display.

Request: Same authentication format as above.

Response:

{
  "round": {
    "id": 184721,
    "asset": "BTC",
    "entry_price": 71284.50,
    "settlement_price": 71310.25,
    "result": "up",
    "status": "settled",
    "start_time": "2026-03-19T14:00:00Z",
    "end_time": "2026-03-19T14:05:00Z",
    "pyth_verification_url": "https://hermes.pyth.network/..."
  },
  "bets": [
    {
      "bet_id": "bet-uuid-1",
      "player_id": "player-uuid-1",
      "side": "up",
      "stake": 100.00,
      "odds": 1.82,
      "payout": 182.00,
      "result": "win",
      "cashed_out": false,
      "placed_at": "2026-03-19T14:01:12Z",
      "settled_at": "2026-03-19T14:05:01Z",
      "pyth_verification_url": "https://hermes.pyth.network/..."
    }
  ]
}

Error Codes

Error Code	HTTP Status	Description
INVALID_API_KEY	401	API key not recognized
INVALID_SIGNATURE	401	HMAC verification failed
QUERY_ERROR	500	Database query failed
DB_UNAVAILABLE	503	Database not connected