Inbound URL

Instead of calling the API on every sign-up, you can give your auth provider or your backend a secret inbound URL. Every sign-up or wallet event posted to it creates or updates the platform user, exactly like Create or update a user. It works with the webhooks of Privy, Dynamic and any other provider that sends JSON, and with your own format. No API key is needed: the secret in the URL identifies your instance. In the dashboard the inbound URL is the Sign-up URL on the instance’s White-label tab: Switch on creates it, Create a new URL replaces it and Switch off disables it, like the calls below.

Keep the URL secret. Whoever knows it can create users in your instance. If it leaks, enable it again to get a new URL, the old one stops working at once.

Enable

POST /v1/platform-users/inbound/enable Creates the secret URL and returns it. It is shown only once. Calling it again replaces the URL.

curl -X POST "https://api-id.cabalspy.xyz/v1/platform-users/inbound/enable" \
  -H "Authorization: Bearer YOUR_KEY"

import requests

r = requests.post("https://api-id.cabalspy.xyz/v1/platform-users/inbound/enable",
                  headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["data"]["url"])   # store it as a secret

const res = await fetch("https://api-id.cabalspy.xyz/v1/platform-users/inbound/enable", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY" },
});
const { data } = await res.json();
console.log(data.url);

Response

{
  "success": true,
  "data": {
    "enabled": true,
    "url": "https://api-id.cabalspy.xyz/v1/inbound/csin_r8Tq2...",
    "note": "Keep this URL secret: whoever knows it can create users in your instance. Calling this again replaces it."
  },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-10-26T08:04:11Z" }
}

Status

GET /v1/platform-users/inbound

curl "https://api-id.cabalspy.xyz/v1/platform-users/inbound" \
  -H "Authorization: Bearer YOUR_KEY"

Response

{
  "success": true,
  "data": {
    "enabled": true,
    "last_event_at": "2026-10-26T07:58:02Z",
    "formats": ["csid", "privy", "dynamic", "generic"]
  },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-10-26T08:04:11Z" }
}

The URL itself is never shown again. last_event_at is the time of the last event received.

Disable

POST /v1/platform-users/inbound/disable Switches the URL off. Returns {"enabled": false}. Events posted to it afterwards get 404 invalid_inbound_url.

Send events

POST https://api-id.cabalspy.xyz/v1/inbound/csin_... Post one event per request as a JSON object. The event is read like this:

User id: the first of external_id, user.id, data.userId, userId, data.user_id, user_id and data.id that is set. It becomes the external_id.
Event name: event, type or eventName.
Wallets: the wallets array if the body has one (CabalSpy ID format, with chains and source). Otherwise every Solana or EVM address found anywhere in the body in a field named address, wallet_address, walletAddress, publicKey or public_key. Other values, such as e-mail addresses, are ignored.
Profile: display_name and avatar_url at the top level, if present.

Then:

Event	Result
Name contains `delet` (and not `wallet`), for example `user.deleted`	The user is deleted.
`wallet.removed` in the CabalSpy ID format, with `wallets`	Those wallets are removed: `wallets_removed`. The user’s last wallet stays and is listed in `wallets_not_removed` with `last_wallet`.
Any other name that contains `unlink`, `remov` or `delet`, for example Privy `user.unlinked_account` or Dynamic `wallet.unlinked`	Nothing changes: `ignored`.
Unknown user, no wallet in the body, for example an e-mail sign-up before the embedded wallet exists	Nothing yet: `waiting_for_wallet`. The next event with a wallet creates the user.
Anything else	The user is created, or updated with new wallets and profile fields.

Wallet removals from auth providers are not applied, because their payloads usually also carry the wallets the user keeps. To remove a wallet, send {"event": "wallet.removed", "external_id": "...", "wallets": ["<address>"]} to the inbound URL, or call POST /v1/platform-users/wallets/delete.

CabalSpy ID format

Use this from your own backend.

{
  "event": "user.created",
  "external_id": "user_8412",
  "display_name": "Maze",
  "avatar_url": "https://cdn.example.com/avatars/8412.png",
  "wallets": [
    { "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW", "source": "embedded" },
    { "address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01", "chains": ["base"] }
  ]
}

event is one of user.created, user.updated, wallet.added and user.deleted. wallets takes the same items as Create or update a user.

