### API Key Authentication Examples (Bash)

Source: https://docs.polybacktest.com/api-keys

Demonstrates how to authenticate API requests using either the 'Authorization: Bearer' header or the 'X-API-Key' header. These examples show the structure for making requests to different PolyBackTest API endpoints.

```bash
# Using Authorization header (recommended)
curl "https://api.polybacktest.com/v2/markets?coin=btc" \
  -H "Authorization: Bearer pdm_your_api_key_here"

# Or using X-API-Key header
curl "https://api.polybacktest.com/v2/spot/latest?coin=btc" \
  -H "X-API-Key: pdm_your_api_key_here"
```

--------------------------------

### GET /v2/spot/trades

Source: https://docs.polybacktest.com/fetching-data

Retrieves historical spot trade data for analysis using time-based filtering.

```APIDOC
## GET /v2/spot/trades

### Description
Fetch spot trade history for a given time window.

### Method
GET

### Endpoint
https://api.polybacktest.com/v2/spot/trades

### Parameters
#### Query Parameters
- **start_time** (integer) - Required - Start timestamp in millisecond epoch.
- **end_time** (integer) - Required - End timestamp in millisecond epoch.

### Request Example
curl "https://api.polybacktest.com/v2/spot/trades?start_time=1708992000000&end_time=1708995600000"

### Response
#### Success Response (200)
- **trades** (array) - List of trade records.

#### Response Example
{
  "trades": [
    { "id": "123", "price": 0.55, "amount": 100 }
  ]
}
```

--------------------------------

### Fetch Time-Series Data with cURL

Source: https://docs.polybacktest.com/fetching-data

Demonstrates how to query market snapshots and spot trades using time filters via HTTP GET requests. Supports both ISO8601 strings and millisecond epoch timestamps.

```bash
curl "https://api.polybacktest.com/v2/markets/1051520/snapshots?start_time=2026-01-01T00:00:00Z&end_time=2026-01-31T23:59:59Z"
```

```bash
curl "https://api.polybacktest.com/v2/spot/trades?start_time=1708992000000&end_time=1708995600000"
```

--------------------------------

### GET /v2/markets/{market_id}/snapshots

Source: https://docs.polybacktest.com/fetching-data

Retrieves market snapshots for a specific market within a defined time range. Supports time-series filtering and pagination.

```APIDOC
## GET /v2/markets/{market_id}/snapshots

### Description
Fetch historical snapshots for a specific market. Use this to analyze market states over time.

### Method
GET

### Endpoint
https://api.polybacktest.com/v2/markets/{market_id}/snapshots

### Parameters
#### Path Parameters
- **market_id** (string) - Required - The unique identifier for the market.

#### Query Parameters
- **start_time** (string|integer) - Optional - Return records created after this timestamp.
- **end_time** (string|integer) - Optional - Return records created before this timestamp.
- **limit** (integer) - Optional - Number of results to return (Max 1000).
- **offset** (integer) - Optional - Number of results to skip.
- **include_orderbook** (boolean) - Optional - Whether to include orderbook data (default: false).

### Request Example
curl "https://api.polybacktest.com/v2/markets/1051520/snapshots?start_time=2026-01-01T00:00:00Z&end_time=2026-01-31T23:59:59Z"

### Response
#### Success Response (200)
- **snapshots** (array) - List of market snapshot objects.

#### Response Example
{
  "snapshots": [
    { "timestamp": 1709006400000, "price": 0.52 }
  ]
}
```

--------------------------------

### Get Market By Slug

Source: https://docs.polybacktest.com/api-reference/endpoint/get-market-by-slug

Fetches a single market's data using its slug. Includes warnings about data collection start dates for specific cryptocurrencies.

```APIDOC
## GET /markets/{slug}

### Description
Retrieves details for a specific market using its unique slug identifier. This endpoint also provides warnings regarding the data collection start dates for certain cryptocurrencies.

### Method
GET

### Endpoint
/markets/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique human-readable identifier for the market.

#### Query Parameters
- **coin** (string) - Required - The cryptocurrency to query. Available values: `btc`, `eth`, `sol`.

### Request Example
```json
{
  "example": "GET /markets/bitcoin?coin=btc"
}
```

### Response
#### Success Response (200)
- **market_data** (object) - Contains detailed information about the market.
- **warnings** (array) - An array of warning objects related to data availability.

#### Response Example
```json
{
  "example": {
    "market_data": {
      "name": "Bitcoin",
      "symbol": "BTC",
      "slug": "bitcoin",
      "current_price": 50000.00,
      "market_cap": 1000000000000.00
    },
    "warnings": [
      {
        "message": "ETH data collection started on 2026-03-02. Full 31-day historical coverage for Ethereum is not yet available."
      },
      {
        "message": "SOL data collection started on 2026-03-15. Full 31-day historical coverage for Solana is not yet available."
      }
    ]
  }
}
```
```

