Casino API

The Casino API is the primary interface for interacting with Predictu’s prediction market platform. It handles trading, balance management, position tracking, and market configuration. All endpoints require authentication via a session token (for user-facing requests) or an operator API key (for server-to-server requests).

Error Handling

All endpoints return errors in a consistent format. HTTP status codes follow REST conventions.

// Error response format:
{
  "error": "Insufficient balance"
}

Error responses always contain an error string. Some endpoints return structured error codes for programmatic handling:

Trade (Buy/Sell)

Place a buy or sell trade on a prediction market. This is the core trading endpoint. It runs through a 12-step execution pipeline: validate inputs, run risk assessment (5 walls of defence), calculate spread-adjusted price, resolve operator, get wallet adapter, check balance, debit/credit via adapter, record trade, upsert position, update exposure, update wagering stats, and return the result (or rollback via compensating transaction on failure).

Request Body

{
  "marketId": "0x1234abcd...",
  "side": "buy",
  "outcome": "yes",
  "amount": 25.00,
  "midPrice": 62,
  "marketTitle": "Will Bitcoin hit $100k by June?",
  "category": "crypto",
  "liquidity": 150000
}

Response (200 OK)

{
  "success": true,
  "tradeId": "uuid-string",
  "positionId": "uuid-string",
  "executionPrice": 64,
  "shares": 39.0625,
  "cost": 25.00,
  "newBalance": 75.00
}

Selling Positions

When side is "sell", the amount field represents the number ofshares to sell (not a dollar amount). The user must hold at least this many shares in the specified outcome. Sell responses include an additional realizedPnl field.

// Sell request:
{
  "marketId": "0x1234abcd...",
  "side": "sell",
  "outcome": "yes",
  "amount": 20.00,
  "midPrice": 68
}

// Sell response includes realizedPnl:
{
  "success": true,
  "tradeId": "uuid-string",
  "positionId": "uuid-string",
  "executionPrice": 66,
  "shares": 20.00,
  "cost": 13.20,
  "newBalance": 88.20,
  "realizedPnl": 0.60
}

Trade Executor Pipeline

Every trade passes through a 12-step pipeline inside the Trade Executor:

1. Validate inputs - check required fields, side, outcome, positive amount.
2. Check market tradeability - blocked categories, disabled markets, price/liquidity criteria.
3. Risk assessment - 5 walls of defence (velocity, tier limits, exposure caps, sharp detection, operator limits).
4. Calculate spread-adjusted price - apply base spread + per-market overrides + per-user sharp adjustments.
5. Resolve operator - look up the user’s operator_id for multi-tenancy.
6. Get wallet adapter - resolve the S2S callback adapter for the user’s operator.
7. Check balance - verify sufficient funds via the adapter.
8. Debit/credit balance - execute the balance change via the wallet adapter.
9. Record trade - insert into casino_trades with full audit fields.
10. Upsert position - create or average into casino_positions (with optimistic concurrency).
11. Update exposure - recalculate casino_exposure (net exposure, max loss).
12. Update wagering stats - increment total_wagered on the user record (best-effort).

On failure after step 8, a compensating transaction reverses the balance change viaadapter.rollback().

Quote

Get a price quote for a potential trade without executing it. Quotes include the spread and are calculated synchronously against the default spread configuration. No authentication is required.

Query Parameters

Response (200 OK)

{
  "executionPrice": 64,
  "shares": 39.0625,
  "cost": 25.00,
  "spreadPct": 4,
  "payout": 39.06,
  "midPrice": 62
}

Balance

Get Balance

Returns the authenticated user’s current balance. The balance is resolved through the wallet adapter, which sends a BALANCE callback to the operator’s S2S server.

Query Parameters

Response (200 OK)

{
  "balance": 100.00,
  "ledger": null
}

When ledger=true is passed, the ledger field contains an array of the 50 most recent s2s_transactions entries (most recent first). When omitted or false,ledger is null.

// With ledger=true:
{
  "balance": 100.00,
  "ledger": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "amount": 25.00,
      "type": "trade_debit",
      "description": "Buy 39 shares YES @ 64c",
      "created_at": "2025-03-18T14:32:01.000Z"
    }
  ]
}

Admin Balance Adjustment

