xcrop 1.0.1__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.
- xcrop-1.0.1/.gitignore +19 -0
- xcrop-1.0.1/PKG-INFO +345 -0
- xcrop-1.0.1/README.md +317 -0
- xcrop-1.0.1/pyproject.toml +42 -0
- xcrop-1.0.1/tests/__init__.py +0 -0
- xcrop-1.0.1/tests/test_sdk.py +268 -0
- xcrop-1.0.1/xcrop/__init__.py +41 -0
- xcrop-1.0.1/xcrop/_http.py +334 -0
- xcrop-1.0.1/xcrop/_version.py +3 -0
- xcrop-1.0.1/xcrop/client.py +125 -0
- xcrop-1.0.1/xcrop/errors.py +93 -0
- xcrop-1.0.1/xcrop/py.typed +0 -0
- xcrop-1.0.1/xcrop/resources/__init__.py +29 -0
- xcrop-1.0.1/xcrop/resources/account.py +92 -0
- xcrop-1.0.1/xcrop/resources/communities.py +167 -0
- xcrop-1.0.1/xcrop/resources/lists.py +135 -0
- xcrop-1.0.1/xcrop/resources/search.py +285 -0
- xcrop-1.0.1/xcrop/resources/stream.py +30 -0
- xcrop-1.0.1/xcrop/resources/trending.py +29 -0
- xcrop-1.0.1/xcrop/resources/tweets.py +292 -0
- xcrop-1.0.1/xcrop/resources/users.py +293 -0
- xcrop-1.0.1/xcrop/types.py +219 -0
xcrop-1.0.1/.gitignore
ADDED
xcrop-1.0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: xcrop
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: Official Python SDK for the XCROP API, the X/Twitter data intelligence platform
|
|
5
|
+
Project-URL: Homepage, https://xcrop.io
|
|
6
|
+
Project-URL: Documentation, https://xcrop.io/docs
|
|
7
|
+
Project-URL: Repository, https://github.com/xcrop-io/xcrop-python
|
|
8
|
+
Project-URL: Issues, https://github.com/xcrop-io/xcrop-python/issues
|
|
9
|
+
Author-email: XCROP <support@xcrop.io>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
Keywords: api,data,intelligence,scraper,twitter,x,xcrop
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
23
|
+
Classifier: Typing :: Typed
|
|
24
|
+
Requires-Python: >=3.8
|
|
25
|
+
Requires-Dist: httpx>=0.24.0
|
|
26
|
+
Requires-Dist: typing-extensions>=3.7.4; python_version < '3.12'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# XCROP Python SDK
|
|
30
|
+
|
|
31
|
+
Official Python client for the [XCROP API](https://xcrop.io), the X/Twitter data intelligence platform. 42 endpoints covering profile lookup, timelines, search, lists, communities, account monitoring, write operations, and interaction/eligibility checks.
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install xcrop
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Quick Start
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from xcrop import XCropClient
|
|
43
|
+
|
|
44
|
+
client = XCropClient(api_key="xc_live_...")
|
|
45
|
+
|
|
46
|
+
# Get user profile
|
|
47
|
+
user = client.users.get("elonmusk")
|
|
48
|
+
print(user["data"]["name"])
|
|
49
|
+
|
|
50
|
+
# Get user tweets
|
|
51
|
+
tweets = client.users.tweets("elonmusk", count=50)
|
|
52
|
+
for tweet in tweets["data"]:
|
|
53
|
+
print(tweet["text"])
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Features
|
|
57
|
+
|
|
58
|
+
- **Sync & Async**: `XCropClient` (sync) and `AsyncXCropClient` (async) with identical APIs
|
|
59
|
+
- **Auto-retry**: Exponential backoff on 429 (rate limit) and 5xx errors, up to 3 retries
|
|
60
|
+
- **Auto-pagination**: `.paginate()` iterators handle cursor-based pagination automatically
|
|
61
|
+
- **SSE Streaming**: Real-time search streaming and event streams
|
|
62
|
+
- **Type hints**: Full typing for IDE autocomplete
|
|
63
|
+
- **Custom exceptions**: `AuthError`, `RateLimitError`, `NotFoundError`, `ServerError`
|
|
64
|
+
|
|
65
|
+
## Usage
|
|
66
|
+
|
|
67
|
+
### Users
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
# Profile
|
|
71
|
+
user = client.users.get("elonmusk")
|
|
72
|
+
|
|
73
|
+
# Tweets, followers, following, etc.
|
|
74
|
+
tweets = client.users.tweets("elonmusk", count=20)
|
|
75
|
+
followers = client.users.followers("elonmusk", count=50)
|
|
76
|
+
following = client.users.following("elonmusk")
|
|
77
|
+
mentions = client.users.mentions("elonmusk")
|
|
78
|
+
replies = client.users.replies("elonmusk")
|
|
79
|
+
media = client.users.media("elonmusk")
|
|
80
|
+
verified = client.users.verified_followers("elonmusk")
|
|
81
|
+
|
|
82
|
+
# Bulk follower IDs (up to 5,000 per call, no profile metadata)
|
|
83
|
+
ids = client.users.followers_ids("elonmusk", count=5000)
|
|
84
|
+
|
|
85
|
+
# Auto-paginate (fetches all pages, yields individual items)
|
|
86
|
+
for tweet in client.users.tweets.paginate("elonmusk", count=200):
|
|
87
|
+
print(tweet["text"])
|
|
88
|
+
|
|
89
|
+
# Batch lookup (up to 100)
|
|
90
|
+
users = client.users.batch(["elonmusk", "jack", "vaboronin"])
|
|
91
|
+
|
|
92
|
+
# Follow relationship check: does `source` follow `target`?
|
|
93
|
+
rel = client.users.check_follow(source="jack", target="elonmusk")
|
|
94
|
+
print(rel["data"]["source_follows_target"])
|
|
95
|
+
|
|
96
|
+
# Eligibility checks (for giveaway/airdrop gating)
|
|
97
|
+
account_ok = client.users.check_qualified_account(
|
|
98
|
+
"elonmusk", min_followers=100, min_age_days=30,
|
|
99
|
+
)
|
|
100
|
+
name_ok = client.users.check_qualified_name(
|
|
101
|
+
"elonmusk", contains="Musk", position="anywhere",
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
# Follow / unfollow (requires connected account)
|
|
105
|
+
client.users.follow("jack")
|
|
106
|
+
client.users.unfollow("jack")
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### Tweets
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
# Single tweet
|
|
113
|
+
tweet = client.tweets.get("1234567890")
|
|
114
|
+
|
|
115
|
+
# Conversation thread
|
|
116
|
+
conv = client.tweets.conversation("1234567890", count=50)
|
|
117
|
+
|
|
118
|
+
# Quotes (with pagination)
|
|
119
|
+
for quote in client.tweets.quotes.paginate("1234567890", count=100):
|
|
120
|
+
print(quote["text"])
|
|
121
|
+
|
|
122
|
+
# Batch lookup
|
|
123
|
+
tweets = client.tweets.batch(["123", "456", "789"])
|
|
124
|
+
|
|
125
|
+
# Write operations (requires connected account)
|
|
126
|
+
result = client.tweets.create(text="Hello from XCROP SDK!")
|
|
127
|
+
client.tweets.reply(tweet_id="1234567890", text="Great thread!")
|
|
128
|
+
client.tweets.quote(tweet_id="1234567890", text="Interesting take")
|
|
129
|
+
client.tweets.delete(tweet_id="1234567890")
|
|
130
|
+
|
|
131
|
+
# Like / unlike / retweet / unretweet
|
|
132
|
+
client.tweets.like("1234567890")
|
|
133
|
+
client.tweets.unlike("1234567890")
|
|
134
|
+
client.tweets.retweet("1234567890")
|
|
135
|
+
client.tweets.unretweet("1234567890")
|
|
136
|
+
|
|
137
|
+
# Interaction checks (no connected account needed)
|
|
138
|
+
check = client.tweets.check_retweet("1234567890", username="jack")
|
|
139
|
+
print(check["data"]["result"]) # True/False
|
|
140
|
+
|
|
141
|
+
# check_reply / check_quote also accept an optional min_tags (0-20)
|
|
142
|
+
check = client.tweets.check_reply("1234567890", username="jack", min_tags=1)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Search
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
# Basic search
|
|
149
|
+
results = client.search.tweets(query="bitcoin", count=50)
|
|
150
|
+
|
|
151
|
+
# Advanced search
|
|
152
|
+
results = client.search.tweets(
|
|
153
|
+
query="ethereum",
|
|
154
|
+
sort="popular",
|
|
155
|
+
lang="en",
|
|
156
|
+
min_likes=100,
|
|
157
|
+
exclude_replies=True,
|
|
158
|
+
since="2024-01-01",
|
|
159
|
+
)
|
|
160
|
+
|
|
161
|
+
# Auto-paginate search
|
|
162
|
+
for tweet in client.search.tweets_paginate(query="bitcoin", count=200, sort="latest"):
|
|
163
|
+
print(tweet["text"])
|
|
164
|
+
|
|
165
|
+
# SSE streaming search
|
|
166
|
+
for tweet in client.search.tweets_stream(query="breaking", count=100):
|
|
167
|
+
print(tweet)
|
|
168
|
+
|
|
169
|
+
# User search
|
|
170
|
+
users = client.search.users(query="crypto trader", count=20)
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### Lists
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
tweets = client.lists.tweets("1234567890", count=50)
|
|
177
|
+
members = client.lists.members("1234567890")
|
|
178
|
+
subscribers = client.lists.subscribers("1234567890")
|
|
179
|
+
|
|
180
|
+
# Paginate
|
|
181
|
+
for tweet in client.lists.tweets.paginate("1234567890", count=200):
|
|
182
|
+
print(tweet["text"])
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### Trending
|
|
186
|
+
|
|
187
|
+
```python
|
|
188
|
+
trending = client.trending.get()
|
|
189
|
+
for topic in trending["data"]:
|
|
190
|
+
print(topic["name"], topic.get("tweet_count"))
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Communities (beta)
|
|
194
|
+
|
|
195
|
+
> Communities endpoints are still rolling out and may return a `503`
|
|
196
|
+
> (`ServerError`) while the underlying data source stabilizes.
|
|
197
|
+
|
|
198
|
+
```python
|
|
199
|
+
from xcrop import ServerError
|
|
200
|
+
|
|
201
|
+
try:
|
|
202
|
+
community = client.communities.get("1708766018985501165")
|
|
203
|
+
tweets = client.communities.tweets("1708766018985501165", count=50)
|
|
204
|
+
members = client.communities.members("1708766018985501165", count=50)
|
|
205
|
+
|
|
206
|
+
for tweet in client.communities.tweets.paginate("1708766018985501165", count=200):
|
|
207
|
+
print(tweet["text"])
|
|
208
|
+
except ServerError:
|
|
209
|
+
print("Communities data source temporarily unavailable")
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### Account Management
|
|
213
|
+
|
|
214
|
+
```python
|
|
215
|
+
# Connect via credentials
|
|
216
|
+
client.account.connect(username="myuser", password="mypass", totp_secret="TOTP_SECRET")
|
|
217
|
+
|
|
218
|
+
# Connect via cookies
|
|
219
|
+
client.account.connect(cookies={"auth_token": "...", "ct0": "..."})
|
|
220
|
+
|
|
221
|
+
# Check status
|
|
222
|
+
status = client.account.status()
|
|
223
|
+
print(status["data"]["connected"])
|
|
224
|
+
|
|
225
|
+
# Disconnect
|
|
226
|
+
client.account.disconnect()
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
### Real-time Stream
|
|
230
|
+
|
|
231
|
+
```python
|
|
232
|
+
for event in client.stream.connect():
|
|
233
|
+
print(event)
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
## Async Usage
|
|
237
|
+
|
|
238
|
+
```python
|
|
239
|
+
import asyncio
|
|
240
|
+
from xcrop import AsyncXCropClient
|
|
241
|
+
|
|
242
|
+
async def main():
|
|
243
|
+
async with AsyncXCropClient(api_key="xc_live_...") as client:
|
|
244
|
+
# All methods are async
|
|
245
|
+
user = await client.users.get("elonmusk")
|
|
246
|
+
print(user["data"]["name"])
|
|
247
|
+
|
|
248
|
+
# Async pagination
|
|
249
|
+
async for tweet in client.users.tweets.paginate("elonmusk", count=200):
|
|
250
|
+
print(tweet["text"])
|
|
251
|
+
|
|
252
|
+
# Async search streaming
|
|
253
|
+
async for tweet in client.search.tweets_stream(query="breaking"):
|
|
254
|
+
print(tweet)
|
|
255
|
+
|
|
256
|
+
asyncio.run(main())
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
## Error Handling
|
|
260
|
+
|
|
261
|
+
```python
|
|
262
|
+
from xcrop import XCropClient, AuthError, RateLimitError, NotFoundError, XCropError
|
|
263
|
+
|
|
264
|
+
client = XCropClient(api_key="xc_live_...")
|
|
265
|
+
|
|
266
|
+
try:
|
|
267
|
+
user = client.users.get("nonexistent_user_12345")
|
|
268
|
+
except NotFoundError:
|
|
269
|
+
print("User not found")
|
|
270
|
+
except AuthError:
|
|
271
|
+
print("Invalid API key")
|
|
272
|
+
except RateLimitError as e:
|
|
273
|
+
print(f"Rate limited. Retry after: {e.retry_after}s")
|
|
274
|
+
except XCropError as e:
|
|
275
|
+
print(f"API error: {e.message} (HTTP {e.status_code})")
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
## Configuration
|
|
279
|
+
|
|
280
|
+
```python
|
|
281
|
+
client = XCropClient(
|
|
282
|
+
api_key="xc_live_...",
|
|
283
|
+
base_url="https://xcrop.io/api/v2", # default
|
|
284
|
+
timeout=30.0, # seconds, default
|
|
285
|
+
max_retries=3, # default
|
|
286
|
+
)
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
You can also pass a custom `httpx.Client` or `httpx.AsyncClient`:
|
|
290
|
+
|
|
291
|
+
```python
|
|
292
|
+
import httpx
|
|
293
|
+
|
|
294
|
+
http = httpx.Client(proxy="http://proxy:8080")
|
|
295
|
+
client = XCropClient(api_key="xc_live_...", http_client=http)
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
## Rate Limits & Plans
|
|
299
|
+
|
|
300
|
+
Per-minute request limits are enforced per plan (in addition to the monthly
|
|
301
|
+
credit allowance):
|
|
302
|
+
|
|
303
|
+
| Plan | Requests / min |
|
|
304
|
+
|---------|-----------------|
|
|
305
|
+
| Starter | 60 |
|
|
306
|
+
| Basic | 300 |
|
|
307
|
+
| Pro | 600 |
|
|
308
|
+
| PAYG | 300 |
|
|
309
|
+
|
|
310
|
+
Exceeding the limit raises `RateLimitError` (the SDK auto-retries 429s with
|
|
311
|
+
backoff before raising). See [xcrop.io/pricing](https://xcrop.io/pricing) for
|
|
312
|
+
credit costs per endpoint.
|
|
313
|
+
|
|
314
|
+
## Billing
|
|
315
|
+
|
|
316
|
+
Plans and credit top-ups are paid via cryptocurrency: **USDT (BEP-20)**,
|
|
317
|
+
**USDC (BEP-20)**, **SOL**, and **POL**. Credit card payments via Stripe are
|
|
318
|
+
coming soon. See [xcrop.io/pricing](https://xcrop.io/pricing) and the
|
|
319
|
+
dashboard billing page to manage your subscription.
|
|
320
|
+
|
|
321
|
+
## API Response Format
|
|
322
|
+
|
|
323
|
+
All methods return the raw API response as a dict:
|
|
324
|
+
|
|
325
|
+
```python
|
|
326
|
+
{
|
|
327
|
+
"data": ..., # Response payload
|
|
328
|
+
"meta": {
|
|
329
|
+
"latency_ms": 123,
|
|
330
|
+
"cached": True,
|
|
331
|
+
"total": 50,
|
|
332
|
+
"cursor": "abc123",
|
|
333
|
+
"has_next": True,
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
## Requirements
|
|
339
|
+
|
|
340
|
+
- Python 3.8+
|
|
341
|
+
- httpx >= 0.24.0
|
|
342
|
+
|
|
343
|
+
## License
|
|
344
|
+
|
|
345
|
+
MIT
|
xcrop-1.0.1/README.md
ADDED
|
@@ -0,0 +1,317 @@
|
|
|
1
|
+
# XCROP Python SDK
|
|
2
|
+
|
|
3
|
+
Official Python client for the [XCROP API](https://xcrop.io), the X/Twitter data intelligence platform. 42 endpoints covering profile lookup, timelines, search, lists, communities, account monitoring, write operations, and interaction/eligibility checks.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pip install xcrop
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
```python
|
|
14
|
+
from xcrop import XCropClient
|
|
15
|
+
|
|
16
|
+
client = XCropClient(api_key="xc_live_...")
|
|
17
|
+
|
|
18
|
+
# Get user profile
|
|
19
|
+
user = client.users.get("elonmusk")
|
|
20
|
+
print(user["data"]["name"])
|
|
21
|
+
|
|
22
|
+
# Get user tweets
|
|
23
|
+
tweets = client.users.tweets("elonmusk", count=50)
|
|
24
|
+
for tweet in tweets["data"]:
|
|
25
|
+
print(tweet["text"])
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Features
|
|
29
|
+
|
|
30
|
+
- **Sync & Async**: `XCropClient` (sync) and `AsyncXCropClient` (async) with identical APIs
|
|
31
|
+
- **Auto-retry**: Exponential backoff on 429 (rate limit) and 5xx errors, up to 3 retries
|
|
32
|
+
- **Auto-pagination**: `.paginate()` iterators handle cursor-based pagination automatically
|
|
33
|
+
- **SSE Streaming**: Real-time search streaming and event streams
|
|
34
|
+
- **Type hints**: Full typing for IDE autocomplete
|
|
35
|
+
- **Custom exceptions**: `AuthError`, `RateLimitError`, `NotFoundError`, `ServerError`
|
|
36
|
+
|
|
37
|
+
## Usage
|
|
38
|
+
|
|
39
|
+
### Users
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
# Profile
|
|
43
|
+
user = client.users.get("elonmusk")
|
|
44
|
+
|
|
45
|
+
# Tweets, followers, following, etc.
|
|
46
|
+
tweets = client.users.tweets("elonmusk", count=20)
|
|
47
|
+
followers = client.users.followers("elonmusk", count=50)
|
|
48
|
+
following = client.users.following("elonmusk")
|
|
49
|
+
mentions = client.users.mentions("elonmusk")
|
|
50
|
+
replies = client.users.replies("elonmusk")
|
|
51
|
+
media = client.users.media("elonmusk")
|
|
52
|
+
verified = client.users.verified_followers("elonmusk")
|
|
53
|
+
|
|
54
|
+
# Bulk follower IDs (up to 5,000 per call, no profile metadata)
|
|
55
|
+
ids = client.users.followers_ids("elonmusk", count=5000)
|
|
56
|
+
|
|
57
|
+
# Auto-paginate (fetches all pages, yields individual items)
|
|
58
|
+
for tweet in client.users.tweets.paginate("elonmusk", count=200):
|
|
59
|
+
print(tweet["text"])
|
|
60
|
+
|
|
61
|
+
# Batch lookup (up to 100)
|
|
62
|
+
users = client.users.batch(["elonmusk", "jack", "vaboronin"])
|
|
63
|
+
|
|
64
|
+
# Follow relationship check: does `source` follow `target`?
|
|
65
|
+
rel = client.users.check_follow(source="jack", target="elonmusk")
|
|
66
|
+
print(rel["data"]["source_follows_target"])
|
|
67
|
+
|
|
68
|
+
# Eligibility checks (for giveaway/airdrop gating)
|
|
69
|
+
account_ok = client.users.check_qualified_account(
|
|
70
|
+
"elonmusk", min_followers=100, min_age_days=30,
|
|
71
|
+
)
|
|
72
|
+
name_ok = client.users.check_qualified_name(
|
|
73
|
+
"elonmusk", contains="Musk", position="anywhere",
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
# Follow / unfollow (requires connected account)
|
|
77
|
+
client.users.follow("jack")
|
|
78
|
+
client.users.unfollow("jack")
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Tweets
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
# Single tweet
|
|
85
|
+
tweet = client.tweets.get("1234567890")
|
|
86
|
+
|
|
87
|
+
# Conversation thread
|
|
88
|
+
conv = client.tweets.conversation("1234567890", count=50)
|
|
89
|
+
|
|
90
|
+
# Quotes (with pagination)
|
|
91
|
+
for quote in client.tweets.quotes.paginate("1234567890", count=100):
|
|
92
|
+
print(quote["text"])
|
|
93
|
+
|
|
94
|
+
# Batch lookup
|
|
95
|
+
tweets = client.tweets.batch(["123", "456", "789"])
|
|
96
|
+
|
|
97
|
+
# Write operations (requires connected account)
|
|
98
|
+
result = client.tweets.create(text="Hello from XCROP SDK!")
|
|
99
|
+
client.tweets.reply(tweet_id="1234567890", text="Great thread!")
|
|
100
|
+
client.tweets.quote(tweet_id="1234567890", text="Interesting take")
|
|
101
|
+
client.tweets.delete(tweet_id="1234567890")
|
|
102
|
+
|
|
103
|
+
# Like / unlike / retweet / unretweet
|
|
104
|
+
client.tweets.like("1234567890")
|
|
105
|
+
client.tweets.unlike("1234567890")
|
|
106
|
+
client.tweets.retweet("1234567890")
|
|
107
|
+
client.tweets.unretweet("1234567890")
|
|
108
|
+
|
|
109
|
+
# Interaction checks (no connected account needed)
|
|
110
|
+
check = client.tweets.check_retweet("1234567890", username="jack")
|
|
111
|
+
print(check["data"]["result"]) # True/False
|
|
112
|
+
|
|
113
|
+
# check_reply / check_quote also accept an optional min_tags (0-20)
|
|
114
|
+
check = client.tweets.check_reply("1234567890", username="jack", min_tags=1)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Search
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
# Basic search
|
|
121
|
+
results = client.search.tweets(query="bitcoin", count=50)
|
|
122
|
+
|
|
123
|
+
# Advanced search
|
|
124
|
+
results = client.search.tweets(
|
|
125
|
+
query="ethereum",
|
|
126
|
+
sort="popular",
|
|
127
|
+
lang="en",
|
|
128
|
+
min_likes=100,
|
|
129
|
+
exclude_replies=True,
|
|
130
|
+
since="2024-01-01",
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
# Auto-paginate search
|
|
134
|
+
for tweet in client.search.tweets_paginate(query="bitcoin", count=200, sort="latest"):
|
|
135
|
+
print(tweet["text"])
|
|
136
|
+
|
|
137
|
+
# SSE streaming search
|
|
138
|
+
for tweet in client.search.tweets_stream(query="breaking", count=100):
|
|
139
|
+
print(tweet)
|
|
140
|
+
|
|
141
|
+
# User search
|
|
142
|
+
users = client.search.users(query="crypto trader", count=20)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Lists
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
tweets = client.lists.tweets("1234567890", count=50)
|
|
149
|
+
members = client.lists.members("1234567890")
|
|
150
|
+
subscribers = client.lists.subscribers("1234567890")
|
|
151
|
+
|
|
152
|
+
# Paginate
|
|
153
|
+
for tweet in client.lists.tweets.paginate("1234567890", count=200):
|
|
154
|
+
print(tweet["text"])
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Trending
|
|
158
|
+
|
|
159
|
+
```python
|
|
160
|
+
trending = client.trending.get()
|
|
161
|
+
for topic in trending["data"]:
|
|
162
|
+
print(topic["name"], topic.get("tweet_count"))
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Communities (beta)
|
|
166
|
+
|
|
167
|
+
> Communities endpoints are still rolling out and may return a `503`
|
|
168
|
+
> (`ServerError`) while the underlying data source stabilizes.
|
|
169
|
+
|
|
170
|
+
```python
|
|
171
|
+
from xcrop import ServerError
|
|
172
|
+
|
|
173
|
+
try:
|
|
174
|
+
community = client.communities.get("1708766018985501165")
|
|
175
|
+
tweets = client.communities.tweets("1708766018985501165", count=50)
|
|
176
|
+
members = client.communities.members("1708766018985501165", count=50)
|
|
177
|
+
|
|
178
|
+
for tweet in client.communities.tweets.paginate("1708766018985501165", count=200):
|
|
179
|
+
print(tweet["text"])
|
|
180
|
+
except ServerError:
|
|
181
|
+
print("Communities data source temporarily unavailable")
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Account Management
|
|
185
|
+
|
|
186
|
+
```python
|
|
187
|
+
# Connect via credentials
|
|
188
|
+
client.account.connect(username="myuser", password="mypass", totp_secret="TOTP_SECRET")
|
|
189
|
+
|
|
190
|
+
# Connect via cookies
|
|
191
|
+
client.account.connect(cookies={"auth_token": "...", "ct0": "..."})
|
|
192
|
+
|
|
193
|
+
# Check status
|
|
194
|
+
status = client.account.status()
|
|
195
|
+
print(status["data"]["connected"])
|
|
196
|
+
|
|
197
|
+
# Disconnect
|
|
198
|
+
client.account.disconnect()
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### Real-time Stream
|
|
202
|
+
|
|
203
|
+
```python
|
|
204
|
+
for event in client.stream.connect():
|
|
205
|
+
print(event)
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
## Async Usage
|
|
209
|
+
|
|
210
|
+
```python
|
|
211
|
+
import asyncio
|
|
212
|
+
from xcrop import AsyncXCropClient
|
|
213
|
+
|
|
214
|
+
async def main():
|
|
215
|
+
async with AsyncXCropClient(api_key="xc_live_...") as client:
|
|
216
|
+
# All methods are async
|
|
217
|
+
user = await client.users.get("elonmusk")
|
|
218
|
+
print(user["data"]["name"])
|
|
219
|
+
|
|
220
|
+
# Async pagination
|
|
221
|
+
async for tweet in client.users.tweets.paginate("elonmusk", count=200):
|
|
222
|
+
print(tweet["text"])
|
|
223
|
+
|
|
224
|
+
# Async search streaming
|
|
225
|
+
async for tweet in client.search.tweets_stream(query="breaking"):
|
|
226
|
+
print(tweet)
|
|
227
|
+
|
|
228
|
+
asyncio.run(main())
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
## Error Handling
|
|
232
|
+
|
|
233
|
+
```python
|
|
234
|
+
from xcrop import XCropClient, AuthError, RateLimitError, NotFoundError, XCropError
|
|
235
|
+
|
|
236
|
+
client = XCropClient(api_key="xc_live_...")
|
|
237
|
+
|
|
238
|
+
try:
|
|
239
|
+
user = client.users.get("nonexistent_user_12345")
|
|
240
|
+
except NotFoundError:
|
|
241
|
+
print("User not found")
|
|
242
|
+
except AuthError:
|
|
243
|
+
print("Invalid API key")
|
|
244
|
+
except RateLimitError as e:
|
|
245
|
+
print(f"Rate limited. Retry after: {e.retry_after}s")
|
|
246
|
+
except XCropError as e:
|
|
247
|
+
print(f"API error: {e.message} (HTTP {e.status_code})")
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
## Configuration
|
|
251
|
+
|
|
252
|
+
```python
|
|
253
|
+
client = XCropClient(
|
|
254
|
+
api_key="xc_live_...",
|
|
255
|
+
base_url="https://xcrop.io/api/v2", # default
|
|
256
|
+
timeout=30.0, # seconds, default
|
|
257
|
+
max_retries=3, # default
|
|
258
|
+
)
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
You can also pass a custom `httpx.Client` or `httpx.AsyncClient`:
|
|
262
|
+
|
|
263
|
+
```python
|
|
264
|
+
import httpx
|
|
265
|
+
|
|
266
|
+
http = httpx.Client(proxy="http://proxy:8080")
|
|
267
|
+
client = XCropClient(api_key="xc_live_...", http_client=http)
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
## Rate Limits & Plans
|
|
271
|
+
|
|
272
|
+
Per-minute request limits are enforced per plan (in addition to the monthly
|
|
273
|
+
credit allowance):
|
|
274
|
+
|
|
275
|
+
| Plan | Requests / min |
|
|
276
|
+
|---------|-----------------|
|
|
277
|
+
| Starter | 60 |
|
|
278
|
+
| Basic | 300 |
|
|
279
|
+
| Pro | 600 |
|
|
280
|
+
| PAYG | 300 |
|
|
281
|
+
|
|
282
|
+
Exceeding the limit raises `RateLimitError` (the SDK auto-retries 429s with
|
|
283
|
+
backoff before raising). See [xcrop.io/pricing](https://xcrop.io/pricing) for
|
|
284
|
+
credit costs per endpoint.
|
|
285
|
+
|
|
286
|
+
## Billing
|
|
287
|
+
|
|
288
|
+
Plans and credit top-ups are paid via cryptocurrency: **USDT (BEP-20)**,
|
|
289
|
+
**USDC (BEP-20)**, **SOL**, and **POL**. Credit card payments via Stripe are
|
|
290
|
+
coming soon. See [xcrop.io/pricing](https://xcrop.io/pricing) and the
|
|
291
|
+
dashboard billing page to manage your subscription.
|
|
292
|
+
|
|
293
|
+
## API Response Format
|
|
294
|
+
|
|
295
|
+
All methods return the raw API response as a dict:
|
|
296
|
+
|
|
297
|
+
```python
|
|
298
|
+
{
|
|
299
|
+
"data": ..., # Response payload
|
|
300
|
+
"meta": {
|
|
301
|
+
"latency_ms": 123,
|
|
302
|
+
"cached": True,
|
|
303
|
+
"total": 50,
|
|
304
|
+
"cursor": "abc123",
|
|
305
|
+
"has_next": True,
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
## Requirements
|
|
311
|
+
|
|
312
|
+
- Python 3.8+
|
|
313
|
+
- httpx >= 0.24.0
|
|
314
|
+
|
|
315
|
+
## License
|
|
316
|
+
|
|
317
|
+
MIT
|