Privy

Add the inbound URL as a webhook endpoint in the Privy dashboard and subscribe to the user created and wallet created events. The Privy user id (user.id, did:privy:...) becomes the external_id, and the wallet addresses in linked_accounts and wallet are added.

Privy user.created

{
  "type": "user.created",
  "user": {
    "id": "did:privy:cm3np4u9j001rc8b73seqmqqk",
    "linked_accounts": [
      { "type": "email", "address": "maze@example.com" },
      { "type": "wallet", "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW", "chain_type": "solana" }
    ]
  }
}

Dynamic

Add the inbound URL as a webhook in the Dynamic dashboard and subscribe to user creation and wallet linking. The top-level userId becomes the external_id; every address or publicKey is added.

Dynamic user.created

{
  "eventName": "user.created",
  "userId": "8b1f2c4d-6e7a-4b9c-8d0e-1f2a3b4c5d6e",
  "data": {
    "id": "8b1f2c4d-6e7a-4b9c-8d0e-1f2a3b4c5d6e",
    "verifiedCredentials": [
      { "format": "blockchain", "chain": "eip155", "address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01" }
    ]
  }
}

Any other provider

Any JSON object works as long as it carries the user id in one of the fields above and the wallets in address-like fields.

Generic

{
  "type": "signup",
  "userId": "u_8412",
  "wallet": { "publicKey": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW" }
}

Example

curl -X POST "https://api-id.cabalspy.xyz/v1/inbound/csin_r8Tq2..." \
  -H "Content-Type: application/json" \
  -d '{"event": "user.created", "external_id": "user_8412", "wallets": ["7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW"]}'

Response

Every event that reaches your instance is answered with 200, also when it is rejected for a business reason, such as a missing user id, an invalid address or your plan’s user limit. Providers retry deliveries that are not answered with 2xx, so this keeps them from retrying events that would fail again. Check accepted.

boolean

Whether the event was processed.

string

created, updated, deleted, wallets_removed, ignored (a wallet removal from an auth provider), unknown_user (deletion or wallet removal for a user you do not have) or waiting_for_wallet.

string

The user id read from the event.

string

created and updated: the user’s CabalSpy ID account id.

array

created and updated: the wallets and chains that are new.

array

wallets_removed: the addresses removed. wallets_not_removed: {address, code} for each one kept, for example last_wallet or wallet_not_found.

boolean

deleted: as in Delete a user.

object

When accepted is false: code and message, the same codes as Create or update a user.

{
  "success": true,
  "data": {
    "accepted": true,
    "result": "created",
    "external_id": "user_8412",
    "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "wallets_added": [
      { "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW", "family": "solana", "chains": ["solana"], "source": null }
    ]
  },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-10-26T08:04:11Z" }
}

{
  "success": true,
  "data": {
    "accepted": false,
    "error": {
      "code": "plan_user_limit",
      "message": "Your Starter plan allows 200 users and all of them are taken (200 on example.com). Upgrade the plan to add more users."
    }
  },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-10-26T08:04:11Z" }
}

Rate limit and retries

The inbound URL accepts 600 events per minute per instance, counted in fixed one-minute windows. Above that, events are not processed and answered with 429 rate_limited. Your provider retries them on its own schedule (Privy and Dynamic retry failed deliveries with a backoff). Retries are safe: an event creates or updates the user, so a repeated event changes nothing. When you send events from your own backend, retry 429 answers after the next full minute. Other non-2xx answers:

Status	Code	Meaning
400	invalid_body	The body is not JSON.
404	invalid_inbound_url	The URL is unknown, was replaced or is disabled.
429	rate_limited	More than 600 events in the current minute.

The inbound URL does not count towards your API key’s request rate. To import an existing user base, use Import instead.

Introduction

Login

Data API

Users

Trading

Theses

Streams

White-Label

Competitions

Reference

Enable

Status

Disable

Send events

CabalSpy ID format

Privy

Dynamic

Any other provider

Example

Response

Rate limit and retries

​Enable

​Status

​Disable

​Send events

​CabalSpy ID format

​Privy

​Dynamic

​Any other provider

​Example

​Response

​Rate limit and retries

Enable

Status

Disable

Send events

CabalSpy ID format

Privy

Dynamic

Any other provider

Example

Response

Rate limit and retries