--------------------------------

### GET /v2/markets

Source: https://docs.polybacktest.com/api-reference/endpoint/list-markets

Retrieves a paginated list of prediction markets. Markets are sorted by start time in descending order.

```APIDOC
## GET /v2/markets

### Description
List all markets with pagination. Returns markets sorted by start_time descending (newest first).

### Method
GET

### Endpoint
/v2/markets

### Parameters
#### Query Parameters
- **coin** (string) - Required - Cryptocurrency to query. Supported coins: btc, eth, sol.
- **limit** (integer) - Optional - Number of results to return. Defaults to 50, maximum 100.
- **offset** (integer) - Optional - Pagination offset. Defaults to 0.
- **market_type** (string) - Optional - Filter by market type (5m, 15m, 1hr, 4hr, 24hr).
- **resolved** (boolean) - Optional - Filter by resolution status.
- **start_time** (string) - Optional - Filter markets starting after this time (ms epoch or ISO8601).
- **end_time** (string) - Optional - Filter markets starting before this time (ms epoch or ISO8601).

### Request Example
```json
{
  "example": "GET /v2/markets?coin=eth&limit=10&offset=0&market_type=1hr"
}
```

### Response
#### Success Response (200)
- **markets** (array) - A list of market objects.
- **total** (integer) - The total number of markets available.
- **limit** (integer) - The limit applied to the current request.
- **offset** (integer) - The offset applied to the current request.

#### Response Example
```json
{
  "markets": [
    {
      "id": "market_id_1",
      "name": "Will ETH reach $5000 by EOY?",
      "start_time": "2023-10-26T10:00:00Z",
      "end_time": "2023-12-31T23:59:59Z",
      "resolved_time": null,
      "resolution": null,
      "probability": 0.75,
      "volume": 10000,
      "best_bid": 0.70,
      "best_ask": 0.80
    }
  ],
  "total": 150,
  "limit": 10,
  "offset": 0
}
```

#### Error Response (401)
- **detail** (string) - Error message describing what went wrong (e.g., 'Missing or invalid API key').

#### Error Response (422)
- **detail** (array) - An array of validation errors, each containing 'loc' (location) and 'msg' (message).

```

--------------------------------

### GET /v1/markets

Source: https://docs.polybacktest.com/api-reference/endpoint/v1-list-markets

List all markets with pagination. Returns markets sorted by start_time descending (newest first).

```APIDOC
## GET /v1/markets

### Description
List all markets with pagination. Returns markets sorted by start_time descending (newest first).

### Method
GET

### Endpoint
/v1/markets

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of results to return. Max: 100, Min: 1, Default: 50
- **offset** (integer) - Optional - Pagination offset. Min: 0, Default: 0
- **market_type** (string) - Optional - Filter by market type (5m, 15m, 1hr, 4hr, 24hr)
- **resolved** (boolean) - Optional - Filter by resolution status

### Request Example
```json
{
  "example": "No request body for GET request."
}
```

### Response
#### Success Response (200)
- **markets** (array) - List of markets.
- **total** (integer) - Total number of markets available.
- **limit** (integer) - The limit used for the pagination.
- **offset** (integer) - The offset used for the pagination.

#### Response Example
```json
{
  "markets": [
    {
      "id": "market_id_1",
      "name": "Example Market 1",
      "url": "https://example.com/market/1",
      "creator": "creator_address_1",
      "creation_time": "2023-10-27T10:00:00Z",
      "start_time": "2023-10-27T12:00:00Z",
      "end_time": "2023-10-27T18:00:00Z",
      "resolved_time": null,
      "outcome": null,
      "volume": 1000,
      "is_resolved": false,
      "is_valid": true,
      "market_type": "1hr"
    }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}
```

#### Error Response (401)
- **detail** (string) - Error message describing what went wrong.

#### Error Response Example (401)
```json
{
  "detail": "Missing or invalid API key"
}
```

#### Error Response (422)
- **detail** (array) - Details of the validation error.

#### Error Response Example (422)
```json
{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.max"
    }
  ]
}
```
```

--------------------------------

### GET /snapshots

Source: https://docs.polybacktest.com/api-reference/endpoint/v1-get-snapshots

Retrieves a paginated list of market snapshots containing price and order book data.

