Backend Public API Reference

This page covers public backend endpoints with parameters and example responses.

1) Health

`GET /health`

Service health probe.

Example response:

{
  "status": "healthy",
  "timestamp": "2026-02-20T16:00:00.000Z",
  "services": {
    "database": true,
    "rabbitmq": true,
    "settlement": true
  }
}

2) Markets

`GET /api/markets`

List markets with filters and pagination.

Query parameters:

Name	Type	Description
`limit`	string/int	page size (default `20`)
`offset`	string/int	pagination offset (default `0`)
`sortBy`	string	`volume`, `newest`, `ending_soon`
`statusFilter`	string	`all`, `active`, `expired`, `resolved`
`timeFilter`	string	`all`, `24h`, `4h`, `1h`, `30m`, `15m`, `5m`, `week`, `month`
`tokenId`	string/int	optional token filter

Example request:

curl "https://api.speculite.com/api/markets?limit=20&offset=0&statusFilter=active&sortBy=volume"

Example response (truncated):

{
  "success": true,
  "markets": [
    {
      "market_id": "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
      "title": "Will BTC close above $100k this week?",
      "status": "ACTIVE",
      "exchange_address": "0x...",
      "expiration_timestamp": "2026-02-24T21:00:00.000Z",
      "taker_fee_bps": 80,
      "probability": 0.6123,
      "volume": 18422.91
    }
  ],
  "pagination": {
    "total": 84,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

`GET /api/markets/:id`

Fetch one market by UUID or exchange address.

Example request:

curl "https://api.speculite.com/api/markets/5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28"

Example response (truncated):

{
  "success": true,
  "market": {
    "market_id": "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
    "market_name": "BTC_WEEKLY_CLOSE",
    "title": "Will BTC close above $100k this week?",
    "question": "Will BTC/USD close above 100000 at expiry?",
    "status": "ACTIVE",
    "probability": 0.6123,
    "volume": 18422.91,
    "expiration_timestamp": "2026-02-24T21:00:00.000Z"
  }
}

`GET /api/markets/:id/history`

Probability time-series for a market.

Query parameters:

Name	Type	Description
`interval`	string	`1h`, `24h`, `7d`, `30d`, `all`

Example request:

curl "https://api.speculite.com/api/markets/5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28/history?interval=24h"

Example response:

{
  "success": true,
  "market_id": "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
  "history": [
    {
      "time": "2026-02-20T10:00:00.000Z",
      "midpoint_price": 0.605,
      "best_bid": 0.6,
      "best_ask": 0.61,
      "spread": 0.01,
      "probability": 0.605
    }
  ]
}

`GET /api/markets/:id/holders`

Holder leaderboard by outcome.

Query parameters:

Name	Type	Required	Description
`type`	string	yes	`YES` or `NO`
`limit`	string/int	no	default `20`
`offset`	string/int	no	default `0`

Example request:

curl "https://api.speculite.com/api/markets/5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28/holders?type=YES&limit=10"

Example response:

{
  "success": true,
  "market_id": "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
  "type": "YES",
  "holders": [
    {
      "username": "alice",
      "wallet_address": "0xabc...",
      "quantity": 1250,
      "average_entry_price": 0.58
    }
  ],
  "pagination": {
    "total": 31,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

`GET /api/markets/:id/comments`

Top-level comments with one-level replies.

Query parameters:

Name	Type	Description
`limit`	string/int	default `20`, max `50`
`offset`	string/int	default `0`

Example request:

curl "https://api.speculite.com/api/markets/5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28/comments?limit=20&offset=0"

Example response (truncated):

{
  "success": true,
  "market_id": "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
  "comments": [
    {
      "comment_id": "0a45...",
      "depth": 0,
      "content": "Interesting setup into expiry.",
      "like_count": 3,
      "liked_by_me": false,
      "author": {
        "user_id": "...",
        "username": "trader1",
        "wallet_address": "0x..."
      },
      "replies": [
        {
          "comment_id": "5ff1...",
          "depth": 1,
          "content": "Agreed, spread tightened a lot.",
          "like_count": 1,
          "liked_by_me": false,
          "author": {
            "user_id": "...",
            "username": "maker42",
            "wallet_address": "0x..."
          }
        }
      ]
    }
  ],
  "pagination": {
    "total": 14,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

`GET /api/markets/:id/activity`

Recent market activity feed.

Query parameters:

Name	Type	Description
`limit`	string/int	default `20`, max `100`
`offset`	string/int	default `0`

Example request:

curl "https://api.speculite.com/api/markets/5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28/activity?limit=20"

Example response:

{
  "success": true,
  "market_id": "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
  "activity": [
    {
      "activity_id": "...",
      "activity_type": "TRADE",
      "price": "0.61",
      "size": "150",
      "total_value": "91.5",
      "activity_timestamp": "2026-02-20T15:22:14.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

`GET /api/markets/probabilities`

Batch current probabilities by market.

Example request:

curl "https://api.speculite.com/api/markets/probabilities"

Example response:

{
  "success": true,
  "probabilities": {
    "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28": {
      "midpoint": 0.6123,
      "best_bid": 0.61,
      "best_ask": 0.615,
      "last_trade_price": 0.612,
      "timestamp": "2026-02-20T15:23:00.000Z"
    }
  }
}

3) Search and Tokens

`GET /api/search?q=<query>`

Global search across markets, users, and tokens.

Example request:

curl "https://api.speculite.com/api/search?q=btc"

Example response:

{
  "success": true,
  "results": {
    "markets": [
      {
        "market_id": "...",
        "title": "Will BTC close above $100k this week?",
        "status": "ACTIVE"
      }
    ],
    "users": [
      {
        "user_id": "...",
        "username": "btc_bull",
        "wallet_address": "0x..."
      }
    ],
    "tokens": [
      {
        "id": 1,
        "symbol": "BTC",
        "name": "Bitcoin",
        "asset_type": "CRYPTO"
      }
    ]
  }
}

`GET /api/tokens?query=<query>`

Token search.

Example request:

curl "https://api.speculite.com/api/tokens?query=tesla"

Example response:

{
  "success": true,
  "tokens": [
    {
      "id": 12,
      "pyth_feed_id": "0x...",
      "symbol": "TSLA",
      "name": "Tesla",
      "asset_type": "STOCK"
    }
  ]
}

`GET /api/tokens/:id`

Get token metadata by ID.

Example request:

curl "https://api.speculite.com/api/tokens/12"

Example response:

{
  "success": true,
  "token": {
    "id": 12,
    "pyth_feed_id": "0x...",
    "symbol": "TSLA",
    "name": "Tesla",
    "asset_type": "STOCK",
    "logo_url": "https://...",
    "country": "US",
    "sector": "Consumer Cyclical"
  }
}

`GET /api/tokens/price/:feedId`

Fetch latest parsed price from Pyth feed ID.

Example request:

curl "https://api.speculite.com/api/tokens/price/0xef0d8b6fda2ceba41..."

Example response:

{
  "success": true,
  "feed_id": "0xef0d8b6fda2ceba41...",
  "price": 102345.12,
  "raw_price": "10234512",
  "expo": -2,
  "publish_time": 1766234567
}

4) Public User Profiles

`GET /api/users/:username`

Public identity data.

Example response:

{
  "success": true,
  "user": {
    "user_id": "...",
    "username": "alice",
    "wallet_address": "0x...",
    "created_at": "2026-01-04T18:22:00.000Z"
  }
}

`GET /api/users/:username/profile`

Full public profile bundle.

Query parameters:

Name	Type	Description
`include_closed`	string/bool	include closed positions

Example request:

curl "https://api.speculite.com/api/users/alice/profile?include_closed=1"

Example response (truncated):

{
  "success": true,
  "user": {
    "user_id": "...",
    "username": "alice",
    "wallet_address": "0x...",
    "created_at": "2026-01-04T18:22:00.000Z"
  },
  "stats": {
    "markets_traded": 42,
    "win_rate": "56.12"
  },
  "positions": [],
  "activities": []
}

`GET /api/users/:username/stats`

Public stats only.

Example request:

curl "https://api.speculite.com/api/users/alice/stats"

Example response:

{
  "success": true,
  "stats": {
    "total_volume_usd": "18442.12",
    "markets_traded": 42,
    "positions_count": 7,
    "win_rate": "56.12"
  }
}

`GET /api/users/:username/positions`

Public positions.

Query parameters:

Name	Type	Description
`include_closed`	string/bool	include closed positions

Example request:

curl "https://api.speculite.com/api/users/alice/positions?include_closed=1"

Example response:

{
  "success": true,
  "total_value_usd": "1240.18",
  "positions": [
    {
      "market_id": "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
      "market_title": "Will BTC close above $100k this week?",
      "outcome": "YES",
      "quantity": "125.00",
      "avg_price": "0.58",
      "current_value": "76.25"
    }
  ]
}

`GET /api/users/:username/activity`

Public activity feed.

Example request:

curl "https://api.speculite.com/api/users/alice/activity"

Example response:

{
  "success": true,
  "activities": [
    {
      "activity_id": "...",
      "activity_type": "TRADE",
      "market_id": "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
      "market_title": "Will BTC close above $100k this week?",
      "side": "BUY",
      "price": "0.61",
      "size": "50",
      "activity_timestamp": "2026-02-20T15:22:14.000Z"
    }
  ]
}

`GET /api/users/:username/net-worth-history`

Public net worth time series.

Query parameters:

Name	Type	Description
`days`	string/int	default `30`, max `365`

Example response (truncated):

{
  "success": true,
  "data": [
    {
      "timestamp": "2026-02-19T00:00:00.000Z",
      "total_value": "1240.18",
      "unrealized_pnl": "83.20",
      "realized_pnl": "11.50",
      "change_percentage": "1.92",
      "position_count": 7
    }
  ],
  "summary": {
    "current_value": "1240.18",
    "start_value": "1185.11",
    "change_value": "55.07",
    "change_percentage": "4.65",
    "highest_value": "1261.44",
    "lowest_value": "1162.93"
  }
}

5) Rewards (Public Metadata)

`GET /api/rewards/program`

Example response:

{
  "success": true,
  "program": {
    "maker_rebate_share_bps": 2000,
    "fee_equivalent_k": 0.25,
    "creator_share_of_taker_fee_bps": 5000
  }
}

`GET /api/rewards/leaderboard`

Query parameters:

Name	Type	Description
`limit`	string/int	default `25`
`from`	string/date	optional start date
`to`	string/date	optional end date

Example response:

{
  "success": true,
  "leaderboard": [
    {
      "user_id": "...",
      "username": "maker_one",
      "fee_equivalent": "412.8842",
      "estimated_rebate_usdc": "89.42"
    }
  ]
}

`GET /api/rewards/epochs`

Query parameters:

Name	Type	Description
`limit`	string/int	default `30`
`status`	string	`OPEN`, `FINALIZED`, `PAID`

Example response:

{
  "success": true,
  "epochs": [
    {
      "epoch_id": "...",
      "epoch_label": "2026-02-19",
      "status": "FINALIZED",
      "reward_type": "MAKER_REBATE"
    }
  ]
}

6) Market Data Proxy

`GET /api/market-data/:marketId`

Example request:

curl "https://api.speculite.com/api/market-data/5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28"

Example response:

{
  "market_id": "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
  "midpoint_price": "0.61250000",
  "best_bid": "0.61000000",
  "best_ask": "0.61500000",
  "spread": "0.00500000",
  "timestamp": "2026-02-20T15:36:00.000Z"
}

`POST /api/market-data/batch`

Request body:

{
  "market_ids": [
    "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
    "f2ea64ee-95af-4b13-adf4-c8b6190c7e8b"
  ]
}

Example response:

{
  "success": true,
  "data": [
    {
      "market_id": "5f2d8f5d-86b2-4ca8-a451-4b7b4669ed28",
      "midpoint_price": "0.61250000",
      "best_bid": "0.61000000",
      "best_ask": "0.61500000",
      "spread": "0.00500000",
      "timestamp": "2026-02-20T15:36:00.000Z"
    }
  ]
}

1) Health​

GET /health​

2) Markets​

GET /api/markets​

GET /api/markets/:id​

GET /api/markets/:id/history​

GET /api/markets/:id/holders​

GET /api/markets/:id/comments​

GET /api/markets/:id/activity​

GET /api/markets/probabilities​

3) Search and Tokens​

GET /api/search?q=<query>​

GET /api/tokens?query=<query>​

GET /api/tokens/:id​

GET /api/tokens/price/:feedId​

4) Public User Profiles​

GET /api/users/:username​

GET /api/users/:username/profile​

GET /api/users/:username/stats​

GET /api/users/:username/positions​

GET /api/users/:username/activity​

GET /api/users/:username/net-worth-history​

5) Rewards (Public Metadata)​

GET /api/rewards/program​

GET /api/rewards/leaderboard​

GET /api/rewards/epochs​

6) Market Data Proxy​

GET /api/market-data/:marketId​

POST /api/market-data/batch​

1) Health

`GET /health`

2) Markets

`GET /api/markets`

`GET /api/markets/:id`

`GET /api/markets/:id/history`

`GET /api/markets/:id/holders`

`GET /api/markets/:id/comments`

`GET /api/markets/:id/activity`

`GET /api/markets/probabilities`

3) Search and Tokens

`GET /api/search?q=<query>`

`GET /api/tokens?query=<query>`

`GET /api/tokens/:id`

`GET /api/tokens/price/:feedId`

4) Public User Profiles

`GET /api/users/:username`

`GET /api/users/:username/profile`

`GET /api/users/:username/stats`

`GET /api/users/:username/positions`

`GET /api/users/:username/activity`

`GET /api/users/:username/net-worth-history`

5) Rewards (Public Metadata)

`GET /api/rewards/program`

`GET /api/rewards/leaderboard`

`GET /api/rewards/epochs`

6) Market Data Proxy

`GET /api/market-data/:marketId`

`POST /api/market-data/batch`