Skip to main content
This guide walks through a complete SocialFi integration with the CabalSpy ID SocialFi API: from an empty dashboard to your first signed-in user and their live trading data, the base for leaderboards, trader profiles, activity feeds and every other social feature on your platform. It uses the login button in a browser app and a small backend that verifies the ID token and calls the Data API.
1

Create an instance

Open the API Dashboard, go to the CabalSpy ID tab and create an instance. Start in sandbox or development mode. Copy the Instance ID, it is your client_id and starts with csid_.Add the page that shows the button as a redirect URI, for example https://app.example.com/, and add its origin as a web origin. Redirect URIs must match exactly.Two more settings before the first sign-in works:
  • Scopes. A new instance may only ask for openid, profile and offline_access. Switch on the others you request (wallets, thesis, trade_feed, …) under Settings, Scopes. Otherwise sign-in stops with “This app is not allowed to request: …”.
  • Testers. Until you go live, only testers can sign in. Add their X handles under Domains & testers, including your own: your dashboard login is not a CabalSpy ID.
2

Add the login button

Paste the button where people should sign in. For a browser app the widget runs the whole PKCE flow itself.
After a successful sign-in the widget fires a csid:login event on window.
Server-side apps set data-href to their own login route instead and run the flow with their client secret, see OpenID Connect.
3

Verify the ID token on your backend

Never trust the user object from the browser on its own. Verify the ID token’s signature with the public keys at https://id.cabalspy.xyz/oauth/jwks, and check the issuer and the audience.
Store sub as the user’s id in your database. It never changes for that person and your instance.
Handling users without X. People can sign in with X, Telegram or Google. Users without X have x: null, a handle like tg.<name> or id.<hex>, and possibly no picture. Show a fallback avatar, never key on the handle (it changes when they connect X later), and see Users without X.
4

Enable your API key for CabalSpy ID

The Data API uses the same API key as the CabalSpy API. On the API keys page of the dashboard, every key shows Works with: CabalSpy API / CabalSpy ID API; both are on by default. Then check it:
The response shows your instance, plan, request rate and how many users you receive data for. If your account has several instances, add instance=csid_... to every call.Development and sandbox instances allow 1 request per second. Space your calls or retry after HTTP 429 with the Retry-After header; the SDKs do both for you.
5

Call the Data API

Look up the signed-in user by the sub from the ID token (step 3), then load the trading profile of each of their verified wallets.
The official SDKs do steps 3 to 5 in a few lines: npm install cabalspy-id (with a React button in cabalspy-id/react) or pip install cabalspy-id.

Going live

When everything works, switch the instance to live in the dashboard. Live instances need a verified domain, a logo, privacy policy and terms URLs and a support e-mail, and every redirect URI and web origin must be on a verified domain. If you request the wallets or onchain scope, the instance is reviewed first.

Next steps

Webhooks

React when a user verifies a wallet or gets the KOL badge.

Plans and limits

How many users you receive data for and how fast you can call the API.