```APIDOC
## GET /snapshots

### Description
Retrieves a paginated list of market snapshots. Use this to track price movements and order book changes over time.

### Method
GET

### Endpoint
/snapshots

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of snapshots to return
- **offset** (integer) - Optional - Number of snapshots to skip

### Response
#### Success Response (200)
- **snapshots** (array) - List of Snapshot objects
- **total** (integer) - Total count of snapshots available

#### Response Example
{
  "snapshots": [],
  "total": 0,
  "limit": 10,
  "offset": 0
}
```

--------------------------------

### GET /v2/spot/snapshots

Source: https://docs.polybacktest.com/api-reference/endpoint/spot-orderbooks

Retrieves historical spot orderbook snapshots with support for pagination and time-based filtering.

```APIDOC
## GET /v2/spot/snapshots

### Description
Get historical spot orderbook snapshots with pagination. Timestamps accept millisecond epoch or ISO8601 format.

### Method
GET

### Endpoint
/v2/spot/snapshots

### Parameters
#### Query Parameters
- **coin** (string) - Required - Cryptocurrency to query (e.g., btc, eth).
- **start_time** (string) - Optional - Start timestamp (ms epoch or ISO8601).
- **end_time** (string) - Optional - End timestamp (ms epoch or ISO8601, default: now).
- **limit** (integer) - Optional - Results per page (1-1000, default: 100).
- **offset** (integer) - Optional - Pagination offset (default: 0).

### Request Example
GET /v2/spot/snapshots?coin=btc&limit=10

### Response
#### Success Response (200)
- **snapshots** (array) - List of snapshot objects.
- **total** (integer) - Total number of matching snapshots.
- **limit** (integer) - Results per page.
- **offset** (integer) - Current pagination offset.

#### Response Example
{
  "snapshots": [
    {
      "id": 1,
      "price": 50000.0,
      "bids": [],
      "asks": [],
      "timestamp": "2023-10-27T10:00:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
```

--------------------------------

### GET /v2/spot/latest

Source: https://docs.polybacktest.com/api-reference/endpoint/spot-latest

Retrieves the most recent spot orderbook snapshot for a specified cryptocurrency.

```APIDOC
## GET /v2/spot/latest

### Description
Returns the most recent spot orderbook snapshot for a given cryptocurrency. Note that data availability varies by coin (e.g., ETH and SOL have limited historical coverage).

### Method
GET

### Endpoint
https://api.polybacktest.com/v2/spot/latest

### Parameters
#### Query Parameters
- **coin** (string) - Required - Cryptocurrency to query. Available values: `btc`, `eth`, `sol`.

### Request Example
GET /v2/spot/latest?coin=btc

### Response
#### Success Response (200)
- **id** (integer) - Unique snapshot identifier
- **price** (number) - Current spot price
- **bids** (array) - List of current bids
- **asks** (array) - List of current asks
- **timestamp** (string) - Source timestamp from Binance (ISO8601)

#### Response Example
{
  "id": 12345,
  "price": 50000.00,
  "bids": [[49999.0, 1.5]],
  "asks": [[50001.0, 1.2]],
  "timestamp": "2026-03-20T10:00:00Z"
}
```

--------------------------------

### GET /v2/spot/latest

Source: https://docs.polybacktest.com/index

Retrieves the latest spot orderbook data for a specified cryptocurrency.

```APIDOC
## GET /v2/spot/latest

### Description
Fetch the latest spot orderbook data for the specified cryptocurrency.

### Method
GET

### Endpoint
https://api.polybacktest.com/v2/spot/latest

### Parameters
#### Query Parameters
- **coin** (string) - Required - The cryptocurrency symbol (e.g., btc, eth, sol).

### Request Example
curl "https://api.polybacktest.com/v2/spot/latest?coin=btc" \
  -H "Authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **bids** (array) - Current buy orders.
- **asks** (array) - Current sell orders.

#### Response Example
{
  "bids": [[94990, 1.2]],
  "asks": [[95010, 0.8]]
}
```

--------------------------------

### GET /markets/{market_id}/snapshots

Source: https://docs.polybacktest.com/api-reference/endpoint/get-snapshots

Retrieves a paginated list of snapshots for a specific market. Includes market details, total snapshots, and pagination information.

