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
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,20 @@ 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.9.1] - 2026-11-08

### Fixed

- Theses in the name of a platform user: `thesis_eligibility`, `post_thesis`, `reply_to_thesis`,
`react_to_thesis`, `report_thesis`, `delete_thesis`, `thesis_notifications` and
`appeal_thesis_decision` take `external_id=` in place of `csid_id` (they accepted only
`csid_id` before). Exactly one of the two.

### Added

- `history(mint=)`: only the trades of one token, for example to mark a user's buys and sells on
a price chart. History trades carry `token_amount` and `price_usd`.

## [0.9.0] - 2026-11-01

Trade Feed: read and manage your users' Trade Feeds from your backend (the traders they follow,
Expand Down
20 changes: 10 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ The API key is the **same key as the CabalSpy API**, with the per-key toggle "Ca
| `profile(username= \| csid_id= \| address=)` | `GET /v1/profile` |
| `wallet_lookup(address)` | `GET /v1/wallets/lookup` |
| `tracker(blockchain=, address=, period=)` | `GET /v1/wallets/tracker` |
| `history(blockchain=, address=, limit=, cursor=)` | `GET /v1/wallets/history` |
| `history(blockchain=, address=, limit=, cursor=, mint=)` | `GET /v1/wallets/history` |
| `holdings(blockchain=, address=)` | `GET /v1/wallets/holdings` |
| `pnl_calendar(blockchain=, address=)` | `GET /v1/wallets/pnl_calendar` |
| `leaderboard(blockchain=, period=, sort=, limit=, cursor=, scope=)` | `GET /v1/wallets/leaderboard` |
Expand Down Expand Up @@ -558,15 +558,15 @@ if ok["can_post"]:
| `thesis_replies(id, limit=, cursor=)` / `iter_thesis_replies()` | `GET /v1/theses/replies` |
| `latest_theses(blockchain=, users="all" \| "instance", limit=, cursor=)` | `GET /v1/theses/latest` |
| `user_theses(csid_id= \| username=)` | `GET /v1/theses/user` |
| `thesis_eligibility(blockchain=, mint=, csid_id=)` | `GET /v1/theses/eligibility` |
| `post_thesis(blockchain=, mint=, body=, stance=, csid_id=)` | `POST /v1/theses` |
| `reply_to_thesis(thesis_id=, body=, csid_id=)` | `POST /v1/theses/replies` |
| `react_to_thesis(thesis_id=, emoji=, on=, csid_id=)` | `POST /v1/theses/reactions` |
| `report_thesis(thesis_id=, reason=, note=, csid_id=)` | `POST /v1/theses/report` |
| `delete_thesis(thesis_id=, csid_id=)` | `POST /v1/theses/delete` |

| `thesis_notifications(csid_id)` | `GET /v1/theses/notifications` |
| `appeal_thesis_decision(csid_id, notification_id, message)` | `POST /v1/theses/appeal` |
| `thesis_eligibility(blockchain=, mint=, csid_id= \| external_id=)` | `GET /v1/theses/eligibility` |
| `post_thesis(blockchain=, mint=, body=, stance=, csid_id= \| external_id=)` | `POST /v1/theses` |
| `reply_to_thesis(thesis_id=, body=, csid_id= \| external_id=)` | `POST /v1/theses/replies` |
| `react_to_thesis(thesis_id=, emoji=, on=, csid_id= \| external_id=)` | `POST /v1/theses/reactions` |
| `report_thesis(thesis_id=, reason=, note=, csid_id= \| external_id=)` | `POST /v1/theses/report` |
| `delete_thesis(thesis_id=, csid_id= \| external_id=)` | `POST /v1/theses/delete` |

| `thesis_notifications(csid_id \| external_id=)` | `GET /v1/theses/notifications` |
| `appeal_thesis_decision(csid_id, notification_id, message, external_id=)` | `POST /v1/theses/appeal` |

Every thesis carries `reacted_by` (the latest reactions with who reacted) and, for theses, `latest_replies` (a preview of the newest replies).

Expand Down
93 changes: 64 additions & 29 deletions cabalspy_id/_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -678,16 +678,25 @@ def history(
limit: int | None = None,
cursor: str | None = None,
scope: Scope | None = None,
mint: str | None = None,
) -> Any:
"""GET /v1/wallets/history — lifetime stats, token overview and one page
of trades (``limit`` 1-1000, default 500).
of trades (``limit`` 1-1000, default 500). ``mint``: only the trades of
this token (the stats then cover this token only).

Returns :class:`~cabalspy_id.HistoryResponse`.
"""
_wallet(blockchain, address)
return self._get(
"/wallets/history",
{"blockchain": blockchain, "address": address, "limit": limit, "cursor": cursor, "scope": scope},
{
"blockchain": blockchain,
"address": address,
"limit": limit,
"cursor": cursor,
"scope": scope,
"mint": mint,
},
)

