cabalspy 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,8 +1,8 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: cabalspy
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: KOL and smart money wallet tracking API for Solana, Base, BNB Chain, Ethereum and Robinhood Chain. Realtime KOL trades, whale wallets, copy-trading signals, bundle detection, token holders and PnL over REST and WebSocket.
5
- Project-URL: Homepage, https://docs.cabalspy.xyz
5
+ Project-URL: Homepage, https://www.cabalspy.xyz/sdks/
6
6
  Project-URL: Documentation, https://docs.cabalspy.xyz
7
7
  Project-URL: Repository, https://github.com/CabalSpy/cabalspy-python
8
8
  Project-URL: Issues, https://github.com/CabalSpy/cabalspy-python/issues
@@ -54,6 +54,30 @@ pip install "cabalspy[realtime]"
54
54
 
55
55
  **What you can build with it:** copy-trading bots, KOL leaderboards, memecoin alert systems, wallet analytics dashboards, bundle and sniper detection, portfolio and PnL trackers.
56
56
 
57
+ ## Try it without signing up
58
+
59
+ The public demo key works on every endpoint and on the websocket, with no account:
60
+
61
+ ```python
62
+ from cabalspy import CabalSpy
63
+
64
+ client = CabalSpy.demo()
65
+ wallets = client.wallets.list(blockchain="solana", type="kol")
66
+ print(client.last_demo["remaining_today"])
67
+ ```
68
+
69
+ Or keyless, straight from a terminal:
70
+
71
+ ```bash
72
+ curl "https://demo-api.cabalspy.xyz/v1/wallets?blockchain=solana&type=kol"
73
+ ```
74
+
75
+ - 20 requests per IP per UTC day, shared between REST and WebSocket (each connection counts as 1)
76
+ - Data is 15 minutes delayed, at most 5 rows per list, no pagination
77
+ - WebSocket: 1 connection per IP, up to 3 subscriptions, closed after 30 minutes
78
+
79
+ Every demo response carries a `demo` object (`notice`, `remaining_today`, `upgrade`), exposed as `client.last_demo` and `Envelope.demo`. A spent budget raises `DemoLimitError` with `.resets_in_seconds` and `.upgrade`. For real-time data, get a free test key (1,000 requests per month) at [apidashboard.cabalspy.xyz](https://apidashboard.cabalspy.xyz/), or pay per call with x402 via [`cabalspy-x402`](https://pypi.org/project/cabalspy-x402/).
80
+
57
81
  ## Quick start
58
82
 
59
83
  ```python
@@ -222,12 +246,13 @@ except RateLimitError as exc:
222
246
  | `InsufficientCreditsError` | 403 | `insufficient_credits` |
223
247
  | `NotFoundError` | 404 | `wallet_not_found`, `token_not_found` |
224
248
  | `RateLimitError` | 429 | `rate_limit_exceeded` |
249
+ | `DemoLimitError` | 429 | `demo_limit_reached` (subclass of `RateLimitError`) |
225
250
  | `ServerError` | 5xx | `internal_error`, `service_unavailable` |
226
251
  | `APIConnectionError` | – | network failure, timeout |
227
252
 
228
253
  Every error carries `.code`, `.request_id` and `.docs`; `BadRequestError` also carries `.parameter` and `.allowed`.
229
254
 
230
- `429`, `5xx` and network errors are retried automatically with exponential backoff and jitter. A server-sent `Retry-After` wins over the SDK's own backoff.
255
+ `429` (except `demo_limit_reached`), `5xx` and network errors are retried automatically with exponential backoff and jitter. A server-sent `Retry-After` wins over the SDK's own backoff.
231
256
 
232
257
  ```python
233
258
  client = CabalSpy(max_retries=3, timeout=15.0)
@@ -294,6 +319,14 @@ data = client.post_raw("/some/new/endpoint", {"foo": "bar"}).data
294
319
 
295
320
  Full API reference: [docs.cabalspy.xyz](https://docs.cabalspy.xyz) · free API key: [apidashboard.cabalspy.xyz](https://apidashboard.cabalspy.xyz/)
296
321
 
322
+ ## Related
323
+
324
+ - [SDK overview](https://www.cabalspy.xyz/sdks/) on cabalspy.xyz · [KOL API](https://www.cabalspy.xyz/kol-api/) · [Smart Money API](https://www.cabalspy.xyz/smart-money-api/) · [use cases](https://www.cabalspy.xyz/use-cases/)
325
+ - SDKs: [TypeScript](https://www.npmjs.com/package/cabalspy) · [Python](https://pypi.org/project/cabalspy/) · [Rust](https://crates.io/crates/cabalspy)
326
+ - x402 clients (pay per request, no API key): [TypeScript](https://www.npmjs.com/package/cabalspy-x402) · [Python](https://pypi.org/project/cabalspy-x402/)
327
+ - [MCP server](https://www.cabalspy.xyz/mcp/) — for Claude, Cursor and VS Code
328
+ - [CabalSpy Terminal](https://app.cabalspy.xyz/) — trade with the same wallet data
329
+
297
330
  ## License
298
331
 
299
332
  MIT
@@ -16,6 +16,30 @@ pip install "cabalspy[realtime]"
16
16
 
17
17
  **What you can build with it:** copy-trading bots, KOL leaderboards, memecoin alert systems, wallet analytics dashboards, bundle and sniper detection, portfolio and PnL trackers.
18
18
 
19
+ ## Try it without signing up
20
+
21
+ The public demo key works on every endpoint and on the websocket, with no account:
22
+
23
+ ```python
24
+ from cabalspy import CabalSpy
25
+
26
+ client = CabalSpy.demo()
27
+ wallets = client.wallets.list(blockchain="solana", type="kol")
28
+ print(client.last_demo["remaining_today"])
29
+ ```
30
+
31
+ Or keyless, straight from a terminal:
32
+
33
+ ```bash
34
+ curl "https://demo-api.cabalspy.xyz/v1/wallets?blockchain=solana&type=kol"
35
+ ```
36
+
37
+ - 20 requests per IP per UTC day, shared between REST and WebSocket (each connection counts as 1)
38
+ - Data is 15 minutes delayed, at most 5 rows per list, no pagination
39
+ - WebSocket: 1 connection per IP, up to 3 subscriptions, closed after 30 minutes
40
+
41
+ Every demo response carries a `demo` object (`notice`, `remaining_today`, `upgrade`), exposed as `client.last_demo` and `Envelope.demo`. A spent budget raises `DemoLimitError` with `.resets_in_seconds` and `.upgrade`. For real-time data, get a free test key (1,000 requests per month) at [apidashboard.cabalspy.xyz](https://apidashboard.cabalspy.xyz/), or pay per call with x402 via [`cabalspy-x402`](https://pypi.org/project/cabalspy-x402/).
42
+
19
43
  ## Quick start
20
44
 
21
45
  ```python
@@ -184,12 +208,13 @@ except RateLimitError as exc:
184
208
  | `InsufficientCreditsError` | 403 | `insufficient_credits` |
185
209
  | `NotFoundError` | 404 | `wallet_not_found`, `token_not_found` |
186
210
  | `RateLimitError` | 429 | `rate_limit_exceeded` |
211
+ | `DemoLimitError` | 429 | `demo_limit_reached` (subclass of `RateLimitError`) |
187
212
  | `ServerError` | 5xx | `internal_error`, `service_unavailable` |
188
213
  | `APIConnectionError` | – | network failure, timeout |
189
214
 
190
215
  Every error carries `.code`, `.request_id` and `.docs`; `BadRequestError` also carries `.parameter` and `.allowed`.
191
216
 
192
- `429`, `5xx` and network errors are retried automatically with exponential backoff and jitter. A server-sent `Retry-After` wins over the SDK's own backoff.
217
+ `429` (except `demo_limit_reached`), `5xx` and network errors are retried automatically with exponential backoff and jitter. A server-sent `Retry-After` wins over the SDK's own backoff.
193
218
 
194
219
  ```python
195
220
  client = CabalSpy(max_retries=3, timeout=15.0)
@@ -256,6 +281,14 @@ data = client.post_raw("/some/new/endpoint", {"foo": "bar"}).data
256
281
 
257
282
  Full API reference: [docs.cabalspy.xyz](https://docs.cabalspy.xyz) · free API key: [apidashboard.cabalspy.xyz](https://apidashboard.cabalspy.xyz/)
258
283
 
284
+ ## Related
285
+
286
+ - [SDK overview](https://www.cabalspy.xyz/sdks/) on cabalspy.xyz · [KOL API](https://www.cabalspy.xyz/kol-api/) · [Smart Money API](https://www.cabalspy.xyz/smart-money-api/) · [use cases](https://www.cabalspy.xyz/use-cases/)
287
+ - SDKs: [TypeScript](https://www.npmjs.com/package/cabalspy) · [Python](https://pypi.org/project/cabalspy/) · [Rust](https://crates.io/crates/cabalspy)
288
+ - x402 clients (pay per request, no API key): [TypeScript](https://www.npmjs.com/package/cabalspy-x402) · [Python](https://pypi.org/project/cabalspy-x402/)
289
+ - [MCP server](https://www.cabalspy.xyz/mcp/) — for Claude, Cursor and VS Code
290
+ - [CabalSpy Terminal](https://app.cabalspy.xyz/) — trade with the same wallet data
291
+
259
292
  ## License
260
293
 
261
294
  MIT
@@ -6,6 +6,7 @@ Ethereum and Robinhood Chain.
6
6
  from cabalspy import CabalSpy
7
7
 
8
8
  client = CabalSpy() # reads CABALSPY_API_KEY
9
+ client = CabalSpy.demo() # or try it without a key
9
10
  board = client.wallets.leaderboard(blockchain="solana", period="7d", limit=25)
10
11
 
11
12
  Async and realtime:
@@ -20,7 +21,7 @@ Async and realtime:
20
21
  Docs: https://docs.cabalspy.xyz
21
22
  """
22
23
 
23
- from ._client import AsyncCabalSpy, CabalSpy, Envelope
24
+ from ._client import DEMO_API_KEY, AsyncCabalSpy, CabalSpy, Envelope
24
25
  from ._constants import (
25
26
  ANALYTICS_MODES,
26
27
  BATCH_MAX_ADDRESSES,
@@ -48,6 +49,7 @@ from ._errors import (
48
49
  AuthenticationError,
49
50
  BadRequestError,
50
51
  CabalSpyError,
52
+ DemoLimitError,
51
53
  InsufficientCreditsError,
52
54
  InvalidResponseError,
53
55
  NotFoundError,
@@ -70,6 +72,8 @@ from ._types import (
70
72
  BundleWallet,
71
73
  ClusterSignal,
72
74
  CountResponse,
75
+ DemoInfo,
76
+ DemoUpgrade,
73
77
  FeedTransaction,
74
78
  HealthResponse,
75
79
  HoldingsAfter,
@@ -92,7 +96,7 @@ from ._types import (
92
96
  WinRateDistribution,
93
97
  )
94
98
 
95
- __version__ = "0.2.0"
99
+ __version__ = "0.3.0"
96
100
 
97
101
  __all__ = [
98
102
  "__version__",
@@ -109,11 +113,13 @@ __all__ = [
109
113
  "InsufficientCreditsError",
110
114
  "NotFoundError",
111
115
  "RateLimitError",
116
+ "DemoLimitError",
112
117
  "ServerError",
113
118
  "APIConnectionError",
114
119
  "InvalidResponseError",
115
120
  "RateLimit",
116
121
  # constants and helpers
122
+ "DEMO_API_KEY",
117
123
  "CHAINS",
118
124
  "WALLET_TYPES_BY_CHAIN",
119
125
  "CURRENCY_BY_CHAIN",
@@ -141,6 +147,8 @@ __all__ = [
141
147
  # response types
142
148
  "ResponseMeta",
143
149
  "Pagination",
150
+ "DemoInfo",
151
+ "DemoUpgrade",
144
152
  "WalletProfile",
145
153
  "TokenBlock",
146
154
  "HoldingsAfter",
@@ -37,17 +37,25 @@ from ._errors import (
37
37
  is_retryable,
38
38
  )
39
39
 
40
- __all__ = ["CabalSpy", "AsyncCabalSpy", "Envelope"]
40
+ __all__ = ["CabalSpy", "AsyncCabalSpy", "Envelope", "DEMO_API_KEY"]
41
41
 
42
42
  DEFAULT_BASE_URL = "https://api.cabalspy.xyz/v1"
43
43
  DEFAULT_WS_URL = "wss://stream.cabalspy.xyz"
44
- SDK_VERSION = "0.2.0"
44
+ SDK_VERSION = "0.3.0"
45
+
46
+ #: Public demo key. 20 requests per IP per UTC day, data 15 minutes delayed and
47
+ #: at most 5 rows per list. Use :meth:`CabalSpy.demo` rather than passing it by hand.
48
+ DEMO_API_KEY = "demo"
45
49
 
46
50
 
47
51
  class Envelope:
48
- """A full API response: data plus pagination, meta and rate limit headers."""
52
+ """A full API response: data plus pagination, meta and rate limit headers.
53
+
54
+ ``demo`` holds the top-level ``demo`` object the server adds to every response
55
+ made with the demo key (notice, remaining_today, upgrade), and is None otherwise.
56
+ """
49
57
 
50
- __slots__ = ("data", "pagination", "meta", "rate_limit", "status")
58
+ __slots__ = ("data", "pagination", "meta", "rate_limit", "status", "demo")
51
59
 
52
60
  def __init__(
53
61
  self,
@@ -56,12 +64,14 @@ class Envelope:
56
64
  meta: dict[str, Any],
57
65
  rate_limit: RateLimit,
58
66
  status: int,
67
+ demo: dict[str, Any] | None = None,
59
68
  ) -> None:
60
69
  self.data = data
61
70
  self.pagination = pagination
62
71
  self.meta = meta
63
72
  self.rate_limit = rate_limit
64
73
  self.status = status
74
+ self.demo = demo
65
75
 
66
76
  def __repr__(self) -> str:
67
77
  keys = list(self.data)[:5] if isinstance(self.data, dict) else type(self.data).__name__
@@ -537,7 +547,8 @@ class _BaseClient:
537
547
  if not key and not pays_per_call:
538
548
  raise CabalSpyError(
539
549
  "Missing credentials. Pass api_key=, set CABALSPY_API_KEY, or hand in an "
540
- "http_client that pays per call with x402.",
550
+ "http_client that pays per call with x402. To try the API without signing "
551
+ "up use CabalSpy.demo(); a free test key is at https://apidashboard.cabalspy.xyz/",
541
552
  code="missing_api_key",
542
553
  )
543
554
  self._api_key = key or ""
@@ -551,6 +562,8 @@ class _BaseClient:
551
562
  self._extra_headers = dict(headers or {})
552
563
  #: Rate limit state from the most recent request.
553
564
  self.last_rate_limit = RateLimit()
565
+ #: The ``demo`` object from the most recent response, None unless using the demo key.
566
+ self.last_demo: dict[str, Any] | None = None
554
567
 
555
568
  self.system = SystemResource(self)
556
569
  self.wallets = WalletsResource(self)
@@ -560,6 +573,11 @@ class _BaseClient:
560
573
  self.analytics = AnalyticsResource(self)
561
574
  self.bundle = BundleResource(self)
562
575
 
576
+ @property
577
+ def is_demo(self) -> bool:
578
+ """True when this client authenticates with the public demo key."""
579
+ return self._api_key == DEMO_API_KEY
580
+
563
581
  # ── plumbing shared by both clients ──────────────────────────────────
564
582
 
565
583
  def _request_headers(self, json_body: bool) -> dict[str, str]:
@@ -592,12 +610,15 @@ class _BaseClient:
592
610
 
593
611
  if response.status_code >= 400:
594
612
  body = parsed.get("error") if isinstance(parsed, dict) else None
613
+ # demo_limit_reached carries its upgrade links next to error, not inside it.
614
+ upgrade = parsed.get("upgrade") if isinstance(parsed, dict) else None
595
615
  raise error_from_status(
596
616
  response.status_code,
597
617
  body if isinstance(body, dict) else None,
598
618
  rate_limit,
599
619
  _int_header(response.headers, "Retry-After"),
600
620
  f"HTTP {response.status_code} on {method} {path}",
621
+ upgrade=upgrade if isinstance(upgrade, dict) else None,
601
622
  )
602
623
 
603
624
  if not isinstance(parsed, dict) or "data" not in parsed:
@@ -608,12 +629,15 @@ class _BaseClient:
608
629
  rate_limit=rate_limit,
609
630
  )
610
631
 
632
+ demo = parsed.get("demo")
633
+ self.last_demo = demo if isinstance(demo, dict) else None
611
634
  return Envelope(
612
635
  parsed["data"],
613
636
  parsed.get("pagination"),
614
637
  parsed.get("meta") or {},
615
638
  rate_limit,
616
639
  response.status_code,
640
+ self.last_demo,
617
641
  )
618
642
 
619
643
  def _connection_error(self, exc: Exception, method: str, path: str) -> APIConnectionError:
@@ -658,6 +682,17 @@ class CabalSpy(_BaseClient):
658
682
  self._http = http_client or httpx.Client(timeout=self.timeout)
659
683
  self._owns_http = http_client is None
660
684
 
685
+ @classmethod
686
+ def demo(cls, **options: Any) -> "CabalSpy":
687
+ """A client on the public demo key, no sign up needed.
688
+
689
+ 20 requests per IP per UTC day shared with the websocket, data 15 minutes
690
+ delayed, at most 5 rows per list. Takes the same options as the constructor.
691
+ A spent budget raises :class:`DemoLimitError`.
692
+ """
693
+ options.pop("api_key", None)
694
+ return cls(DEMO_API_KEY, **options)
695
+
661
696
  def __enter__(self) -> "CabalSpy":
662
697
  return self
663
698
 
@@ -769,6 +804,12 @@ class AsyncCabalSpy(_BaseClient):
769
804
  self._http = http_client or httpx.AsyncClient(timeout=self.timeout)
770
805
  self._owns_http = http_client is None
771
806
 
807
+ @classmethod
808
+ def demo(cls, **options: Any) -> "AsyncCabalSpy":
809
+ """Async version of :meth:`CabalSpy.demo`."""
810
+ options.pop("api_key", None)
811
+ return cls(DEMO_API_KEY, **options)
812
+
772
813
  async def __aenter__(self) -> "AsyncCabalSpy":
773
814
  return self
774
815
 
@@ -74,6 +74,28 @@ class RateLimitError(CabalSpyError):
74
74
  self.retry_after = retry_after
75
75
 
76
76
 
77
+ class DemoLimitError(RateLimitError):
78
+ """429 — demo_limit_reached. The public demo key's daily budget is spent.
79
+
80
+ Not retried: the budget only resets at the next UTC day. ``upgrade`` holds the
81
+ links to a free test key and to pay per call with x402.
82
+ """
83
+
84
+ def __init__(
85
+ self,
86
+ message: str,
87
+ *,
88
+ resets_in_seconds: int | None = None,
89
+ upgrade: dict[str, Any] | None = None,
90
+ **kwargs: Any,
91
+ ) -> None:
92
+ kwargs.setdefault("retry_after", resets_in_seconds)
93
+ super().__init__(message, **kwargs)
94
+ #: Seconds until the demo budget resets, as reported by the server.
95
+ self.resets_in_seconds = resets_in_seconds
96
+ self.upgrade = upgrade or {}
97
+
98
+
77
99
  class ServerError(CabalSpyError):
78
100
  """5xx — internal_error or service_unavailable."""
79
101
 
@@ -112,6 +134,8 @@ def error_from_status(
112
134
  rate_limit: RateLimit,
113
135
  retry_after: float | None,
114
136
  fallback: str,
137
+ *,
138
+ upgrade: dict[str, Any] | None = None,
115
139
  ) -> CabalSpyError:
116
140
  """Maps an HTTP status and error body onto the right exception class."""
117
141
  body = body or {}
@@ -137,6 +161,15 @@ def error_from_status(
137
161
  if status == 404:
138
162
  return NotFoundError(message, **kwargs)
139
163
  if status == 429:
164
+ if body.get("code") == "demo_limit_reached":
165
+ resets = body.get("resets_in_seconds")
166
+ return DemoLimitError(
167
+ message,
168
+ retry_after=retry_after if retry_after is not None else resets,
169
+ resets_in_seconds=resets,
170
+ upgrade=upgrade,
171
+ **kwargs,
172
+ )
140
173
  return RateLimitError(message, retry_after=retry_after, **kwargs)
141
174
  if status >= 500:
142
175
  return ServerError(message, **kwargs)
@@ -145,4 +178,6 @@ def error_from_status(
145
178
 
146
179
  def is_retryable(exc: BaseException) -> bool:
147
180
  """True for failures where retrying with backoff is worthwhile."""
181
+ if isinstance(exc, DemoLimitError):
182
+ return False
148
183
  return isinstance(exc, (RateLimitError, ServerError, APIConnectionError))
@@ -40,6 +40,23 @@ class Pagination(TypedDict):
40
40
  next_cursor: str | None
41
41
 
42
42
 
43
+ class DemoUpgrade(TypedDict, total=False):
44
+ test_key: str
45
+ pay_per_call: str
46
+ docs: str
47
+
48
+
49
+ class DemoInfo(TypedDict, total=False):
50
+ """Top-level ``demo`` object on responses made with the demo key.
51
+
52
+ Available as ``Envelope.demo`` and ``client.last_demo``.
53
+ """
54
+
55
+ notice: str
56
+ remaining_today: int
57
+ upgrade: DemoUpgrade
58
+
59
+
43
60
  # ── shared ───────────────────────────────────────────────────────────────────
44
61
 
45
62
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "cabalspy"
7
- version = "0.2.0"
7
+ version = "0.3.0"
8
8
  description = "KOL and smart money wallet tracking API for Solana, Base, BNB Chain, Ethereum and Robinhood Chain. Realtime KOL trades, whale wallets, copy-trading signals, bundle detection, token holders and PnL over REST and WebSocket."
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -40,7 +40,7 @@ x402 = ["x402>=2.17"]
40
40
  dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "mypy>=1.8", "websockets>=12.0"]
41
41
 
42
42
  [project.urls]
43
- Homepage = "https://docs.cabalspy.xyz"
43
+ Homepage = "https://www.cabalspy.xyz/sdks/"
44
44
  Documentation = "https://docs.cabalspy.xyz"
45
45
  Repository = "https://github.com/CabalSpy/cabalspy-python"
46
46
  Issues = "https://github.com/CabalSpy/cabalspy-python/issues"
File without changes
File without changes
File without changes
File without changes