```APIDOC
## GET /markets/{market_id}/snapshots

### Description
Retrieves a paginated list of snapshots for a specific market. Includes market details, total snapshots, and pagination information.

### Method
GET

### Endpoint
/markets/{market_id}/snapshots

### Parameters
#### Path Parameters
- **market_id** (string) - Required - The unique identifier for the market.

#### Query Parameters
- **limit** (integer) - Optional - Number of results returned in this response. Defaults to 100.
- **offset** (integer) - Optional - Pagination offset used for this request. Defaults to 0.

### Request Example
```json
{
  "example": "GET /markets/some_market_id/snapshots?limit=10&offset=0"
}
```

### Response
#### Success Response (200)
- **market** (object) - Details of the market.
  - **market_id** (string) - Unique identifier for the market.
  - **event_id** (string) - Unique identifier for the event associated with the market.
  - **slug** (string) - URL-friendly identifier for the market.
  - **market_type** (string) - The type of market (e.g., 'BINARY', '।
  - **start_time** (string) - The start time of the market in ISO8601 format.
  - **end_time** (string) - The end time of the market in ISO8601 format.
  - **btc_price_start** (number | null) - The Bitcoin price at the start of the market.
  - **condition_id** (string | null) - The ID of the condition associated with the market.
  - **clob_token_up** (string | null) - The token for the UP side of the CLOB.
  - **clob_token_down** (string | null) - The token for the DOWN side of the CLOB.
  - **winner** (string | null) - The winning side of the market if resolved.
  - **final_volume** (number | null) - The final trading volume for the market.
  - **final_liquidity** (number | null) - The final liquidity for the market.
  - **btc_price_end** (number | null) - The Bitcoin price at the end of the market.
  - **resolved_at** (string | null) - The timestamp when the market was resolved in ISO8601 format.
  - **created_at** (string | null) - The timestamp when the market was created in ISO8601 format.
  - **updated_at** (string | null) - The timestamp when the market was last updated in ISO8601 format.
- **snapshots** (array) - A list of snapshot objects.
  - **id** (integer) - Unique snapshot identifier.
  - **time** (string) - Timestamp when the snapshot was captured (ISO8601).
  - **market_id** (string) - ID of the market this snapshot belongs to.
  - **btc_price** (number | null) - Bitcoin price at the time of snapshot (USD).
  - **price_up** (number | null) - Best price for the UP token (0-1 range).
  - **price_down** (number | null) - Best price for the DOWN token (0-1 range).
  - **orderbook_up** (object | null) - Full order book for the UP token.
  - **orderbook_down** (object | null) - Full order book for the DOWN token.
- **total** (integer) - Total number of snapshots available for this market.
- **limit** (integer) - Number of results returned in this response.
- **offset** (integer) - Pagination offset used for this request.

#### Response Example
```json
{
  "example": "{\n  \"market\": {\n    \"market_id\": \"some_market_id\",\n    \"event_id\": \"some_event_id\",\n    \"slug\": \"some-market-slug\",\n    \"market_type\": \"BINARY\",\n    \"start_time\": \"2023-10-27T10:00:00Z\",\n    \"end_time\": \"2023-10-27T12:00:00Z\",\n    \"btc_price_start\": 34000.50,\n    \"condition_id\": null,\n    \"clob_token_up\": \"UP_TOKEN_ID\",\n    \"clob_token_down\": \"DOWN_TOKEN_ID\",\n    \"winner\": null,\n    \"final_volume\": null,\n    \"final_liquidity\": null,\n    \"btc_price_end\": null,\n    \"resolved_at\": null,\n    \"created_at\": \"2023-10-26T09:00:00Z\",\n    \"updated_at\": \"2023-10-26T09:00:00Z\"\n  },\n  \"snapshots\": [\n    {\n      \"id\": 1,\n      \"time\": \"2023-10-27T10:05:00Z\",\n      \"market_id\": \"some_market_id\",\n      \"btc_price\": 34050.75,\n      \"price_up\": 0.60,\n      \"price_down\": 0.40,\n      \"orderbook_up\": {\n        \"bids\": [[0.60, 100], [0.59, 50]],\n        \"asks\": [[0.61, 120], [0.62, 60]]\n      },\n      \"orderbook_down\": {\n        \"bids\": [[0.40, 80], [0.39, 40]],\n        \"asks\": [[0.41, 90], [0.42, 55]]\n      }\n    }\n  ],\n  \"total\": 150,\n  \"limit\": 10,\n  \"offset\": 0\n}
```

#### Error Response (422)
- **detail** (array) - Details about the validation error.
  - **type** (string) - The type of validation error.
  - **loc** (array) - The location of the error in the request.
  - **msg** (string) - The error message.

#### Error Response Example
```json
{
  "example": "{\n  \"detail\": [\n    {\n      \"type\": \"missing\",\n      \"loc\": [\n        \"query\",\n        \"market_id\"\n      ],\n      \"msg\": \"Field required\"\n    }\n  ]\n}"
}
```
```

--------------------------------

### GET /market

Source: https://docs.polybacktest.com/api-reference/endpoint/get-market

Retrieves market details for a specific cryptocurrency based on the provided coin identifier.

```APIDOC
## GET /market

### Description
Get a single market by its ID to retrieve historical data and status information.

### Method
GET

### Endpoint
/market

### Parameters
#### Query Parameters
- **coin** (string) - Required - Cryptocurrency to query. Available values: `btc`, `eth`, `sol`.

### Request Example
GET /market?coin=btc

### Response
#### Success Response (200)
- **data** (object) - Market data object for the requested cryptocurrency.

#### Response Example
{
  "coin": "btc",
  "status": "active",
  "historical_coverage_days": 31
}
```

--------------------------------

### GET /v1/markets/{market_id}/snapshots

Source: https://docs.polybacktest.com/api-reference/endpoint/v1-get-snapshots

Retrieves a paginated list of snapshots for a specific prediction market, sorted by time in ascending order.

```APIDOC
## GET /v1/markets/{market_id}/snapshots

### Description
Get snapshots for a market with pagination. Returns snapshots sorted by time ascending (oldest first). Maximum limit is 1000 snapshots per request.

### Method
GET

### Endpoint
/v1/markets/{market_id}/snapshots

### Parameters
#### Path Parameters
- **market_id** (string) - Required - The unique identifier of the market.

#### Query Parameters
- **include_orderbook** (boolean) - Optional - Include full orderbook JSON in each snapshot. Default: false.
- **limit** (integer) - Optional - Number of results to return (max 1000, default 100).
- **offset** (integer) - Optional - Pagination offset (default 0).
- **start_time** (string/date-time) - Optional - Filter snapshots after this time (ISO8601).
- **end_time** (string/date-time) - Optional - Filter snapshots before this time (ISO8601).

### Request Example
GET /v1/markets/1051520/snapshots?limit=10&include_orderbook=false

### Response
#### Success Response (200)
- **market** (object) - Market details
- **snapshots** (array) - Array of market snapshots
- **total** (integer) - Total number of snapshots available
- **limit** (integer) - Number of results returned
- **offset** (integer) - Pagination offset used

#### Response Example
{
  "market": { "id": "1051520", "name": "Example Market" },
  "snapshots": [],
  "total": 500,
  "limit": 10,
  "offset": 0
}
```

--------------------------------

### GET /v1/snapshot

Source: https://docs.polybacktest.com/api-reference/endpoint/v1-get-snapshot-at

Retrieves the market snapshot closest to a specified timestamp, provided it falls within a 2-second window.

```APIDOC
## GET /v1/snapshot

### Description
Returns the snapshot closest to the given timestamp, but only if it's within ±2 seconds. Note that this is a legacy endpoint and will be discontinued soon.

### Method
GET

### Endpoint
/v1/snapshot

### Parameters
#### Query Parameters
- **timestamp** (integer) - Required - The target Unix timestamp to search for.

### Request Example
GET /v1/snapshot?timestamp=1672531200

### Response
#### Success Response (200)
- **data** (array) - An array containing 0 or 1 snapshot objects.

#### Response Example
[
  {
    "timestamp": 1672531200,
    "price": 16500.50
  }
]
```

--------------------------------

### GET /v1/markets/{market_id}/snapshot-at/{timestamp}

Source: https://docs.polybacktest.com/api-reference/endpoint/v1-get-snapshot-at

Retrieves the market snapshot closest to a specific timestamp, provided it falls within a ±2 second window.

```APIDOC
## GET /v1/markets/{market_id}/snapshot-at/{timestamp}

### Description
Get the closest snapshot to a specific timestamp. Returns the snapshot closest to the given timestamp, but only if it's within ±2 seconds. Returns 404 if no snapshot is found within that range.

### Method
GET

### Endpoint
/v1/markets/{market_id}/snapshot-at/{timestamp}

### Parameters
#### Path Parameters
- **market_id** (string) - Required - Market ID
- **timestamp** (string) - Required - Target timestamp (ISO8601)

### Request Example
GET /v1/markets/1051520/snapshot-at/2026-01-01T12:30:00Z

### Response
#### Success Response (200)
- **market** (object) - Market details
- **snapshots** (array) - Array containing 0 or 1 snapshot closest to the requested timestamp

#### Response Example
{
  "market": {
    "market_id": "1051520",
    "slug": "example-market"
  },
  "snapshots": []
}
```

--------------------------------

### Get Market Snapshots (v1 - Deprecated)

Source: https://docs.polybacktest.com/api-reference/endpoint/v1-get-snapshots

Retrieves historical market snapshots for a given market. This is a legacy endpoint and is recommended to migrate to v2.

```APIDOC
## GET /v1/markets/{market}/snapshots

### Description
Fetches historical market snapshots, sorted by time ascending. Supports pagination and an option to include order book data.

### Method
GET

### Endpoint
`/v1/markets/{market}/snapshots`

### Parameters
#### Path Parameters
- **market** (string) - Required - The market identifier (e.g., 'BTC-USD').

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of snapshots to return (default: 100, max: 1000).
- **offset** (integer) - Optional - The number of snapshots to skip for pagination.
- **include_orderbook** (boolean) - Optional - Whether to include full order book depth (default: false).
- **start_time** (string) - Optional - ISO 8601 timestamp to filter snapshots from the start.
- **end_time** (string) - Optional - ISO 8601 timestamp to filter snapshots until the end.

### Request Example
```json
{
  "example": "GET /v1/markets/BTC-USD/snapshots?limit=100&include_orderbook=true&start_time=2023-01-01T00:00:00Z"
}
```

### Response
#### Success Response (200)
- **snapshots** (array) - An array of snapshot objects.
  - **time** (string) - Timestamp of the snapshot.
  - **price_data** (object) - Price data including bid/ask for UP and DOWN tokens.
  - **orderbook** (object) - Full order book depth (only if `include_orderbook` is true).
  - **btc_price** (number) - Bitcoin price at the time of the snapshot.

#### Response Example
```json
{
  "example": {
    "snapshots": [
      {
        "time": "2023-01-01T00:00:00Z",
        "price_data": {
          "bid_up": 100.0,
          "ask_up": 101.0,
          "bid_down": 99.0,
          "ask_down": 98.0
        },
        "orderbook": {
          "bids": [...],
          "asks": [...] 
        },
        "btc_price": 16500.50
      }
    ]
  }
}
```
```

--------------------------------

### List All Markets

Source: https://docs.polybacktest.com/api-reference/endpoint/list-markets

Retrieves a list of all available prediction markets, sorted by start time in descending order. Supports filtering by cryptocurrency.

```APIDOC
## GET /markets

### Description
Lists all available prediction markets, sorted by start_time descending (newest first). Supports filtering by cryptocurrency.

### Method
GET

### Endpoint
/markets

### Parameters
#### Query Parameters
- **coin** (string) - Optional - Cryptocurrency to query. Available values: `btc`, `eth`, `sol`.

### Request Example
```json
{
  "example": "GET /markets?coin=btc"
}
```

### Response
#### Success Response (200)
- **markets** (array) - A list of market objects.
  - **id** (string) - The unique identifier for the market.
  - **name** (string) - The name of the market.
  - **start_time** (string) - The start time of the market in ISO 8601 format.
  - **end_time** (string) - The end time of the market in ISO 8601 format.
  - **resolution_time** (string) - The time the market was resolved in ISO 8601 format.
  - **status** (string) - The current status of the market (e.g., 'open', 'closed', 'resolved').
  - **coin** (string) - The cryptocurrency associated with the market.

#### Response Example
```json
{
  "example": "{\n  \"markets\": [\n    {\n      \"id\": \"market_123\",\n      \"name\": \"Will BTC reach $100,000 by December 2024?\",\n      \"start_time\": \"2024-01-01T00:00:00Z\",\n      \"end_time\": \"2024-12-31T23:59:59Z\",\n      \"resolution_time\": \"2025-01-01T00:00:00Z\",\n      \"status\": \"open\",\n      \"coin\": \"btc\"\n    }\n  ]\n}"
}
```

### Warnings
- **ETH data collection started on 2026-03-02.** Full 31-day historical coverage for Ethereum is not yet available.
- **SOL data collection started on 2026-03-15.** Full 31-day historical coverage for Solana is not yet available.

### Notes
Markets are sorted by start time in descending order, so you'll see the newest markets first.

### Info
- Learn how to query effectively using time filters and pagination limits in our [Fetching Data & Pagination](/fetching-data) guide.
- Check the [Available Data & Markets](/available-data) guide to see which market types are supported for each coin.
```

--------------------------------

### GET /v2/spot/trades

Source: https://docs.polybacktest.com/api-reference/endpoint/spot-trades

Retrieves historical spot aggregated trade data with pagination. Supports filtering by cryptocurrency, start and end times, and pagination limits.

```APIDOC
## GET /v2/spot/trades

### Description
Get historical spot aggregated trade data with pagination. Timestamps accept millisecond epoch or ISO8601 format.

Learn how to query effectively using time filters and pagination limits in our [Fetching Data & Pagination](/fetching-data) guide.

Check the [Available Data & Markets](/available-data) guide to see which market types are supported for each coin.

### Method
GET

### Endpoint
/v2/spot/trades

### Parameters
#### Query Parameters
- **coin** (string) - Required - Cryptocurrency to query. Supported coins include btc, eth. New coins added as they become available.
- **start_time** (string) - Optional - Start timestamp (ms epoch or ISO8601)
- **end_time** (string) - Optional - End timestamp (ms epoch or ISO8601, default: now)
- **limit** (integer) - Optional - Results per page (1-1000, default: 100)
- **offset** (integer) - Optional - Pagination offset (default: 0)

### Request Example
```json
{
  "coin": "btc",
  "start_time": "1678886400000",
  "end_time": "1678972800000",
  "limit": 100,
  "offset": 0
}
```

### Response
#### Success Response (200)
- **trades** (array) - List of trade objects.
- **total** (integer) - Total number of matching trades.
- **limit** (integer) - Results per page.
- **offset** (integer) - Current pagination offset.

#### Response Example
```json
{
  "trades": [
    {
      "id": 12345,
      "price_open": 25000.50,
      "price_high": 25100.75,
      "price_low": 24950.25,
      "price_close": 25050.00,
      "total_volume": 100.5,
      "aggressive_buy_volume": 50.2,
      "aggressive_sell_volume": 50.3,
      "num_trades": 1000,
      "timestamp": "2023-03-15T12:00:00Z"
    }
  ],
  "total": 5000,
  "limit": 100,
  "offset": 0
}
```

#### Error Response (422)
- **detail** (array) - Validation error details.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": ["query", "coin"],
      "msg": "value is not a valid enumeration member; permitted: 'btc', 'eth'",
      "type": "enum"
    }
  ]
}
```
```

--------------------------------

### Check API Limits and Plan Status

Source: https://docs.polybacktest.com/rate-limits

Demonstrates how to query the /v2/limits endpoint to retrieve current plan details, market access limits, and remaining rate limit quotas.

```bash
curl -X GET "https://api.polybacktest.com/v2/limits" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "plan": "free",
  "limits": {
    "5m_markets": 50,
    "15m_markets": 50,
    "1h_markets": 24,
    "4h_markets": 24,
    "24h_markets": 5,
    "snapshots": null
  },
  "rate_limit": {
    "max_per_second": 1,
    "remaining_per_second": 0,
    "max_per_minute": null,
    "remaining_per_minute": null
  }
}
```

```json
{
  "plan": "pro",
  "limits": {
    "5m_markets": null,
    "15m_markets": null,
    "1h_markets": null,
    "4h_markets": null,
    "24h_markets": null,
    "snapshots": null
  },
  "rate_limit": {
    "max_per_second": 10,
    "remaining_per_second": 9,
    "max_per_minute": 300,
    "remaining_per_minute": 299
  }
}
```

--------------------------------

### Retrieve Spot Orderbook Snapshots via OpenAPI

Source: https://docs.polybacktest.com/api-reference/endpoint/spot-orderbooks

This OpenAPI definition describes the GET /v2/spot/snapshots endpoint. It accepts query parameters for coin selection, time ranges, and pagination, returning a paginated list of market snapshots.

```yaml
paths:
  /v2/spot/snapshots:
    get:
      tags:
        - v2 - Spot
      summary: Get Spot Orderbook Snapshots
      operationId: get_spot_snapshots_v2_spot_snapshots_get
      parameters:
        - name: coin
          in: query
          required: true
          schema:
            type: string
        - name: start_time
          in: query
          required: false
          schema:
            type: string
        - name: end_time
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
```

--------------------------------

### Implement Pagination Loop in Python

Source: https://docs.polybacktest.com/fetching-data

A robust pattern for fetching large datasets by iterating through pages using limit and offset parameters. The loop terminates automatically when the returned dataset is smaller than the requested limit.

```python
import requests