Admin-only endpoint to deposit or withdraw funds from a user’s balance. Used for promotional credits, refunds, and manual corrections. Requires admin role.

Request Body

{
  "targetUserId": "uuid-string",
  "amount": 50.00,
  "action": "deposit",
  "description": "Promotional welcome bonus"
}

Response (200 OK)

{
  "success": true,
  "newBalance": 150.00
}

Deposit

Deposit funds into the authenticated user’s account. This is the user-facing deposit endpoint (as opposed to the admin balance adjustment above). A maximum balance cap of $100,000 is enforced.

Request Body

{
  "amount": 100.00
}

Response (200 OK)

{
  "balance": 200.00
}

Withdraw

Withdraw funds from the authenticated user’s Predictu balance. A maximum withdrawal of $100,000 per request is enforced, and the user must have sufficient balance.

Request Body

{
  "amount": 50.00
}

Response (200 OK)

{
  "success": true,
  "newBalance": 150.00,
  "amount": 50.00
}

Positions

Returns all positions for the authenticated user, filtered by status. Results are ordered byupdated_at descending (most recently updated first).

Query Parameters

Response (200 OK)

{
  "positions": [
    {
      "id": "uuid-string",
      "user_id": "uuid-string",
      "market_id": "0x1234abcd...",
      "market_title": "Will Bitcoin hit $100k by June?",
      "outcome": "yes",
      "shares": 39.0625,
      "avg_price": 64,
      "status": "open",
      "realized_pnl": 0,
      "operator_id": "uuid-string",
      "created_at": "2025-03-18T14:32:01.000Z",
      "updated_at": "2025-03-18T15:00:00.000Z"
    }
  ]
}

Trades

Returns the authenticated user’s trade history, ordered by created_at descending (most recent first).

Query Parameters

Response (200 OK)

{
  "trades": [
    {
      "id": "uuid-string",
      "user_id": "uuid-string",
      "market_id": "0x1234abcd...",
      "market_title": "Will Bitcoin hit $100k by June?",
      "side": "buy",
      "outcome": "yes",
      "shares": 39.0625,
      "price_mid": 62,
      "price_executed": 64,
      "spread_applied": 2,
      "cost": 25.00,
      "balance_before": 100.00,
      "balance_after": 75.00,
      "operator_id": "uuid-string",
      "s2s_transaction_id": null,
      "created_at": "2025-03-18T14:32:01.000Z"
    }
  ]
}

Markets Configuration

Returns the casino’s market configuration: blocked categories, individually disabled markets, market selection criteria, and per-market custom spreads. This is not a market listing endpoint -markets are sourced from Polymarket and filtered client-side using these rules. No authentication is required.

Response (200 OK)

{
  "blockedCategories": ["adult", "drugs"],
  "disabledMarketIds": ["0xabc123...", "0xdef456..."],
  "criteria": {
    "min_liquidity": 5000,
    "min_price": 5,
    "max_price": 95
  },
  "customSpreads": {
    "0x1234abcd...": 6,
    "0x5678efgh...": 2.5
  }
}

Resolve Market

Admin-only endpoint to resolve or void a prediction market. Resolving triggers settlement: winning positions are credited $1 per share via the wallet adapter, losing positions are marked as resolved. Voiding refunds all positions at their original cost basis.

Request Body

// Resolve a market:
{
  "marketId": "0x1234abcd...",
  "outcome": "yes",
  "action": "resolve"
}

// Void a market:
{
  "marketId": "0x1234abcd...",
  "action": "void",
  "reason": "Resolution criteria became ambiguous"
}

Response (200 OK) - Resolve

{
  "success": true,
  "marketId": "0x1234abcd...",
  "outcome": "yes",
  "totalPositions": 142,
  "totalWinners": 89,
  "totalPayout": 4250.00,
  "casinoProfit": -1340.00
}

Response (200 OK) - Void

{
  "success": true,
  "marketId": "0x1234abcd...",
  "totalPositions": 142,
  "totalPayout": 3500.00,
  "casinoProfit": 0
}

When voiding, all positions are refunded at their original cost basis. casinoProfit is always 0 for voids. The totalPayout represents the total amount refunded.

Rate Limits

The Casino API enforces rate limits to prevent abuse and ensure fair access.

Rate limit headers are included in every response:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 18
X-RateLimit-Reset: 1710772321