# Markets

Retrieve market listings, statistics, top holders, and activity.

## List Markets

Returns all active markets, optionally filtered by chain.

GET /api/v1/markets

### Query Parameters

| Parameter  | Type    | Required | Description                                  |
| ---------- | ------- | -------- | -------------------------------------------- |
| `chain_id` | integer | No       | Filter by chain ID (e.g., `137` for Polygon) |

### Response

```json
{
  "markets": [
    {
      "id": "0x1234...abcd",
      "question": "Will ETH reach $5000 by March 2025?",
      "description": "Resolves YES if...",
      "category": "defi",
      "contractAddress": "0xMarketContract...",
      "maker": "0xMakerAddress...",
      "expiration": 1735689600,
      "chainId": 137,
      "resolved": false,
      "bestAskPrice": 450000,
      "createdAt": 1735600000
    }
  ],
  "count": 1
}
```

| Field             | Type    | Description                                             |
| ----------------- | ------- | ------------------------------------------------------- |
| `id`              | bytes32 | Market identifier                                       |
| `question`        | string  | Market question                                         |
| `description`     | string  | Market description                                      |
| `category`        | string  | Category: `defi`, `protocol`, `stablecoin`, `general`   |
| `contractAddress` | address | On-chain market contract                                |
| `maker`           | address | Market creator address                                  |
| `expiration`      | uint64  | Unix timestamp when market expires                      |
| `chainId`         | integer | Blockchain chain ID                                     |
| `resolved`        | bool    | Whether the market has been resolved                    |
| `bestAskPrice`    | uint64  | Best YES ask price from the live orderbook (6 decimals) |

### Example

```bash
# All markets
curl "https://api.turbinefi.com/api/v1/markets"

# Polygon markets only
curl "https://api.turbinefi.com/api/v1/markets?chain_id=137"
```

***

## Get Market Statistics

Returns volume and price statistics for a market.

GET /api/v1/stats/{marketId}

### Path Parameters

| Parameter  | Type    | Description       |
| ---------- | ------- | ----------------- |
| `marketId` | bytes32 | Market identifier |

### Response

```json
{
  "marketId": "0x1234...abcd",
  "contractAddress": "0xMarketContract...",
  "volume24h": 50000000000,
  "totalVolume": 250000000000,
  "lastPrice": 550000
}
```

| Field             | Type   | Description                                                          |
| ----------------- | ------ | -------------------------------------------------------------------- |
| `marketId`        | string | Market identifier                                                    |
| `contractAddress` | string | Market contract address                                              |
| `volume24h`       | uint64 | 24-hour trading volume in USDC (6 decimals). `50000000000` = $50,000 |
| `totalVolume`     | uint64 | All-time trading volume in USDC (6 decimals)                         |
| `lastPrice`       | uint64 | Last trade price (6 decimals). `550000` = $0.55                      |

### Example

```bash
curl "https://api.turbinefi.com/api/v1/stats/0x1234...abcd"
```

***

## Get Top Holders

Returns the top position holders for a market.

GET /api/v1/holders/{marketId}

### Path Parameters

| Parameter  | Type    | Description       |
| ---------- | ------- | ----------------- |
| `marketId` | bytes32 | Market identifier |

### Response

```json
{
  "marketId": "0x1234...abcd",
  "topHolders": [
    {
      "userAddress": "0xUser1...",
      "yesShares": 50000000,
      "noShares": 0
    }
  ],
  "totalHolders": 42
}
```

| Field          | Type    | Description                            |
| -------------- | ------- | -------------------------------------- |
| `topHolders`   | array   | Top 10 holders sorted by position size |
| `totalHolders` | integer | Total number of unique holders         |

### Example

```bash
curl "https://api.turbinefi.com/api/v1/holders/0x1234...abcd"
```

***

## Get Market Activity

Returns recent trade activity for a market.

GET /api/v1/activity/{marketId}

### Path Parameters

| Parameter  | Type    | Description       |
| ---------- | ------- | ----------------- |
| `marketId` | bytes32 | Market identifier |

### Response

```json
{
  "marketId": "0x1234...abcd",
  "activity": [
    {
      "price": 550000,
      "size": 10000000,
      "buyer": "0xBuyer...",
      "seller": "0xSeller...",
      "timestamp": 1735689000,
      "txHash": "0xTxHash..."
    }
  ]
}
```

Returns the 50 most recent trades for the market.

### Example

```bash
curl "https://api.turbinefi.com/api/v1/activity/0x1234...abcd"
```

***

## Get Platform Statistics

Returns platform-wide volume and trade statistics across all markets.

GET /api/v1/platform/stats

### Query Parameters

| Parameter  | Type    | Required | Description                                                   |
| ---------- | ------- | -------- | ------------------------------------------------------------- |
| `chain_id` | integer | No       | Filter by chain ID. If omitted, returns stats for all chains. |

### Response (All Chains)

```json
{
  "chains": [
    {
      "chainId": 137,
      "totalVolume": 500000000000,
      "totalTrades": 12500
    }
  ],
  "total_volume": 500000000000,
  "total_trades": 12500
}
```

### Response (Single Chain)

```json
{
  "chainId": 137,
  "totalVolume": 500000000000,
  "totalTrades": 12500
}
```

### Example

```bash
# All chains
curl "https://api.turbinefi.com/api/v1/platform/stats"

# Polygon only
curl "https://api.turbinefi.com/api/v1/platform/stats?chain_id=137"
```