market_id = "1051520"
base_url = f"https://api.polybacktest.com/v2/markets/{market_id}/snapshots"
headers = {"X-API-Key": "YOUR_API_KEY"}

limit = 1000
offset = 0
all_snapshots = []

while True:
    params = {
        "limit": limit,
        "offset": offset,
        "start_time": "2026-01-01T00:00:00Z" # Optional time filter
    }
    
    response = requests.get(base_url, headers=headers, params=params).json()
    snapshots = response.get("snapshots", [])
    
    if not snapshots:
        break # No more data
        
    all_snapshots.extend(snapshots)
    offset += limit
    
    # If we received fewer records than the limit, we've reached the end
    if len(snapshots) < limit:
        break

print(f"Total snapshots fetched: {len(all_snapshots)}")
```

--------------------------------

### Get Market Details

Source: https://polybacktest.com/

Retrieves detailed information about a specific market, including its ID, type, start and end times, initial and final prices, and the winner. This endpoint is crucial for understanding the outcome and parameters of a past market.

```HTTP
HTTP/1.1 200 OK application/json

polybacktest@api ~/v1/markets/{market_id} ● CONNECTED

[200 OK] Response received in 42ms

btc-updown-15m-1770138000 UP/DOWN
market_id 1320593
event_id 196799
market_type 15m
btc_price_start $76,488.08
winner DOWN ↓
final_volume 534,123.95
start_time 2026-02-04T01:00:00Z
end_time 2026-02-04T01:15:00Z

