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

### Platform users and managed accounts

A user you add is a **platform user**. For each one CabalSpy ID keeps a **managed** account that belongs to your instance:

* It has no CabalSpy ID login of its own and never appears on CabalSpy ID's public pages. `profile_url` is always null.
* Consent and a plan seat for your instance are implied: your platform informs its users. It is counted against your plan's user limit like a signed-in user.
* Through the API you can verify its wallets, connect X and Telegram, write theses in its name and apply for the KOL badge.
* The person can later take it into a normal CabalSpy ID with a [claim link](#claim-links), if you allow it.

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

> [!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` | The verify widget, the embedded Theses and Trade Feed widgets and the Telegram trade alerts your users get carry no CabalSpy ID wording or links. While `claim_links` is not set, claim links are off when this is `true`. |
| `data_scope` | Where your users' data is visible | `csid`, `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`, `verified_only` | `all`: unverified wallets you send count. `verified_only`: only payment-verified wallets count. |
| `leaderboard_trust` | Leaderboard | `all`, `verified_only` | Which wallets appear on the [platform leaderboard](https://docs.cabalspy.xyz/cabalspy-id/platform-users-leaderboard.md). |
| `claim_links` | Claim links | `true`, `false` | Whether you can create [claim links](#claim-links). |
| `telegram_alerts` | Telegram alerts for your users | `true`, `false` | 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, so after a save there `claim_links` is set explicitly and no longer follows `white_label`.

### Claim links

A [claim link](https://docs.cabalspy.xyz/cabalspy-id/platform-users-claim.md) lets a person take their managed account into their own, normal CabalSpy ID. They sign in on CabalSpy ID with their own account and confirm. Then:

* their **payment-verified** wallets move to their CabalSpy ID; unverified wallets do not,
* X and Telegram come along if their CabalSpy ID has none yet, and so do their theses and Trade Feed,
* your instance keeps access to them, the user's `csid_id` becomes the id of their own account and `claimed` turns true,
* you receive the [`platform_user.claimed`](https://docs.cabalspy.xyz/cabalspy-id/webhooks#white-label-events) webhook.

After the claim the person manages the account themselves. Changing it through the API returns `account_claimed`, and deleting the user only removes the link to your platform.

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

## Webhooks

Platform users trigger the regular [webhooks](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md) of your instance, plus `platform_user.created`, `platform_user.claimed`, `platform_user.x_connected`, `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) | Link to take the account into an own CabalSpy ID. |
| 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. |


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