Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,25 @@ All notable changes to this package are documented here. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
[Semantic Versioning](https://semver.org/).

## [0.10.0] - 2026-11-08

One person, one CabalSpy ID. A platform may create an account for its user, but the person
owns it: when they prove through your platform (X, Telegram or a paid wallet) an identity
their own CabalSpy ID holds, your link moves to that ID; when they sign in themselves, they
manage it. Your `external_id` always stays.

### Added

- Webhook events `platform_user.merged` (`previous_csid_id`, `reason`, `skipped_wallets`),
`platform_user.self_managed` and `platform_user.telegram_linked` in `PLATFORM_WEBHOOK_EVENTS`.
- `PlatformUser` fields `self_managed`, `self_managed_at` and `merged_from`.

### Deprecated

- `platform_user_claim_link()`: claim links are gone, the API answers 410 `claim_removed`.
`claimed` / `claimed_at` are the old names of `self_managed` / `self_managed_at`;
`platform_user.claimed` is no longer sent.

## [0.9.1] - 2026-11-08

### Fixed
Expand Down
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,7 @@ except RateLimitError as err:
| `PermissionError` | 403 | `invalid_api_key`, `product_not_enabled`, `no_instance`, `scope_not_allowed`, `claim_disabled`, `feature_not_enabled`, `kol_only`, `not_a_holder`, `invalid_account`, `posting_paused`, `consent_required`, `sandbox_user`, `trading_private` |
| `PlanUserLimitError` | 403 | `plan_user_limit` |
| `NotFoundError` | 404 | `profile_not_found`, `wallet_not_found`, `instance_not_found`, `platform_user_not_found`, `verification_not_found`, `competition_not_found`, `callout_not_found`, `trader_not_found`, `not_in_trade_feed`, `not_found` |
| `ConflictError` | 409 | `account_claimed`, `last_wallet`, `too_many_wallets`, `wallet_already_verified`, `kol_badge`, `x_required`, `kol_not_eligible`, `competition_limit`, `competition_closed`, `competition_full`, `late_join_closed`, `already_called`, `copy_managed_elsewhere`, `already_reported`, `trade_feed_full` |
| `ConflictError` | 409 | `self_managed`, `already_linked`, `last_wallet`, `too_many_wallets`, `wallet_already_verified`, `kol_badge`, `x_required`, `kol_not_eligible`, `competition_limit`, `competition_closed`, `competition_full`, `late_join_closed`, `already_called`, `copy_managed_elsewhere`, `already_reported`, `trade_feed_full` |
| `RateLimitError` | 429 | `rate_limit_exceeded`, `rate_limited` (also the Trade Feed's 120 changes per hour; not retried), `too_many_open_verifications`, `callout_cooldown` |
| `ServerError` | 5xx | `internal_error`, `service_unavailable` |
| `APIConnectionError` | – | network failure, timeout |
Expand Down Expand Up @@ -302,7 +302,7 @@ Every platform-users method that takes a user accepts the `external_id` position
| `platform_settings()` / `update_platform_settings(...)` | `GET` / `POST /v1/platform-users/settings` |
| `platform_inbound()` / `enable_platform_inbound()` / `disable_platform_inbound()` | `/v1/platform-users/inbound[/enable\|/disable]` |
| `platform_user_session(external_id)` | `POST /v1/platform-users/session` (verify widget, 15 min) |
| `platform_user_claim_link(external_id, return_url=)` | `POST /v1/platform-users/claim-link` |
| ~~`platform_user_claim_link()`~~ | removed: 410 `claim_removed` (one CabalSpy ID per person, see below) |
| `connect_platform_user_x(external_id, return_url=)` / `disconnect_platform_user_x(external_id)` | `POST /v1/platform-users/x/connect`, `/x/disconnect` |
| `link_platform_user_telegram` / `platform_user_telegram` / `unlink_platform_user_telegram` | `/v1/platform-users/telegram[/link\|/unlink]` |
| `platform_user_kol` / `request_platform_user_volume_check` / `apply_platform_user_kol` | `/v1/platform-users/kol[/volume-check\|/apply]` |
Expand All @@ -328,7 +328,9 @@ Individual competitions between your platform users, at most 5 scheduled + runni

The competition routes page by `offset`; the `iter_*` helpers walk them until `pagination.total`.

Webhooks: `platform_user.created`, `platform_user.claimed`, `platform_user.x_connected`, `wallet.added`, `verification.expired`, and per instance `competition.started`, `competition.updated`, `competition.standings`, `competition.ended` (`PLATFORM_WEBHOOK_EVENTS`, `COMPETITION_WEBHOOK_EVENTS`).
**One person, one CabalSpy ID.** You may create an account for your user, but the person owns it: when they connect X or Telegram, or verify a wallet, that their own CabalSpy ID already holds, your link moves there (`platform_user.merged` with the new `csid_id`; your `external_id` stays), and once they sign in themselves they manage profile, X and Telegram (`platform_user.self_managed`, `self_managed: True`). Wallets you report stay yours: other platforms do not see them.

Webhooks: `platform_user.created`, `platform_user.merged`, `platform_user.self_managed`, `platform_user.x_connected`, `platform_user.telegram_linked`, `wallet.added`, `verification.expired`, and per instance `competition.started`, `competition.updated`, `competition.standings`, `competition.ended` (`PLATFORM_WEBHOOK_EVENTS`, `COMPETITION_WEBHOOK_EVENTS`).

## Callouts (on request)

Expand Down Expand Up @@ -667,7 +669,7 @@ The server sends a heartbeat every 30 seconds. The client reconnects with expone

## Webhooks

Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com) spec (`webhook-id`, `webhook-timestamp`, `webhook-signature`, secret `whsec_...`) and are retried for about 2 days. Events: `wallet.verified`, `wallet.removed`, `profile.updated`, `kol.granted`, `consent.revoked`, `thesis.created`, `thesis.reply`, `thesis.reaction` — only for users within the plan's limit. White-label adds `platform_user.created`, `platform_user.claimed`, `platform_user.x_connected`, `wallet.added`, `verification.expired` and the instance-level `competition.started`, `competition.updated`, `competition.standings`, `competition.ended` (these carry `competition_id` instead of `sub`). Callouts add `callout.created`, `callout.milestone`, `callout.scored`, `callout.final` (`data.callout`; `CALLOUT_WEBHOOK_EVENTS`). Copy trading adds `copy_trade.instruction` (one per user and copied trade; `data` is the instruction plus `external_id`; `COPY_TRADING_WEBHOOK_EVENTS`). The Trade Feed adds `trade_feed.trade` and `trade_feed.thesis` (one per trade or thesis, not per user; `data` is the feed item plus `recipients` and `recipients_external`; `TradeFeedTradeEvent` / `TradeFeedThesisEvent`; `TRADE_FEED_WEBHOOK_EVENTS`).
Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com) spec (`webhook-id`, `webhook-timestamp`, `webhook-signature`, secret `whsec_...`) and are retried for about 2 days. Events: `wallet.verified`, `wallet.removed`, `profile.updated`, `kol.granted`, `consent.revoked`, `thesis.created`, `thesis.reply`, `thesis.reaction` — only for users within the plan's limit. White-label adds `platform_user.created`, `platform_user.merged`, `platform_user.self_managed`, `platform_user.x_connected`, `platform_user.telegram_linked`, `wallet.added`, `verification.expired` and the instance-level `competition.started`, `competition.updated`, `competition.standings`, `competition.ended` (these carry `competition_id` instead of `sub`). Callouts add `callout.created`, `callout.milestone`, `callout.scored`, `callout.final` (`data.callout`; `CALLOUT_WEBHOOK_EVENTS`). Copy trading adds `copy_trade.instruction` (one per user and copied trade; `data` is the instruction plus `external_id`; `COPY_TRADING_WEBHOOK_EVENTS`). The Trade Feed adds `trade_feed.trade` and `trade_feed.thesis` (one per trade or thesis, not per user; `data` is the feed item plus `recipients` and `recipients_external`; `TradeFeedTradeEvent` / `TradeFeedThesisEvent`; `TRADE_FEED_WEBHOOK_EVENTS`).

