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

# baseFM identity API

> Link a Base wallet to your baseFM DJ profile and retrieve DJ stats

# baseFM identity API

Link your Base wallet address to connect your baseFM DJ identity. Once linked, you can retrieve your DJ profile, listener stats, show history, and tip totals from baseFM.

## Get linked wallet

```http theme={"dark"}
GET /api/user/basefm-wallet
```

Returns the Base wallet address currently linked to your account. Requires session authentication.

### Response

```json theme={"dark"}
{
  "wallet": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f"
}
```

| Field    | Type           | Description                                                      |
| -------- | -------------- | ---------------------------------------------------------------- |
| `wallet` | string \| null | The linked Base wallet address, or `null` if no wallet is linked |

### Errors

| Code | Description                     |
| ---- | ------------------------------- |
| 401  | Unauthorized — no valid session |

### Example

```bash theme={"dark"}
curl -X GET https://agentbot.sh/api/user/basefm-wallet \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"
```

***

## Update linked wallet

```http theme={"dark"}
PATCH /api/user/basefm-wallet
```

Save or clear the Base wallet address linked to your baseFM DJ identity. Requires session authentication.

### Request body

| Field    | Type           | Required | Description                                                                                                          |
| -------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `wallet` | string \| null | Yes      | A valid Base wallet address (`0x`-prefixed, 40 hex characters). Pass `null` or an empty string to unlink the wallet. |

### Response

```json theme={"dark"}
{
  "ok": true,
  "wallet": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f"
}
```

| Field    | Type           | Description                                                    |
| -------- | -------------- | -------------------------------------------------------------- |
| `ok`     | boolean        | Whether the update succeeded                                   |
| `wallet` | string \| null | The saved wallet address, or `null` if the wallet was unlinked |

### Errors

| Code | Description                                                                                   |
| ---- | --------------------------------------------------------------------------------------------- |
| 400  | Invalid Base wallet address — the value must match `0x` followed by 40 hexadecimal characters |
| 401  | Unauthorized — no valid session                                                               |

### Example

```bash theme={"dark"}
curl -X PATCH https://agentbot.sh/api/user/basefm-wallet \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{"wallet": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f"}'
```

To unlink:

```bash theme={"dark"}
curl -X PATCH https://agentbot.sh/api/user/basefm-wallet \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{"wallet": null}'
```

***

## Get DJ stats

```http theme={"dark"}
GET /api/basefm/dj-stats
```

Fetches your baseFM DJ profile and aggregated stats using the linked wallet address. Requires session authentication and a linked Base wallet.

### Response (wallet linked, baseFM reachable)

```json theme={"dark"}
{
  "linked": true,
  "wallet": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f",
  "dj": {
    "name": "DJ Rave",
    "slug": "dj-rave",
    "avatar": "https://basefm.space/avatars/dj-rave.png",
    "followers": 142,
    "genres": ["Techno", "House"]
  },
  "stats": {
    "totalShows": 23,
    "totalListeners": 8401,
    "totalTipsUsdc": 54.25,
    "isLive": false
  }
}
```

### Response fields

| Field                  | Type           | Description                                                                                    |
| ---------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| `linked`               | boolean        | Whether a Base wallet is linked to the account                                                 |
| `wallet`               | string         | The linked Base wallet address                                                                 |
| `dj`                   | object \| null | DJ profile from baseFM. `null` if no DJ profile exists for this wallet.                        |
| `dj.name`              | string \| null | DJ display name                                                                                |
| `dj.slug`              | string \| null | URL slug for the DJ profile on baseFM                                                          |
| `dj.avatar`            | string \| null | Avatar image URL                                                                               |
| `dj.followers`         | number         | Follower count                                                                                 |
| `dj.genres`            | string\[]      | List of genres associated with the DJ                                                          |
| `stats`                | object \| null | Aggregated show statistics. `null` if baseFM is unreachable.                                   |
| `stats.totalShows`     | number         | Total number of completed and active shows                                                     |
| `stats.totalListeners` | number         | Cumulative listener count across all shows                                                     |
| `stats.totalTipsUsdc`  | number         | Total tips received in USDC (rounded to 2 decimal places)                                      |
| `stats.isLive`         | boolean        | Whether the DJ currently has an active live stream                                             |
| `error`                | string         | Present when baseFM could not be reached. The `linked` and `wallet` fields are still returned. |

### Response (no wallet linked)

```json theme={"dark"}
{
  "linked": false
}
```

When no wallet is linked, the response contains only `linked: false`. Link a wallet using the [update linked wallet](#update-linked-wallet) endpoint first.

### Response (baseFM unreachable)

```json theme={"dark"}
{
  "linked": true,
  "wallet": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f",
  "dj": null,
  "stats": null,
  "error": "baseFM unreachable"
}
```

When baseFM cannot be reached within the 6-second timeout, the `dj` and `stats` fields are `null` and an `error` message is included.

### Errors

| Code | Description                     |
| ---- | ------------------------------- |
| 401  | Unauthorized — no valid session |

### Example

```bash theme={"dark"}
curl -X GET https://agentbot.sh/api/basefm/dj-stats \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"
```