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

# CabalSpy ID — SocialFi API & SDK

> CabalSpy ID is a SocialFi API and SDK for trading platforms: sign in with X, verified wallets, live trades and PnL on Solana, BNB Chain, Base, Ethereum and Robinhood Chain, token theses and webhooks.

#### **The SocialFi layer for your trading platform.** 

CabalSpy ID is a SocialFi API and SDK that gives a trading platform a social layer for its own customers. Add **Sign in with CabalSpy ID** and every user who signs in arrives with their social identity, X or Telegram, and their verified wallets. From that moment every trade those users make is tracked live across Solana, BNB Chain, Base, Ethereum and Robinhood Chain.

Your platform gets each user's identity, KOL badge and full trading record, PnL, win rate, trades, holdings and a daily PnL calendar, through one API, a live trade stream and webhooks: one SocialFi integration instead of building identity, wallet verification and trade tracking yourself. Build leaderboards of your own users, show real positions next to every opinion, put your users' trades on the chart, and turn trading into something people follow, copy and compete in.

> [card] [Login](https://docs.cabalspy.xyz/cabalspy-id/login-button.md)
>
> A drop-in login button and a standard OpenID Connect provider. Every user arrives with X and verified wallets.

> [card] [Data API](https://docs.cabalspy.xyz/cabalspy-id/data-api.md)
>
> Profiles, trading stats, PnL charts, holdings, calendars and leaderboards of your users.

> [card] [Live](https://docs.cabalspy.xyz/cabalspy-id/stream.md)
>
> Every trade of your users pushed live, plus webhooks when a user verifies a wallet or becomes a KOL.

## Choose your path

CabalSpy ID works in two ways. Pick one, or use both in the same instance.

> [card] [Login with CabalSpy ID](https://docs.cabalspy.xyz/cabalspy-id/quickstart.md)
>
> Your users sign in with CabalSpy ID and arrive with X, Telegram and verified wallets. For platforms without a login yet, or that want verified identities. Start with the **Login quickstart**.

> [card] [White-Label](https://docs.cabalspy.xyz/cabalspy-id/white-label-quickstart.md)
>
> You keep your own login (Privy, Dynamic, your own) and brand. Your backend adds your users and their existing wallets by your own user id. Your users never see CabalSpy ID. Start with the **White-Label quickstart**.

Both paths get the same data and features: profiles, wallet tracker, leaderboards, theses, callouts, Trade Feed, copy trading and [trading competitions](https://docs.cabalspy.xyz/cabalspy-id/competitions.md).

## Use cases

What platforms build with CabalSpy ID, and the endpoints that power each feature.

| Use case | What your users see | Powered by |
| - | - | - |
| Leaderboards of your users | Your community ranked by PnL, volume, win rate or trades over 6h, 1d, 7d or 30d. | [leaderboard](https://docs.cabalspy.xyz/cabalspy-id/leaderboard.md) |
| Token theses with real positions | Opinions on a token written only by holders, each showing the author's real position and PnL, shared across every platform. | [theses](https://docs.cabalspy.xyz/cabalspy-id/theses.md) (widget or API), [stream](https://docs.cabalspy.xyz/cabalspy-id/stream.md), [holdings](https://docs.cabalspy.xyz/cabalspy-id/holdings.md), [tracker](https://docs.cabalspy.xyz/cabalspy-id/tracker.md) |
| Trades on the token chart | Buys and sells of your users, and of KOLs among them, as markers on the price chart. | [stream](https://docs.cabalspy.xyz/cabalspy-id/stream.md), [transactions/latest](https://docs.cabalspy.xyz/cabalspy-id/latest.md) |
| Live social activity feed | Who just bought or sold what, with name, avatar and KOL badge, as it happens. | [stream](https://docs.cabalspy.xyz/cabalspy-id/stream.md), [transactions/latest](https://docs.cabalspy.xyz/cabalspy-id/latest.md) |
| Copy trading with verified performance | Traders to follow chosen on real, on-chain results, with their trades pushed live. | [leaderboard](https://docs.cabalspy.xyz/cabalspy-id/leaderboard.md), [tracker](https://docs.cabalspy.xyz/cabalspy-id/tracker.md), [history](https://docs.cabalspy.xyz/cabalspy-id/history.md), [stream](https://docs.cabalspy.xyz/cabalspy-id/stream.md) |
| In-app trader profiles | A profile page per user with stats, PnL chart, holdings, trade history and PnL calendar. | [profile](https://docs.cabalspy.xyz/cabalspy-id/profile.md), [tracker](https://docs.cabalspy.xyz/cabalspy-id/tracker.md), [holdings](https://docs.cabalspy.xyz/cabalspy-id/holdings.md), [history](https://docs.cabalspy.xyz/cabalspy-id/history.md), [pnl\_calendar](https://docs.cabalspy.xyz/cabalspy-id/pnl-calendar.md) |
| Verified and KOL badges | A badge next to every user whose X account and wallets are verified, and a KOL badge for reviewed KOLs. | [users](https://docs.cabalspy.xyz/cabalspy-id/users.md), [profile](https://docs.cabalspy.xyz/cabalspy-id/profile.md), [webhooks](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md) |
| Competitions and rewards | Trading competitions and rewards based on real trading in a chosen period, not on self-reported numbers. | [competitions](https://docs.cabalspy.xyz/cabalspy-id/competitions.md), [leaderboard](https://docs.cabalspy.xyz/cabalspy-id/leaderboard.md), [tracker](https://docs.cabalspy.xyz/cabalspy-id/tracker.md) |
| Your own login, our data | Keep your login and brand: import your users and their existing wallets, and get their trades, PnL and leaderboards. | [White-Label](https://docs.cabalspy.xyz/cabalspy-id/white-label.md), [platform profile](https://docs.cabalspy.xyz/cabalspy-id/platform-users-profile.md), [platform leaderboard](https://docs.cabalspy.xyz/cabalspy-id/platform-users-leaderboard.md) |
| Keeping your user base in sync | New wallets, profile changes, new KOL badges and revoked access reach your backend without polling. | [webhooks](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md), [users](https://docs.cabalspy.xyz/cabalspy-id/users.md) |

All trading numbers are computed exactly like the CabalSpy API, so a wallet shows the same figures everywhere.

## Trust

The social layer is only worth something if it is real. CabalSpy ID makes sure that the person, the wallets and the badges are genuine.

**1. Identity from X or Telegram**

Users sign in with X, with Telegram through the CabalSpy ID bot, or with Google as an alternative. With X, name, handle, avatar and follower counts come from X. Users without X can connect it later, and anyone can verify their Telegram account, which then shows on their public profile.

**2. Verified wallets**

A user proves a wallet by sending a tiny payment from it. No wallet connect and no signatures, the payment itself is the proof. Every verified wallet is tracked live from then on.

**3. Reviewed KOL badge**

Accounts with 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 can apply. Every badge is reviewed and approved manually.

Users without X can do everything except earn the KOL badge, which requires X. Your app receives them with `x` set to null and a handle like `tg.<name>`, see [Users without X](https://docs.cabalspy.xyz/cabalspy-id/openid-connect.md#users-without-x).

Users stay in control. Every user has a public profile at `https://id.cabalspy.xyz/u/<handle>`, sees every app they signed in to and can remove access at any time. Your app then receives a `consent.revoked` webhook.

## Getting started

Everything for developers lives in the [API Dashboard](https://apidashboard.cabalspy.xyz), on the **CabalSpy ID** tab. No account yet? [Create one and get your API key](https://docs.cabalspy.xyz/api-key.md) first. The [Login quickstart](https://docs.cabalspy.xyz/cabalspy-id/quickstart.md) and the [White-Label quickstart](https://docs.cabalspy.xyz/cabalspy-id/white-label-quickstart.md) walk through it.

**1. Create an instance**

An instance is your app on CabalSpy ID. Its Instance ID is your `client_id` and starts with `csid_`. Server-side apps also create a client secret, which starts with `csid_sk_`. Redirect URIs are only needed for Login with CabalSpy ID; leave them empty for White-Label.

**2. Add the login button, or your users**

Login: switch on the scopes you ask for (Settings, Scopes), add yourself and your testers by X handle, then design the button or run the OpenID Connect flow yourself. White-Label: add your users with your API key.

**3. Read your users' data**

Call the Data API with the same API key you use for the CabalSpy API. On the API keys page every key has **Works with: CabalSpy API / CabalSpy ID API**; both are on by default.

The dashboard also holds your redirect URIs, verified domain, testers, webhooks, users and statistics, billing and a sandbox to try every endpoint. [Dashboard settings](https://docs.cabalspy.xyz/cabalspy-id/dashboard.md) explains every field, tab by tab.

### Instance modes

| Mode | Who can sign in | Requirements |
| - | - | - |
| sandbox | Made-up test identities only, no real sign-ins | None. For building the login and CI. |
| development | Up to 25 testers, by X handle | None. Real CabalSpy ID sign-in. Your dashboard login is not a CabalSpy ID: add your own X handle as a tester too. |
| live | Everyone | A verified domain, a logo, privacy policy and terms URLs and a support e-mail. The scopes `wallets` and `onchain` need an admin review. |

Development and sandbox instances allow 1 request per second and 25 users; a live instance uses your [plan](https://docs.cabalspy.xyz/cabalspy-id/plans.md). For White-Label, use **development**: your platform users have real wallets and real trades.

You verify a domain with a DNS TXT record at `_csid-verification.<domain>` or with a file at `https://<domain>/.well-known/csid-verification.txt`. The dashboard shows the exact value.

## White-Label

Platforms that keep their own login use CabalSpy ID as white-label technology. Your users never see a CabalSpy ID sign-in: you add them by your own user id (`external_id`) with the wallets they already have, one by one, in bulk or automatically from Privy, Dynamic or your backend through an inbound URL. Every trade of their wallets is tracked, and you read profiles, leaderboards and run trading competitions through the Data API. White-Label is available on every plan; the plan sets how many users you can have. See [White-Label](https://docs.cabalspy.xyz/cabalspy-id/white-label.md).

## What platforms receive

At sign-in, what you receive depends on the scopes the user approves.

| Scope | Data |
| - | - |
| `openid` | A stable user id (`sub`). Required. |
| `profile` | Name, handle, avatar, the KOL badge and, when the user has X, their X account with follower counts. |
| `wallets` | Verified wallet addresses and the chains they are verified on. |
| `onchain` | The latest 7-day on-chain trading volume. |
| `offline_access` | A refresh token, so you keep access while the user is away. |
| `thesis` | Lets your app post theses and replies, react and report in the user's name. |
| `trade_feed` | Lets your app manage the user's [Trade Feed](https://docs.cabalspy.xyz/cabalspy-id/trade-feed.md), get every trade of the traders in it and [copy](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md) them. |

Through the [Data API](https://docs.cabalspy.xyz/cabalspy-id/data-api.md), the [stream](https://docs.cabalspy.xyz/cabalspy-id/stream.md) and [webhooks](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md) you get the live trading record of every user who signed in.

Users who granted `trade_feed` can follow traders in their [Trade Feed](https://docs.cabalspy.xyz/cabalspy-id/trade-feed.md) and [copy](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md) them: CabalSpy ID sends your app a ready-to-execute instruction for every trade of a copied trader, and your app executes it with the user's wallet. CabalSpy ID never holds keys or executes trades.

On request, CabalSpy also switches on [Callouts](https://docs.cabalspy.xyz/cabalspy-id/callouts.md) for your instance: your users publicly call tokens, and CabalSpy ID tracks each call like the CabalSpy call statistics, with stats, a leaderboard, a stream and callout competitions.

> [!NOTE]
>
> Your plan sets how many users you receive data for. Everyone can always sign in. Above the limit you receive an anonymous id and no data for the extra users until you upgrade. See [Plans and limits](https://docs.cabalspy.xyz/cabalspy-id/plans.md).

## Supported chains

| Chain | `blockchain` value | Currency |
| - | - | - |
| Solana | `solana` | SOL |
| BNB Chain | `bnb` | BNB |
| Base | `base` | ETH |
| Ethereum | `eth` | ETH |
| Robinhood Chain | `rh` | ETH |

## Base URLs

```text theme={null}
https://id.cabalspy.xyz          Sign-in, OpenID Connect, login button
https://api-id.cabalspy.xyz/v1   Data API
wss://api-id.cabalspy.xyz/v1/stream   Live trades
```


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