```python
from cabalspy_id import verify_webhook
Expand Down
8 changes: 4 additions & 4 deletions cabalspy_id/_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -1206,11 +1206,11 @@ def platform_user_session(self, external_id: str | None = None, *, csid_id: str
def platform_user_claim_link(
self, external_id: str | None = None, *, return_url: str | None = None, csid_id: str | None = None
) -> Any:
"""POST /v1/platform-users/claim-link — a 24-hour link that lets the person take the account
into their own CabalSpy ID. ``return_url`` must be on your verified domains or registered
origins. Off with ``white_label`` unless ``claim_links`` is on (``claim_disabled``).
"""Deprecated: claim links are gone, the API answers 410 ``claim_removed``.

Returns :class:`~cabalspy_id.PlatformClaimLink`.
A CabalSpy ID is one account for every platform now: your link moves to the person's
own ID by itself when they connect X or Telegram or verify a wallet it holds (webhook
``platform_user.merged``; your ``external_id`` stays).
"""
body = _who(external_id, csid_id)
if return_url:
Expand Down
5 changes: 4 additions & 1 deletion cabalspy_id/_constants.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

from typing import Literal

SDK_VERSION = "0.9.1"
SDK_VERSION = "0.10.0"
USER_AGENT = f"cabalspy-id-python/{SDK_VERSION}"

DEFAULT_BASE_URL = "https://api-id.cabalspy.xyz/v1"
Expand Down Expand Up @@ -43,8 +43,11 @@
#: Webhook events about platform users (white-label). ``data.sub`` is the user's csid_id.
PLATFORM_WEBHOOK_EVENTS: tuple[str, ...] = (
"platform_user.created",
"platform_user.merged",
"platform_user.self_managed",
"platform_user.claimed",
"platform_user.x_connected",
"platform_user.telegram_linked",
"wallet.added",
"verification.expired",
)
Expand Down
9 changes: 8 additions & 1 deletion cabalspy_id/_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -858,10 +858,17 @@ class PlatformUser(TypedDict):

csid_id: str
external_id: str
#: True once the person took the account into their own CabalSpy ID (claim link).
#: The person signs in to their CabalSpy ID themselves and manages profile, X and
#: Telegram; you can still report wallets for them.
self_managed: bool
self_managed_at: str | None
#: Deprecated: old names of ``self_managed`` / ``self_managed_at``.
claimed: bool
claimed_at: str | None
#: Created by a platform and not taken over by the person yet.
managed: bool
#: The platform account this link moved from when the person proved their own CabalSpy ID.
merged_from: str | None
display_name: str | None
avatar_url: str | None
#: Beyond the plan's user limit: no data until the platform upgrades.
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "hatchling.build"

[project]
name = "cabalspy-id"
version = "0.9.1"
version = "0.10.0"
description = "SocialFi API & SDK for CabalSpy ID — add a social layer to any app: login with X + verified wallets, live trades and PnL of your users, token theses, leaderboards and copy trading on Solana, BNB Chain, Base, Ethereum and Robinhood Chain."
readme = "README.md"
license = "MIT"
Expand Down
2 changes: 1 addition & 1 deletion tests/test_trade_feed.py
Original file line number Diff line number Diff line change
Expand Up @@ -375,7 +375,7 @@ def test_trade_feed_webhook_events() -> None:
def test_exports() -> None:
import cabalspy_id

assert cabalspy_id.__version__ == "0.9.1"
assert cabalspy_id.__version__ == "0.10.0"
assert api.TradeFeedStream is cabalspy_id.TradeFeedStream
assert cabalspy_id.TRADE_FEED_EVENTS == ("trade_feed.trade", "trade_feed.thesis")
assert "ready" in cabalspy_id.TRADE_FEED_STREAM_EVENTS
Expand Down
Loading