SocialFi Data API — authentication

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: 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

https://api-id.cabalspy.xyz/v1/

Authentication

The Data API uses the same API key as the CabalSpy API. In the API Dashboard, 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.

curl "https://api-id.cabalspy.xyz/v1/me" \
  -H "Authorization: Bearer YOUR_KEY"

curl "https://api-id.cabalspy.xyz/v1/me?api_key=YOUR_KEY"

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.

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.

string

default:"instance"

instance or global. global requires the Enterprise plan.

Response format

Every successful response has the same envelope.

Success

{
  "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.

Error

{
  "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.

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	Service health, no key needed.
GET	/v1/me	Your instance, plan and limits.
GET	/v1/users	Your users, newest first.
GET	/v1/profile	One user by handle, id or wallet.
GET	/v1/wallets/lookup	Who owns a verified wallet.
GET	/v1/wallets/tracker	Trading profile of a wallet for a period.
GET	/v1/wallets/history	Lifetime stats and the full trade log.
GET	/v1/wallets/holdings	Current token balances.
GET	/v1/wallets/pnl_calendar	Realized PnL per day.
GET	/v1/wallets/leaderboard	Your users ranked.
GET	/v1/transactions/latest	Newest trades of your users.
GET, POST	/v1/theses/…	Token theses: read, and write in your users’ names.
WS	/v1/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.

Introduction

Login

Data API

Users

Trading

Theses

Streams

Reference

SocialFi Data API — authentication

Base URL

Authentication

Instance

Scope: who a key can see

Response format

Rate-limit headers

Common parameters

Endpoints

​Base URL

​Authentication

​Instance

​Scope: who a key can see

​Response format

​Pagination

​Rate-limit headers

​Common parameters

​Endpoints

Base URL

Authentication

Instance

Scope: who a key can see

Response format

Pagination

Rate-limit headers

Common parameters

Endpoints