Quickstart
Import users, show a profile, rank them and start a competition.
Inbound URL
Let Privy, Dynamic or your backend send new sign-ups automatically.
Competitions
Trading competitions between your users, ranked on real trades.
How it works
1
Create an instance and an API key
Create a CabalSpy ID instance in the API Dashboard and enable CabalSpy ID for your API key, exactly as described in Authentication. White-Label uses the same key, envelope, errors and rate limit as the rest of the Data API.
2
Add your users
Send each user with your own user id and at least one wallet: one by one with Create or update a user, up to 1,000 at a time with Import, or automatically on sign-up through the inbound URL.
3
Read their data
From then on every trade of their wallets is tracked. Read a complete profile in one call, rank your users on the platform leaderboard, and use every other Data API endpoint with your user id in place of
csid_id.Concepts
One person, one CabalSpy ID
A user you add is a platform user. Every person has exactly one CabalSpy ID, whichever platforms they use, and your platform user points at it:- New person: you create their account. It is managed: created by your platform, no CabalSpy ID login yet, and not on CabalSpy ID’s public pages unless
data_scopeiscsid.profile_urlis null. - The person already has a CabalSpy ID: when they connect X or Telegram, or verify a wallet, that their own CabalSpy ID holds, your user moves to that ID by itself. Their
csid_idchanges, yourexternal_idstays, and you receiveplatform_user.merged. Nothing they only claim, such as a wallet you report, merges anything. - The person signs in themselves: once they sign in to CabalSpy ID with the X or Telegram connected through your platform, the account is theirs:
self_managedturns true and you receiveplatform_user.self_managed. They manage profile, X and Telegram from then on (self_managederror); you keep access and can still report wallets. - Consent and a plan seat for your instance are implied: your platform informs its users. Every person counts once against your plan’s user limit, like a signed-in user.
- The person sees your platform under connected apps in their CabalSpy ID and can remove it there.
external_id is refused with already_linked.
Every action you take for a platform user is recorded in an audit log with your instance.
external_id
external_id is your id of the user, for example the id from your database, from Privy (did:privy:...) or from Dynamic. It is 1 to 128 printable ASCII characters without spaces, and unique within your instance. Each platform user also has a csid_id, the CabalSpy ID account id.
Use external_id everywhere: on the /v1/platform-users endpoints, and on every other Data API endpoint in place of csid_id, see external_id in the Data API. A key only ever reaches the platform users of its own instance.
Every user has a wallet
A platform user needs at least one wallet. Creating a user without one is refused withwallet_required, and the last wallet of a user cannot be removed (last_wallet). Delete the user instead.
A wallet is an object with an address and optional chains and source, or just the address as a string:
A request can carry up to 10 wallets. A user can hold up to 5 Solana and 5 EVM wallets.
Unverified and verified wallets
Wallets you send are unverified: you vouch that they belong to the user. They are your report: other platforms the person uses do not see them. They are tracked and count for data, profiles and leaderboards straight away, unless you setwallet_trust to verified_only.
A wallet becomes verified with the same on-chain payment verification as on the CabalSpy ID website: the user sends a tiny, unique amount from the wallet. You start it with Verify a wallet. Verification is optional and works as a trust badge.
Whoever verifies an address owns it. If another account verifies an address that one of your users has as an unverified wallet, that copy stops counting.
Every wallet in a user object carries a status:
counts is true for verified and active.
The wallet endpoints Tracker, History, Holdings and PnL calendar answer for every wallet of your platform users that counts, so you can build a full portfolio view per wallet. profile.wallet_verified says whether the wallet is payment-verified.
Wallet lookup and the
address parameter of Profile only find payment-verified wallets. Find a platform user by external_id instead.Settings
Your instance has a few White-Label settings. Read and change them with Settings, or in the dashboard on the instance’s White-label tab.
The dashboard always saves all of them together.
Removing a user
Deleting a user removes your platform from the person: your link, the wallets only you reported, your consent. Their account is deleted too only while it is managed and no other platform holds it. A person’s own CabalSpy ID always stays. Claim links are gone:POST /v1/platform-users/claim-link answers 410 claim_removed.
Plan limits
White-Label is available on every plan. The plan sets how many users you can have.- Live instances count platform users against the user limit of your domain’s plan, together with everyone who signed in with CabalSpy ID. When the limit is reached, new users are refused with
plan_user_limit(existing users can still be updated). - Sandbox and development instances can hold 25 platform users. Go live with a verified domain for your plan’s limit.
Webhooks
Platform users trigger the regular webhooks of your instance, including the Trade Feed and copy trading events, plusplatform_user.created, platform_user.merged, platform_user.self_managed, platform_user.x_connected, platform_user.telegram_linked, wallet.added and verification.expired. See White-Label events.

