> ## 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.

# SocialFi Data API — authentication

> Authenticate to the CabalSpy ID SocialFi Data API: base URL, API keys, instance scope, response envelope, pagination and rate-limit headers.

The Data API returns the profiles, verified wallets and trading data of the people who signed in to your platform with CabalSpy ID. It follows the same conventions as the [CabalSpy API](https://docs.cabalspy.xyz/Data-APIs.md): the same envelope, the same error format and the same `blockchain`, `address` and `period` parameters. Wallet statistics are computed exactly like the CabalSpy API, so a wallet shows the same numbers on both.

## Base URL

```text theme={null}
https://api-id.cabalspy.xyz/v1/
```

## Authentication

The Data API uses the same API key as the CabalSpy API. In the [API Dashboard](https://apidashboard.cabalspy.xyz), open the **API keys** page: every key shows **Works with: CabalSpy API / CabalSpy ID API**, both on by default. A key with CabalSpy ID switched off is refused with `product_not_enabled`. No key yet? See [API key](https://docs.cabalspy.xyz/api-key.md).

Pass the key as an Authorization Bearer header or as the `apiKey` or `api_key` query parameter, the same as on the CabalSpy API.

```bash Bearer header theme={null}
curl "https://api-id.cabalspy.xyz/v1/me" \
  -H "Authorization: Bearer YOUR_KEY"
```

```bash Query parameter theme={null}
curl "https://api-id.cabalspy.xyz/v1/me?api_key=YOUR_KEY"
```

> [!WARNING]
>
> Your API key is a secret. Call the Data API from your backend, never from code that ships to the browser.

## Instance

A key works with one CabalSpy ID instance at a time. If your account has a single instance, nothing else is needed. With several instances, add `instance=<client_id>` to every request, otherwise the API answers `instance_required` and lists your instances.

**instance** `string`

The Instance ID (`csid_...`) to work with. Only needed when your account has several instances.

## Scope: who a key can see

A key sees the users of its instance only:

* **Live instances**: the users who signed in to any live app on your registrable domain, within your plan's user limit.
* **Development and sandbox instances**: the users who signed in to that app.

Users beyond your plan's user limit, users who removed access to your app and users you blocked are not visible. Requests for them return `profile_not_found` or `wallet_not_found`.

On the **Enterprise** plan, add `scope=global` to see every CabalSpy ID user. Other plans get `scope_not_allowed`.

**scope** `string` (default: instance)

`instance` or `global`. `global` requires the Enterprise plan.

## External ID

If you use [White-Label](https://docs.cabalspy.xyz/cabalspy-id/white-label.md), `external_id`, your own id of a platform user, works wherever `csid_id` does, on every endpoint, as a query parameter and in request bodies. The API looks up the user in your instance and uses their `csid_id`.

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

Pass either `external_id` or `csid_id`, not both. An unknown `external_id` returns `404 platform_user_not_found`.

## Response format

Every successful response has the same envelope.

```json Success theme={null}
{
  "success": true,
  "data": { },
  "pagination": {
    "limit": 50,
    "total": 312,
    "has_more": true,
    "next_cursor": "MjAyNi0xMC0xMlQxNDoyMTowNy40MDIxMTMrMDA6MDB8..."
  },
  "meta": {
    "request_id": "req_1f265546e444",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-10-13T08:04:11Z"
  }
}
```

`pagination` is only present on list endpoints. `meta.cached` and `meta.cache_age_seconds` show whether the data came from the short-lived cache.

Errors carry a machine-readable `code`, a message, the request id and a link to the [error reference](https://docs.cabalspy.xyz/cabalspy-id/errors.md).

```json Error theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid value for 'period'",
    "request_id": "req_5162c7cf7f87",
    "docs": "https://docs.cabalspy.xyz/cabalspy-id/errors#invalid_parameter",
    "parameter": "period",
    "allowed": ["6h", "1d", "7d", "30d"]
  }
}
```

## Pagination

List endpoints are cursor based. Read `next_cursor` from the response and pass it back as `cursor` to get the next page. When `next_cursor` is null, or `has_more` is false, you have reached the end.

## Rate-limit headers

Every authenticated response carries the limit of your plan.

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Requests per second of your plan. |
| `X-RateLimit-Remaining` | Requests left in the current second. |
| `X-RateLimit-Reset` | Seconds until the window resets (always 1). |
| `X-Request-ID` | The request id, also in `meta.request_id`. |

Above the limit the API answers `429 rate_limit_exceeded` with `Retry-After: 1`. See [Plans and limits](https://docs.cabalspy.xyz/cabalspy-id/plans.md).

## Common parameters

| Parameter | Values |
| - | - |
| `blockchain` | `solana`, `bnb`, `base`, `eth`, `rh` |
| `period` | `6h`, `1d`, `7d`, `30d` (rolling windows back from now) |
| `address` | A wallet verified by one of your users. EVM addresses are case-insensitive. |

## Endpoints

| Method | Path | Description |
| - | - | - |
| GET | [/v1/health](https://docs.cabalspy.xyz/cabalspy-id/health.md) | Service health, no key needed. |
| GET | [/v1/me](https://docs.cabalspy.xyz/cabalspy-id/me.md) | Your instance, plan and limits. |
| GET | [/v1/users](https://docs.cabalspy.xyz/cabalspy-id/users.md) | Your users, newest first. |
| GET | [/v1/profile](https://docs.cabalspy.xyz/cabalspy-id/profile.md) | One user by handle, id or wallet. |
| GET | [/v1/wallets/lookup](https://docs.cabalspy.xyz/cabalspy-id/wallet-lookup.md) | Who owns a verified wallet. |
| GET | [/v1/wallets/tracker](https://docs.cabalspy.xyz/cabalspy-id/tracker.md) | Trading profile of a wallet for a period. |
| GET | [/v1/wallets/history](https://docs.cabalspy.xyz/cabalspy-id/history.md) | Lifetime stats and the full trade log. |
| GET | [/v1/wallets/holdings](https://docs.cabalspy.xyz/cabalspy-id/holdings.md) | Current token balances. |
| GET | [/v1/wallets/pnl\_calendar](https://docs.cabalspy.xyz/cabalspy-id/pnl-calendar.md) | Realized PnL per day. |
| GET | [/v1/wallets/leaderboard](https://docs.cabalspy.xyz/cabalspy-id/leaderboard.md) | Your users ranked. |
| GET | [/v1/transactions/latest](https://docs.cabalspy.xyz/cabalspy-id/latest.md) | Newest trades of your users. |
| GET, POST | [/v1/theses/...](https://docs.cabalspy.xyz/cabalspy-id/theses.md#endpoints) | Token theses: read, and write in your users' names. |
| WS | [/v1/stream](https://docs.cabalspy.xyz/cabalspy-id/stream.md) | Every trade of your users and every thesis event, live. |
| GET, POST | [/v1/platform-users/...](https://docs.cabalspy.xyz/cabalspy-id/white-label.md#endpoints) | White-Label: your own users by external\_id. |
| GET, POST | [/v1/competitions/...](https://docs.cabalspy.xyz/cabalspy-id/competitions.md#endpoints) | Trading competitions between your platform users. |
| GET, POST, WS | [/v1/callouts/...](https://docs.cabalspy.xyz/cabalspy-id/callouts.md#endpoints) | Callouts: your users call tokens, tracked with stats, a leaderboard and a stream. An extra, switched on per instance on request. |
| GET, POST, WS | [/v1/trade-feed/...](https://docs.cabalspy.xyz/cabalspy-id/trade-feed.md#endpoints) | Trade Feed: the traders your users follow, every trade and thesis of them, notifications and a stream. |
| GET, POST, WS | [/v1/copy-trading/...](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md#endpoints) | Copy trading: settings per user and trader, ready-to-execute instructions, status reports and a stream. |

You can try every endpoint in the sandbox in the dashboard on the **CabalSpy ID** tab.


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