API Reference

PredMarkets exposes two public REST surfaces, a WebSocket relay, and on-chain contracts. The current frontend still consumes the legacy /api/* routes, while external integrations should prefer /api/v1/*.

Base URLs

Public API: https://api.predmarkets.com/api
Versioned API: https://api.predmarkets.com/api/v1
WebSocket relay: wss://api.predmarkets.com/ws

The worker is rate-limited by environment-configured limits. In the default local configuration that is 600 requests per minute per IP.

Public Market Data

GET /api/clock

GET /api/markets

GET /api/markets/active

GET /api/markets/:asset/:duration/:epoch

GET /api/prices

GET /api/orderbook/:marketId?outcome=0|1

GET /api/trades/:marketId

Market payloads include timing fields, condition ids, current spot, oracle metadata, and the exchange address. The order book endpoint returns prices in cents and shares in decimal share units.

GET /api/orderbook/BTC-300-42?outcome=0

{
  "bids": [{ "price": 55, "shares": 12.5, "side": "buy" }],
  "asks": [{ "price": 57, "shares": 8.0, "side": "sell" }]
}

Orders

In the current centralized CLOB path, order submission is off-chain. Clients sign an EIP-712 order and post it to the worker. Market orders are represented as aggressive IOC orders; there is no separate public market-order API.

POST /api/orders

DELETE /api/orders/:orderHash

GET /api/orders/:address?status=open&limit=100

POST /api/orders
{
  "maker": "0x...",
  "conditionId": "0x...",
  "outcomeIndex": 0,
  "side": 0,
  "price": 560000,
  "shares": 12500000,
  "nonce": "123456789",
  "expiry": 0,
  "signature": "0x...",
  "ioc": false
}

Raw order values are 6-decimal fixed-point numbers: price is USDC per share, and shares is the share quantity. Side 0 is buy and 1 is sell.

{
  "orderHash": "0x...",
  "status": "filled",
  "fills": [
    { "shares": 12.5, "price": 0.56, "fee": 0.105 }
  ],
  "remainingShares": 0
}

Cancelling an order requires a wallet signature over the order hash and a timestamp. The worker rejects stale timestamps and mismatched makers.

Users, Positions, Rewards, and Chat

GET /api/positions/:address

GET /api/claimable/:address

GET /api/users/:address/stats

GET /api/users/:address/trades

GET /api/rewards/:address

GET /api/users/:address/profile

POST /api/users/register

GET /api/chat

POST /api/chat

Usernames are chat-only metadata. Registering a username requires a one-time wallet signature and returns a chat token. Posting to chat then uses Authorization: Bearer <chat_token>.

POST /api/users/register
{
  "address": "0x...",
  "username": "degen_whale",
  "signature": "0x..."
}

{
  "address": "0x...",
  "username": "degen_whale",
  "created_at": 1772854509,
  "chat_token": "eyJ..."
}

Versioned API

The /api/v1 surface wraps successful responses as { data, request_id } and errors as { error, request_id }. Trades, user trades, and orders are paginated with limit and cursor.

GET /api/v1/trades/:marketId?limit=100&cursor=...

GET /api/v1/orders/:address?status=open&limit=100&cursor=...

POST /api/v1/private/rewards/:address/claim

The private reward-claim endpoint is not wallet-authenticated from the browser. It uses worker API credentials with HMAC headers: x-api-key, x-signature, x-nonce, x-timestamp, plus an idempotency-key.

WebSocket Relay

The relay supports both legacy broadcasts used by the frontend and a channel-based protocol for bots.

Legacy server messages:
{ "type": "price_update", "asset": "BTC", "price": 67370.97, "timestamp": 1772870342 }
{ "type": "market_update", "market": { ... } }
{ "type": "trade", "trade": { ... } }
{ "type": "epoch_change", "asset": "BTC", "duration": 300, "newEpoch": 42 }
{ "type": "chat_message", "id": 1, "address": "0x...", "username": "degen_whale", "message": "yo", "created_at": 1772870400 }

Channel protocol:
{ "type": "subscribe", "channels": ["prices", "markets"], "from_seq": { "prices": 100 } }
{ "type": "unsubscribe", "channels": ["prices"] }
{ "type": "ping" }

Channel subscribers receive snapshot, event, and heartbeat messages with per-channel sequence numbers.

On-Chain Contracts

All contracts are deployed on Avalanche C-Chain (chain ID 43114). Collateral is Circle native USDC. Markets are resolved trustlessly via the PythResolver using Pyth Network price proofs. Signed orders are matched off-chain and settled through CTFSettlement.

For frontend integrations, the canonical addresses are exposed via environment variables and mirrored in market and clock responses. For low-level contract calls, refer to the ABIs in src/lib/contracts.ts.