{
  "market_id": "1320593",
  "event_id": "196799",
  "slug": "btc-updown-15m-1770138000",
  "market_type": "15m",
  "start_time": "2026-02-04T01:00:00Z",
  "end_time": "2026-02-04T01:15:00Z",
  "btc_price_start": 76488.08,
  "btc_price_end": 76412.55,
  "winner": "Down",
  "final_volume": 534123.95,
  "final_liquidity": 12847.32,
  "resolved_at": "2026-02-04T01:15:00Z"
}
```

--------------------------------

### GET /v2/markets

Source: https://docs.polybacktest.com/index

Retrieves the latest prediction markets for a specified cryptocurrency.

```APIDOC
## GET /v2/markets

### Description
Fetch the latest prediction markets for a specific coin, filtered by market type and result limit.

### Method
GET

### Endpoint
https://api.polybacktest.com/v2/markets

### Parameters
#### Query Parameters
- **coin** (string) - Required - The cryptocurrency symbol (e.g., btc, eth, sol).
- **market_type** (string) - Required - The timeframe or type of market (e.g., 5m).
- **limit** (integer) - Optional - Number of records to return.

### Request Example
curl "https://api.polybacktest.com/v2/markets?coin=btc&market_type=5m&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (array) - List of prediction market objects.

#### Response Example
{
  "data": [
    { "id": "market_1", "price": 95000.50, "type": "5m" }
  ]
}
```

--------------------------------

### Authentication

Source: https://docs.polybacktest.com/api-reference/endpoint/futures-trades

Details on how to authenticate requests using the API Key header.

```APIDOC
## Authentication

