> ## Documentation Index
> Fetch the complete documentation index at: https://docs.luckylobster.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Markets

> Search and get market data

## Search Markets

<ParamField query="GET" path="/markets/search">
  Search for prediction markets by keyword, tag, or slug.
</ParamField>

### Parameters

| Name               | Type   | Default | Description                                       |
| ------------------ | ------ | ------- | ------------------------------------------------- |
| `q`                | string | -       | Search query                                      |
| `slug`             | string | -       | Exact market slug match                           |
| `tag`              | string | -       | Category: crypto, politics, sports, entertainment |
| `limit`            | int    | 10      | Max results (max: 100)                            |
| `offset`           | int    | 0       | Pagination offset                                 |
| `sort`             | string | volume  | volume, liquidity, end\_date, recent              |
| `min_volume`       | int    | 100     | Minimum volume in USD                             |
| `accepting_orders` | bool   | true    | Only tradeable markets                            |
| `ending_soon`      | bool   | false   | Prioritize markets ending within 24h              |

### Example

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/markets/search?q=bitcoin&sort=volume" \
  -H "Authorization: Bearer ll_..."
```

```json Response theme={null}
{
  "success": true,
  "data": [
    {
      "id": "1314069",
      "slug": "bitcoin-up-or-down-on-february-3",
      "question": "Bitcoin Up or Down on February 3?",
      "outcomes": ["Up", "Down"],
      "outcomePrices": ["0.65", "0.35"],
      "volume": "409100.65",
      "liquidity": "39255.13",
      "acceptingOrders": true
    }
  ],
  "context": {
    "topMatch": { "id": "1314069", "question": "..." }
  }
}
```

***

## Get Market Details

<ParamField query="GET" path="/markets/{id}">
  Get detailed information about a specific market including token IDs for trading.
</ParamField>

### Example

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/markets/1314069" \
  -H "Authorization: Bearer ll_..."
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "id": "1314069",
    "conditionId": "0xf46bf33576e8341821161316705ab2357312f58d58b7d157cb8dca73b656b326",
    "question": "Bitcoin Up or Down on February 3?",
    "tokens": [
      {"tokenId": "36656454529662513...", "outcome": "Up", "price": "0.345"},
      {"tokenId": "10609233133841503...", "outcome": "Down", "price": "0.655"}
    ],
    "clobTokenIds": ["36656454529662513...", "10609233133841503..."],
    "spreads": [
      {"outcome": "Up", "bid": "0.34", "ask": "0.35", "spread": "0.01"}
    ]
  }
}
```

***

## Crypto Markets

<ParamField query="GET" path="/markets/crypto">
  Find active crypto up/down markets using deterministic slug-based lookups. This is the most reliable way to find recurring crypto markets - it uses the same approach as the internal market-data-worker.
</ParamField>

### Parameters

| Name             | Type   | Default | Description                                                                   |
| ---------------- | ------ | ------- | ----------------------------------------------------------------------------- |
| `asset`          | string | -       | **Required.** btc, eth, sol, xrp, doge, matic (long-form names also accepted) |
| `timeframe`      | string | daily   | 5m, 15m, 4h, hourly, daily                                                    |
| `include_tokens` | bool   | true    | Include clobTokenIds and live spread data                                     |

### Example

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/markets/crypto?asset=btc&timeframe=15m" \
  -H "Authorization: Bearer ll_..."
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "conditionId": "0xabc...",
    "slug": "btc-updown-15m-1770129900",
    "question": "BTC Up or Down 9:45AM-10:00AM ET?",
    "outcomes": ["Up", "Down"],
    "outcomePrices": ["0.50", "0.50"],
    "endDate": "2026-02-13T15:00:00Z",
    "acceptingOrders": true,
    "negRisk": false,
    "clobTokenIds": ["366564...", "106092..."],
    "tokens": [
      {"tokenId": "366564...", "outcome": "Up", "price": "0.50", "bid": "0.49", "ask": "0.51"},
      {"tokenId": "106092...", "outcome": "Down", "price": "0.50", "bid": "0.49", "ask": "0.51"}
    ]
  },
  "meta": {
    "asset": "Bitcoin",
    "timeframe": "15m",
    "searchMethod": "slug"
  }
}
```

<Tip>
  This endpoint generates deterministic Polymarket slugs for the current time window and fetches them directly - no fuzzy text search. It checks the current window plus the next 2 windows to find the one accepting orders.
</Tip>

***

## Find by Slug

<ParamField query="GET" path="/markets/by-slug">
  Find a market by its exact Polymarket URL slug.
</ParamField>

### Example

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/markets/by-slug?slug=btc-updown-15m-1770129900" \
  -H "Authorization: Bearer ll_..."
```

***

## Order Book

<ParamField query="GET" path="/orderbook">
  Get the full order book for a token.
</ParamField>

### Parameters

| Name        | Type   | Description                        |
| ----------- | ------ | ---------------------------------- |
| `token_id`  | string | Token ID (required)                |
| `token_ids` | string | Comma-separated for batch (max 20) |

### Example

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/orderbook?token_id=36656454529662513..." \
  -H "Authorization: Bearer ll_..."
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "tokenId": "36656454529662513...",
    "bids": [
      {"price": "0.65", "size": "1000"},
      {"price": "0.64", "size": "500"}
    ],
    "asks": [
      {"price": "0.66", "size": "800"}
    ],
    "summary": {
      "bestBid": "0.65",
      "bestAsk": "0.66",
      "spread": "0.01"
    }
  }
}
```

***

## Prices

<ParamField query="GET" path="/prices">
  Get current prices for tokens.
</ParamField>

### Parameters

| Name        | Type   | Description               |
| ----------- | ------ | ------------------------- |
| `token_id`  | string | Token ID (required)       |
| `token_ids` | string | Comma-separated for batch |

### Example

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/prices?token_id=36656454529662513..." \
  -H "Authorization: Bearer ll_..."
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "tokenId": "36656454529662513...",
    "midpoint": "0.655",
    "buyPrice": "0.66",
    "sellPrice": "0.65",
    "lastTradePrice": "0.65"
  }
}
```

***

## Spread

<ParamField query="GET" path="/spread">
  Get the bid-ask spread for a token.
</ParamField>

### Example

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/spread?token_id=36656454529662513..." \
  -H "Authorization: Bearer ll_..."
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "bid": "0.65",
    "ask": "0.66",
    "spread": "0.01",
    "spreadPercent": "1.52"
  }
}
```

***

## Market Data (All-in-One)

<ParamField query="GET" path="/market-data">
  Get comprehensive market data in a single request.
</ParamField>

### Example

```bash theme={null}
curl "https://luckylobster.io/api/agent/v1/market-data?token_id=36656454529662513..." \
  -H "Authorization: Bearer ll_..."
```

Returns prices, spread, and order book summary combined.