def holdings(self, *, blockchain: Chain, address: str, scope: Scope | None = None) -> Any:
Expand Down Expand Up @@ -847,86 +856,112 @@ def user_theses(
},
)

def thesis_eligibility(self, *, blockchain: Chain, mint: str, csid_id: str) -> Any:
def thesis_eligibility(
self, *, blockchain: Chain, mint: str, csid_id: str | None = None, external_id: str | None = None
) -> Any:
"""GET /v1/theses/eligibility — may this user post (holder, not paused) and reply here
through your app? ``reason`` says why not (consent_required, plan_user_limit, sandbox_user).

Returns :class:`~cabalspy_id.ThesisEligibility`.
"""
_token(blockchain, mint)
_required(csid_id, "csid_id")
return self._get("/theses/eligibility", {"blockchain": blockchain, "mint": mint, "csid_id": csid_id})
return self._get("/theses/eligibility", {"blockchain": blockchain, "mint": mint, **_who(external_id, csid_id)})

# Writing happens in the name of one of your users: ``csid_id`` is the ``sub``
# of their ID token. They must have signed in with the scope "thesis".
# of their ID token (they signed in with the scope "thesis"), or
# ``external_id`` for a platform user (white-label). Exactly one of them.

def post_thesis(
self, *, blockchain: Chain, mint: str, body: str, csid_id: str, stance: ThesisStance | None = None
self,
*,
blockchain: Chain,
mint: str,
body: str,
csid_id: str | None = None,
external_id: str | None = None,
stance: ThesisStance | None = None,
) -> Any:
"""POST /v1/theses — posts a thesis (up to 1000 characters). Holders only (``not_a_holder``)."""
_token(blockchain, mint)
_required(body, "body")
_required(csid_id, "csid_id")
who = _who(external_id, csid_id)
_one_of(stance, ("bull", "bear"), "stance")
payload: dict[str, Any] = {"blockchain": blockchain, "mint": mint, "body": body, "csid_id": csid_id}
payload: dict[str, Any] = {"blockchain": blockchain, "mint": mint, "body": body, **who}
if stance:
payload["stance"] = stance
return self._post("/theses", payload)

def reply_to_thesis(self, *, thesis_id: str, body: str, csid_id: str) -> Any:
def reply_to_thesis(
self, *, thesis_id: str, body: str, csid_id: str | None = None, external_id: str | None = None
) -> Any:
"""POST /v1/theses/replies — replies to a thesis."""
_required(thesis_id, "thesis_id")
_required(body, "body")
_required(csid_id, "csid_id")
return self._post("/theses/replies", {"thesis_id": thesis_id, "body": body, "csid_id": csid_id})
return self._post("/theses/replies", {"thesis_id": thesis_id, "body": body, **_who(external_id, csid_id)})

def react_to_thesis(self, *, thesis_id: str, emoji: ThesisEmoji, csid_id: str, on: bool = True) -> Any:
def react_to_thesis(
self,
*,
thesis_id: str,
emoji: ThesisEmoji,
csid_id: str | None = None,
external_id: str | None = None,
on: bool = True,
) -> Any:
"""POST /v1/theses/reactions — adds (or with ``on=False`` removes) a reaction.

Returns ``{"id", "reactions"}`` with the new counts.
"""
_required(thesis_id, "thesis_id")
_one_of(emoji, THESIS_EMOJIS, "emoji")
_required(csid_id, "csid_id")
return self._post("/theses/reactions", {"thesis_id": thesis_id, "emoji": emoji, "on": on, "csid_id": csid_id})
who = _who(external_id, csid_id)
return self._post("/theses/reactions", {"thesis_id": thesis_id, "emoji": emoji, "on": on, **who})

def report_thesis(
self, *, thesis_id: str, reason: ThesisReportReason, csid_id: str, note: str | None = None
self,
*,
thesis_id: str,
reason: ThesisReportReason,
csid_id: str | None = None,
external_id: str | None = None,
note: str | None = None,
) -> Any:
"""POST /v1/theses/report — reports a post (hidden for review after 3 reports)."""
_required(thesis_id, "thesis_id")
_one_of(reason, THESIS_REPORT_REASONS, "reason")
_required(csid_id, "csid_id")
payload: dict[str, Any] = {"thesis_id": thesis_id, "reason": reason, "csid_id": csid_id}
payload: dict[str, Any] = {"thesis_id": thesis_id, "reason": reason, **_who(external_id, csid_id)}
if note:
payload["note"] = note
return self._post("/theses/report", payload)

def thesis_notifications(self, csid_id: str) -> Any:
def thesis_notifications(self, csid_id: str | None = None, *, external_id: str | None = None) -> Any:
"""GET /v1/theses/notifications — moderation notifications of one of your users
(warnings, hidden posts, pauses, appeal results), with the unread count.

Returns :class:`~cabalspy_id.ThesisNotifications`.
"""
_required(csid_id, "csid_id")
return self._get("/theses/notifications", {"csid_id": csid_id})
return self._get("/theses/notifications", _who(external_id, csid_id))