### Method
Header Authentication

### Header
- **X-API-Key** (string) - Required - API key for authentication. Include this header in all requests to authenticated endpoints.
```

--------------------------------

### Authentication

Source: https://docs.polybacktest.com/api-reference/endpoint/futures-orderbooks

Details on how to authenticate requests using the API Key header.

```APIDOC
## Authentication

### Description
All authenticated endpoints require an API key to be passed in the request header.

### Security Scheme
- **Type**: apiKey
- **In**: header
- **Name**: X-API-Key
- **Description**: API key for authentication. Include this header in all requests to authenticated endpoints.
```

--------------------------------

### GET /v2/futures/latest

Source: https://docs.polybacktest.com/api-reference/endpoint/futures-latest

Retrieves the most recent futures orderbook snapshot for a specified cryptocurrency.

```APIDOC
## GET /v2/futures/latest

### Description
Returns the most recent futures orderbook snapshot. This endpoint provides real-time market data for backtesting and analysis.

### Method
GET

### Endpoint
https://api.polybacktest.com/v2/futures/latest

### Parameters
#### Query Parameters
- **coin** (string) - Required - Cryptocurrency to query. Available values: `btc`, `eth`, `sol`.

### Request Example
GET /v2/futures/latest?coin=btc

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the snapshot
- **price** (number) - Current market price
- **bids** (array) - List of current bid orders
- **asks** (array) - List of current ask orders
- **timestamp** (string) - Source timestamp from Binance (ISO8601)

#### Response Example
{
  "id": 12345,
  "price": 50000.0,
  "bids": [[49990.0, 1.5]],
  "asks": [[50010.0, 1.2]],
  "timestamp": "2026-03-20T10:00:00Z"
}
```

--------------------------------

### Stream Market Snapshots

Source: https://polybacktest.com/

Fetches real-time or historical price snapshots for a given market. This data includes timestamps, BTC prices, and the distribution of price up/down probabilities at each snapshot. It's essential for analyzing price movements over time.

```JSON
{
  "market": { "market_id": "1320593", "market_type": "15m" },
  "snapshots": [
    {
      "id": 94827351,
      "time": "2026-02-04T01:00:03Z",
      "btc_price": 76488.08,
      "price_up": 0.51,
      "price_down": 0.49
    },
    {
      "id": 94827389,
      "time": "2026-02-04T01:05:02Z",
      "btc_price": 76455.22,
      "price_up": 0.45,
      "price_down": 0.55
    }
  ],
  "total": 180,
  "limit": 100,
  "offset": 0
}
```