> ## 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](/Data-APIs): 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 and switch on **CabalSpy ID** for the key you want to use. A key without it is refused with `product_not_enabled`.

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

<CodeGroup>
  ```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"
  ```
</CodeGroup>

<Warning>
  Your API key is a secret. Call the Data API from your backend, never from code that ships to the browser.
</Warning>

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

<ParamField query="instance" type="string">
  The Instance ID (`csid_...`) to work with. Only needed when your account has several instances.
</ParamField>

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

<ParamField query="scope" default="instance" type="string">
  `instance` or `global`. `global` requires the Enterprise plan.
</ParamField>

## 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](/cabalspy-id/errors).

```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](/cabalspy-id/plans).

## 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](/cabalspy-id/health) | Service health, no key needed. |
| GET | [/v1/me](/cabalspy-id/me) | Your instance, plan and limits. |
| GET | [/v1/users](/cabalspy-id/users) | Your users, newest first. |
| GET | [/v1/profile](/cabalspy-id/profile) | One user by handle, id or wallet. |
| GET | [/v1/wallets/lookup](/cabalspy-id/wallet-lookup) | Who owns a verified wallet. |
| GET | [/v1/wallets/tracker](/cabalspy-id/tracker) | Trading profile of a wallet for a period. |
| GET | [/v1/wallets/history](/cabalspy-id/history) | Lifetime stats and the full trade log. |
| GET | [/v1/wallets/holdings](/cabalspy-id/holdings) | Current token balances. |
| GET | [/v1/wallets/pnl\_calendar](/cabalspy-id/pnl-calendar) | Realized PnL per day. |
| GET | [/v1/wallets/leaderboard](/cabalspy-id/leaderboard) | Your users ranked. |
| GET | [/v1/transactions/latest](/cabalspy-id/latest) | Newest trades of your users. |
| GET, POST | [/v1/theses/...](/cabalspy-id/theses#endpoints) | Token theses: read, and write in your users' names. |
| WS | [/v1/stream](/cabalspy-id/stream) | Every trade of your users and every thesis event, live. |

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.