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

# White-Label

> Keep your own login and brand: import your users and their existing wallets from Privy, Dynamic or any provider, and get their trades, PnL, leaderboards and trading competitions through the CabalSpy ID Data API.

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](https://docs.cabalspy.xyz/cabalspy-id/competitions.md) through the [Data API](https://docs.cabalspy.xyz/cabalspy-id/data-api.md). Your users 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, 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.

> [card] [Quickstart](https://docs.cabalspy.xyz/cabalspy-id/white-label-quickstart.md)
>
> Import users, show a profile, rank them and start a competition.

> [card] [Inbound URL](https://docs.cabalspy.xyz/cabalspy-id/platform-users-inbound.md)
>
> Let Privy, Dynamic or your backend send new sign-ups automatically.

> [card] [Competitions](https://docs.cabalspy.xyz/cabalspy-id/competitions.md)
>
> 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](https://apidashboard.cabalspy.xyz) and enable CabalSpy ID for your API key, exactly as described in [Authentication](https://docs.cabalspy.xyz/cabalspy-id/data-api.md#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](https://docs.cabalspy.xyz/cabalspy-id/platform-users-create.md), up to 1,000 at a time with [Import](https://docs.cabalspy.xyz/cabalspy-id/platform-users-import.md), or automatically on sign-up through the [inbound URL](https://docs.cabalspy.xyz/cabalspy-id/platform-users-inbound.md).

**3. Read their data**

From then on every trade of their wallets is tracked. Read a complete [profile](https://docs.cabalspy.xyz/cabalspy-id/platform-users-profile.md) in one call, rank your users on the [platform leaderboard](https://docs.cabalspy.xyz/cabalspy-id/platform-users-leaderboard.md), 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](https://docs.cabalspy.xyz/cabalspy-id/platform-users-x.md) or [Telegram](https://docs.cabalspy.xyz/cabalspy-id/platform-users-telegram.md), or [verify a wallet](https://docs.cabalspy.xyz/cabalspy-id/platform-users-verification.md), 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`](https://docs.cabalspy.xyz/cabalspy-id/webhooks#white-label-events). 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`](https://docs.cabalspy.xyz/cabalspy-id/webhooks#white-label-events). 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](https://docs.cabalspy.xyz/cabalspy-id/data-api.md#external-id). 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:

| Field | Meaning |
| - | - |
| `address` | A Solana or EVM address. |
| `chains` | The chains to track it on. Default: `solana` for a Solana address, every supported EVM chain (`bnb`, `base`, `eth`, `rh`) for an EVM address. |
| `source` | Optional label for where the wallet comes from, for example `privy` or `dynamic`. 1 to 40 characters `a-z 0-9 _ . -`. |

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](https://docs.cabalspy.xyz/cabalspy-id/platform-users-verification.md). 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`:

| status | Counts | Meaning |
| - | - | - |
| `verified` | Yes | Payment-verified, on the chains in `verified_chains`. |
| `active` | Yes | Unverified, accepted by your instance. |
| `needs_verification` | No | Unverified, and your instance only counts verified wallets (`wallet_trust: verified_only`). |
| `verified_elsewhere` | No | Unverified, another account verified this address. |
| `pending` | No | Only a verification was started for it, nothing counts yet. |

`counts` is true for `verified` and `active`.

The wallet endpoints [Tracker](https://docs.cabalspy.xyz/cabalspy-id/tracker.md), [History](https://docs.cabalspy.xyz/cabalspy-id/history.md), [Holdings](https://docs.cabalspy.xyz/cabalspy-id/holdings.md) and [PnL calendar](https://docs.cabalspy.xyz/cabalspy-id/pnl-calendar.md) 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.

> [!NOTE]
>
> [Wallet lookup](https://docs.cabalspy.xyz/cabalspy-id/wallet-lookup.md) and the `address` parameter of [Profile](https://docs.cabalspy.xyz/cabalspy-id/profile.md) 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](https://docs.cabalspy.xyz/cabalspy-id/platform-users-settings.md), or in the dashboard on the instance's [White-label](https://docs.cabalspy.xyz/cabalspy-id/dashboard.md#white-label) tab.

| Setting | Dashboard | Values | Meaning |
| - | - | - | - |
| `white_label` | No CabalSpy ID branding | `true`, `false` (default) | The verify widget, the embedded Theses and Trade Feed widgets and the Telegram messages your users get show your platform instead of CabalSpy ID. |
| `data_scope` | Where your users' data is visible | `csid` (default), `platform` | `csid` (default): your users are part of the CabalSpy ID network: profiles, leaderboard, Trade Feed and theses. `platform`: only your instance sees them. |
| `wallet_trust` | Wallets that count | `all` (default), `verified_only` | `all`: unverified wallets you send count, for profiles, leaderboards and the wallet endpoints (tracker, history, holdings, PnL calendar). `verified_only`: only payment-verified wallets count. |
| `leaderboard_trust` | Leaderboard | `all` (default), `verified_only` | Which wallets appear on the [platform leaderboard](https://docs.cabalspy.xyz/cabalspy-id/platform-users-leaderboard.md). |
| `telegram_alerts` | Telegram alerts for your users | `true`, `false` (default) | Trade Feed alerts through the CabalSpy ID Telegram bot for platform users who [linked Telegram](https://docs.cabalspy.xyz/cabalspy-id/platform-users-telegram.md). |

The dashboard always saves all of them together.

### Removing a user

[Deleting a user](https://docs.cabalspy.xyz/cabalspy-id/platform-users-delete.md) 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](https://docs.cabalspy.xyz/cabalspy-id/plans.md#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.

| Limit | Value |
| - | - |
| Users per import call | 1,000 (request body up to 1 MB) |
| Wallets per request | 10 |
| Wallets per user | 5 Solana and 5 EVM |
| New platform users per minute | 2,000 |
| Inbound URL events per minute | 600 |
| Open competitions | 5 per developer account (scheduled and running), on every plan |

## Webhooks

Platform users trigger the regular [webhooks](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md) of your instance, including the [Trade Feed](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md#trade-feed-events) and [copy trading](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md#copy-trading-events) 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](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md#white-label-events).

## Endpoints

| Method | Path | Description |
| - | - | - |
| POST | [/v1/platform-users](https://docs.cabalspy.xyz/cabalspy-id/platform-users-create.md) | Create or update a user. |
| POST | [/v1/platform-users/import](https://docs.cabalspy.xyz/cabalspy-id/platform-users-import.md) | Create or update up to 1,000 users. |
| GET | [/v1/platform-users](https://docs.cabalspy.xyz/cabalspy-id/platform-users-get.md) | One user by external\_id or csid\_id. |
| GET | [/v1/platform-users/list](https://docs.cabalspy.xyz/cabalspy-id/platform-users-get.md#list-users) | All your users, newest first. |
| POST, PATCH | [/v1/platform-users/update](https://docs.cabalspy.xyz/cabalspy-id/platform-users-create.md#update-a-user) | Change display name or avatar. |
| POST | [/v1/platform-users/delete](https://docs.cabalspy.xyz/cabalspy-id/platform-users-delete.md) | Delete a user. |
| POST | [/v1/platform-users/wallets/add](https://docs.cabalspy.xyz/cabalspy-id/platform-users-wallets.md) | Add wallets. |
| POST | [/v1/platform-users/wallets/delete](https://docs.cabalspy.xyz/cabalspy-id/platform-users-wallets.md#remove-a-wallet) | Remove a wallet. |
| POST, GET | [/v1/platform-users/wallets/verify](https://docs.cabalspy.xyz/cabalspy-id/platform-users-verification.md) | Payment verification: start, status, QR code, cancel. |
| GET | [/v1/platform-users/profile](https://docs.cabalspy.xyz/cabalspy-id/platform-users-profile.md) | Everything for a profile page in one call. |
| GET | [/v1/platform-users/leaderboard](https://docs.cabalspy.xyz/cabalspy-id/platform-users-leaderboard.md) | Your users ranked. |
| GET, POST | [/v1/platform-users/settings](https://docs.cabalspy.xyz/cabalspy-id/platform-users-settings.md) | Instance settings. |
| POST | [/v1/platform-users/session](https://docs.cabalspy.xyz/cabalspy-id/platform-users-session.md) | Short-lived session for the embeddable verification UI. |
| POST | [/v1/platform-users/claim-link](https://docs.cabalspy.xyz/cabalspy-id/platform-users-claim.md) | Removed: answers 410 `claim_removed`. |
| POST | [/v1/platform-users/x/connect](https://docs.cabalspy.xyz/cabalspy-id/platform-users-x.md) | Connect or disconnect X. |
| POST, GET | [/v1/platform-users/telegram/link](https://docs.cabalspy.xyz/cabalspy-id/platform-users-telegram.md) | Link, check or unlink Telegram. |
| GET, POST | [/v1/platform-users/kol](https://docs.cabalspy.xyz/cabalspy-id/platform-users-kol.md) | KOL badge status, volume check and application. |
| GET, POST | [/v1/platform-users/inbound](https://docs.cabalspy.xyz/cabalspy-id/platform-users-inbound.md) | The inbound URL for sign-up events. |
| GET, POST | [/v1/competitions](https://docs.cabalspy.xyz/cabalspy-id/competitions.md) | Trading competitions. |
| GET, POST | [/v1/callouts](https://docs.cabalspy.xyz/cabalspy-id/callouts.md) | Callouts by your users, with stats, a leaderboard and callout competitions. An extra, switched on per instance on request. |
| GET, POST | [/v1/trade-feed](https://docs.cabalspy.xyz/cabalspy-id/trade-feed.md) | Your users' Trade Feeds: the traders they follow and every trade of them. |
| GET, POST | [/v1/copy-trading](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md) | Copy trading: ready-to-execute instructions for every trade of a trader your user copies. Your platform executes with the user's wallet. |


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