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

# KOL badge

> GET /v1/platform-users/kol, POST /kol/volume-check and POST /kol/apply: check a platform user's KOL badge eligibility, refresh their on-chain volume and apply for the badge.

Platform users can earn the same reviewed KOL badge as every CabalSpy ID user. It needs a connected [X account](https://docs.cabalspy.xyz/cabalspy-id/platform-users-x.md), and the requirements described in the [overview](https://docs.cabalspy.xyz/cabalspy-id/overview.md#trust): at least 5,000 followers, an X account older than 90 days and at least \$25,000 on-chain volume in the last 7 days. Every application is reviewed manually.

## Status

`GET /v1/platform-users/kol?external_id=<id>`

```bash theme={null}
curl "https://api-id.cabalspy.xyz/v1/platform-users/kol?external_id=user_8412" \
  -H "Authorization: Bearer YOUR_KEY"
```

**external\_id** `string`

Your id of the user.

**badge** `boolean`

Whether the user holds the KOL badge.

**eligible** `boolean`

Whether the user meets every criterion right now.

**criteria** `array`

The badge criteria and whether the user meets each of them.

**volume\_7d\_usd** `number`

The latest measured 7-day on-chain volume in USD.

**volume\_check\_next\_at** `string`

When the next volume check can be requested, or null.

**application** `object`

The latest application: status, applied\_at and reviewed\_at. Null when the user never applied.

## Volume check

`POST /v1/platform-users/kol/volume-check`

Queues a fresh measurement of the user's 7-day on-chain volume. Answers **202** with `"queued": true`; read the result with the status endpoint. Checks are rate limited per user, `volume_check_next_at` says when the next one is possible.

**external\_id** `string` *required*

Your id of the user. Alternatively pass csid\_id.

## Apply

`POST /v1/platform-users/kol/apply`

Applies for the badge in the user's name. Answers **201** with `"application": "pending"`. The user must have X connected and meet every criterion, otherwise the answer is `kol_not_eligible` with the `criteria`.

**external\_id** `string` *required*

Your id of the user. Alternatively pass csid\_id.

```bash cURL theme={null}
curl -X POST "https://api-id.cabalspy.xyz/v1/platform-users/kol/apply" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_8412"}'
```

```python Python theme={null}
import requests

H = {"Authorization": "Bearer YOUR_KEY"}
s = requests.get("https://api-id.cabalspy.xyz/v1/platform-users/kol",
                 params={"external_id": "user_8412"}, headers=H).json()["data"]
if s["eligible"] and not s["application"]:
    r = requests.post("https://api-id.cabalspy.xyz/v1/platform-users/kol/apply",
                      json={"external_id": "user_8412"}, headers=H)
    print(r.status_code, r.json())
```

```javascript JavaScript theme={null}
const res = await fetch("https://api-id.cabalspy.xyz/v1/platform-users/kol/volume-check", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ external_id: "user_8412" }),
});
console.log(res.status); // 202
```

```json Response theme={null}
{
  "success": true,
  "data": { "external_id": "user_8412", "application": "pending" },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-10-26T08:04:11Z" }
}
```

The status endpoint and the user object show `badge: true` once the badge is granted.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | external\_id missing. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 404 | platform\_user\_not\_found | No user with this id in your instance. |
| 409 | account\_claimed | The person claimed the account and manages it themselves. |
| 409 | volume\_check\_unavailable | Volume check: not possible right now. The message says why. |
| 409 | x\_required | Apply: the user has no X account connected. |
| 409 | kol\_not\_eligible | Apply: the application was refused, for example because a criterion is not met. The message says why, `criteria` lists the criteria. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.