# Fishtank — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access clips, episodes, contestant information, and live stream updates from Fishtank.live to browse content, check leaderboard rankings, and track live broadcast status. Get detailed information about specific clips and episodes, or discover random clips and current stox data.

**Category:** Streaming Video | **Website:** [fishtank.live/](https://fishtank.live/) | **Docs:** [parse.bot/marketplace/3189d8fe-1a41-4431-9b8f-c7b3e453a4b3/fishtank-live-api](https://parse.bot/marketplace/3189d8fe-1a41-4431-9b8f-c7b3e453a4b3/fishtank-live-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-fishtank-live-api-3189d8fe/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_clip_detail

Retrieve full details and comments for a specific clip by its numeric ID. Returns the clip metadata, the creator's display name, and a paginated list of comments with user profiles and nested replies.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `clip_id` | string | Yes | The numeric ID of the clip (e.g., '398178'). Obtainable from get_clips results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fishtank-live-api-3189d8fe/get_clip_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clip_id":"<string>"}'
```

### get_clips

Search and retrieve clips with paginated results and optional filters. Supports sorting by engagement (hot_score) or view count. Filters by room, season, and text search can be combined. Returns a page of clips and the total matching count for pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed). |
| `page_size` | integer | No | Number of clips per page. |
| `room` | string | No | Filter by room name (e.g., 'Bedroom 1', 'Director Mode', 'Laundry Room', 'Bar', 'Cameraman'). |
| `search` | string | No | Text search query to filter clips by name. |
| `season` | string | No | Filter by season (e.g., 'Season 4', 'Season 5'). |
| `sort` | string | No | Sort order for clips. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fishtank-live-api-3189d8fe/get_clips \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","page_size":"<integer>","room":"<string>","search":"<string>","season":"<string>","sort":"<string>"}'
```

### get_episode_detail

Retrieve comments for a specific episode by its UUID. Returns the episode UUID and a list of comments with full user profiles and nested replies.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uuid` | string | Yes | The UUID of the episode (e.g., '3a682dce-bf86-4d40-8601-89d0cfcd3b6a'). Obtainable from get_episodes results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fishtank-live-api-3189d8fe/get_episode_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uuid":"<string>"}'
```

### get_episodes

Retrieve the complete list of all available episodes organized by season or category. Each category maps to an array of episodes with metadata including title, duration, and thumbnail URL.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fishtank-live-api-3189d8fe/get_episodes \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_initial_data

Retrieve site metadata including active contestants, current poll state, recent TTS messages, feature toggles, and the current site announcement. Returns all bootstrap data needed to render the site's initial state.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fishtank-live-api-3189d8fe/get_initial_data \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_leaderboard

Retrieve the top users leaderboard ranked by XP. Returns the top 30 users with their display name, XP total, token balance, and medal counts.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fishtank-live-api-3189d8fe/get_leaderboard \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_live_streams

Retrieve current live stream definitions and their online statuses. Returns the stream list with playback IDs, season, access level, and interactive flag, plus load balancer mappings and status per stream.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fishtank-live-api-3189d8fe/get_live_streams \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_random_clip

Retrieve a random clip from the entire clip library. Returns a single clip object with full metadata. Useful for discovery or random content surfacing.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fishtank-live-api-3189d8fe/get_random_clip \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_stox

Retrieve contestant stock prices (Stox) including current price, IPO price, average price, total shares, and order book data. Orders array is empty when unauthenticated.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-fishtank-live-api-3189d8fe/get_stox \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```