Skip to main content
With White-Label your platform keeps its own login and its own brand. Your users never see a CabalSpy ID sign-in. You tell CabalSpy ID who your users are and which wallets they have, by your own user id, and you get their trades, PnL, profiles, leaderboards and trading competitions through the Data API. Your users can follow traders in their Trade Feed and copy them, with your platform executing the trades. You build the UI. It works with the wallets your users already have, from Privy, Dynamic, your own wallet infrastructure or any other provider. No wallet connect, no signatures and no payment are needed to start.

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_scope is csid. profile_url is 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_id changes, your external_id stays, and you receive platform_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_managed turns true and you receive platform_user.self_managed. They manage profile, X and Telegram from then on (self_managed error); 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.
A person can be a user of one platform only once. Proving an identity that is already linked to you under another 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 with wallet_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 set wallet_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, plus platform_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.

Endpoints