def appeal_thesis_decision(self, csid_id: str, notification_id: int, message: str) -> Any:
def appeal_thesis_decision(
self,
csid_id: str | None = None,
notification_id: int | None = None,
message: str | None = None,
*,
external_id: str | None = None,
) -> Any:
"""POST /v1/theses/appeal — appeals a moderation decision in the user's name
(an ``appealable`` notification, within 30 days; message 10-1000 characters).
"""
_required(csid_id, "csid_id")
who = _who(external_id, csid_id)
_required(notification_id, "notification_id")
_required(message, "message")
return self._post(
"/theses/appeal", {"csid_id": csid_id, "notification_id": notification_id, "message": message}
)
return self._post("/theses/appeal", {**who, "notification_id": notification_id, "message": message})

def delete_thesis(self, *, thesis_id: str, csid_id: str) -> Any:
def delete_thesis(self, *, thesis_id: str, csid_id: str | None = None, external_id: str | None = None) -> Any:
"""POST /v1/theses/delete — deletes the user's own thesis or reply."""
_required(thesis_id, "thesis_id")
_required(csid_id, "csid_id")
return self._post("/theses/delete", {"thesis_id": thesis_id, "csid_id": csid_id})
return self._post("/theses/delete", {"thesis_id": thesis_id, **_who(external_id, csid_id)})

# ── white-label: platform users ──────────────────────────────────────
# Your platform keeps its own login and addresses its users by its own user
Expand Down
2 changes: 1 addition & 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.0"
SDK_VERSION = "0.9.1"
USER_AGENT = f"cabalspy-id-python/{SDK_VERSION}"

DEFAULT_BASE_URL = "https://api-id.cabalspy.xyz/v1"
Expand Down
4 changes: 4 additions & 0 deletions cabalspy_id/_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,10 @@ class HistoryTrade(TypedDict):
value: float
value_usd: float
currency: Currency
token_amount: float | None
"""Tokens bought or sold."""
price_usd: float | None
"""USD price per token at the trade (value_usd / token_amount)."""
created_at: str


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.0"
version = "0.9.1"
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
35 changes: 35 additions & 0 deletions tests/test_theses.py
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,41 @@ def handler(r: httpx.Request) -> httpx.Response:
assert rec.requests[0].headers["content-type"] == "application/json"


def test_platform_user_writes_by_external_id() -> None:
def handler(r: httpx.Request) -> httpx.Response:
if r.url.path.endswith("/reactions"):
return ok({"id": "t1", "reactions": {"like": 1}})
if r.url.path.endswith("/eligibility"):
return ok({"can_post": True, "can_reply": True, "holder": True, "paused": False})
if r.url.path.endswith("/notifications"):
return ok({"unread": 0, "items": []})
return ok(thesis())

csid, rec = make(handler)
csid.thesis_eligibility(blockchain="solana", mint=MINT, external_id="user_1")
csid.post_thesis(blockchain="solana", mint=MINT, body="gm", external_id="user_1")
csid.reply_to_thesis(thesis_id="t1", body="Nice call", external_id="user_2")
csid.react_to_thesis(thesis_id="t1", emoji="like", external_id="user_2")
csid.thesis_notifications(external_id="user_1")
csid.thesis_notifications(USER)
assert [(r.method, pq(r), json.loads(r.content) if r.content else None) for r in rec.requests] == [
("GET", f"/v1/theses/eligibility?blockchain=solana&mint={MINT}&external_id=user_1", None),
("POST", "/v1/theses?", {"blockchain": "solana", "mint": MINT, "body": "gm", "external_id": "user_1"}),
("POST", "/v1/theses/replies?", {"thesis_id": "t1", "body": "Nice call", "external_id": "user_2"}),
("POST", "/v1/theses/reactions?", {"thesis_id": "t1", "emoji": "like", "on": True, "external_id": "user_2"}),
("GET", "/v1/theses/notifications?external_id=user_1", None),
("GET", f"/v1/theses/notifications?csid_id={USER}", None),
]
with pytest.raises(BadRequestError):
csid.post_thesis(blockchain="solana", mint=MINT, body="x", csid_id=USER, external_id="u")


def test_history_mint_filter() -> None:
csid, rec = make(lambda r: ok({"trades": []}))
csid.history(blockchain="solana", address=MINT, mint="TokenMint1")
assert pq(rec.requests[0]) == f"/v1/wallets/history?blockchain=solana&address={MINT}&mint=TokenMint1"


def test_validation() -> None:
csid, rec = make(lambda r: ok({}))
with pytest.raises(BadRequestError):
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.0"
assert cabalspy_id.__version__ == "0.9.1"
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