https://github.com/mountaingod2/cb-events
Async Python client for the Chaturbate Events API
https://github.com/mountaingod2/cb-events
api chaturbate client events longpoll streaming
Last synced: about 1 month ago
JSON representation
Async Python client for the Chaturbate Events API
- Host: GitHub
- URL: https://github.com/mountaingod2/cb-events
- Owner: MountainGod2
- License: mit
- Created: 2025-08-26T01:43:40.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-03-29T15:10:24.000Z (2 months ago)
- Last Synced: 2026-03-29T17:56:31.251Z (2 months ago)
- Topics: api, chaturbate, client, events, longpoll, streaming
- Language: Python
- Homepage: https://cb-events.readthedocs.io
- Size: 2.58 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# CB Events
Async Python client for the Chaturbate Events API.
[](https://pypi.org/project/cb-events/)
[](https://github.com/MountainGod2/cb-events/releases)
[](https://pypi.org/project/cb-events/)
[](https://www.bestpractices.dev/en/projects/12375)
[](https://github.com/MountainGod2/cb-events/actions/workflows/ci-cd.yml)
[](https://github.com/MountainGod2/cb-events/blob/main/LICENSE)
## Requirements
Python 3.10+
## Installation
```bash
pip install cb-events
```
With [uv](https://docs.astral.sh/uv/) (recommended):
```bash
uv add cb-events
```
## Quick Start
```python
import asyncio
from cb_events import EventClient, Router, EventType, Event
router = Router()
username = "your_username"
token = "your_api_token"
@router.on(EventType.TIP)
async def handle_tip(event: Event) -> None:
if event.user and event.tip:
print(f"{event.user.username} tipped {event.tip.tokens} tokens")
async def main():
async with EventClient(username, token) as client:
async for event in client:
await router.dispatch(event)
asyncio.run(main())
```
```text
mountaingod2 tipped 100 tokens
```
For usage examples, see the [examples folder](https://github.com/MountainGod2/cb-events/blob/main/examples).
> [!NOTE]
> Generate an API token at https://chaturbate.com/statsapi/authtoken/ with `Events API` scope.
## Working with Events
### Event Types
`TIP` · `FANCLUB_JOIN` · `MEDIA_PURCHASE` · `CHAT_MESSAGE` · `PRIVATE_MESSAGE` · `USER_ENTER` · `USER_LEAVE` · `FOLLOW` · `UNFOLLOW` · `BROADCAST_START` · `BROADCAST_STOP` · `ROOM_SUBJECT_CHANGE`
### Event Object
```python
event.user # User object (most events)
event.tip # Tip object (TIP only)
event.message # Message object (CHAT_MESSAGE, PRIVATE_MESSAGE)
event.media # Media object (MEDIA_PURCHASE)
event.room_subject # RoomSubject object (ROOM_SUBJECT_CHANGE)
event.broadcaster # Broadcaster username string or None
```
[See full docs for additional details](https://cb-events.readthedocs.io/latest/event_models.html).
## Configuration
```python
from cb_events import ClientConfig
config = ClientConfig(
timeout=10, # Server long-poll timeout (seconds)
use_testbed=False, # Use testbed endpoint (https://www.testbed.cb.dev)
strict_validation=False, # False skips & logs invalid events; True raises.
retry_attempts=8, # Total attempts (initial + retries)
retry_backoff=1.0, # Initial backoff (seconds)
retry_factor=2.0, # Backoff multiplier
retry_max_delay=30.0, # Max retry delay (seconds)
)
client = EventClient(username, token, config=config)
```
> **Testbed:** Register at . New accounts include preloaded tokens for testing. Generate an API token the same way as a live account, then pass `use_testbed=True` with those credentials.
### Rate Limiting
Default: 2000 req/60s per client. Multiple clients each get an independent
budget unless a shared limiter is passed:
```python
from aiolimiter import AsyncLimiter
limiter = AsyncLimiter(max_rate=2000, time_period=60)
client1 = EventClient(username1, token1, rate_limiter=limiter)
client2 = EventClient(username2, token2, rate_limiter=limiter)
```
## Error Handling
`AuthError` is a subclass of `EventsError` — `except EventsError` catches both. Put `AuthError` first if you need to distinguish them.
```python
import logging
import sys
from cb_events import AuthError, EventsError
logger = logging.getLogger(__name__)
try:
async with EventClient(username, token) as client:
async for event in client:
await router.dispatch(event)
except AuthError:
# Authentication failed (401/403) — never retried
logger.error("Invalid credentials — check username and token")
sys.exit(1)
except EventsError as e:
# All other API/network errors — check e.status_code, e.response_text
logger.error("API error %s: %s", e.status_code, e.response_text)
raise
```
**Retries:** 429, 5xx, Cloudflare 521-524. Not retriable: 401/403.
**Handlers:** Sequential execution. Errors logged but don't stop processing.
## Logging
Set the logger to `DEBUG` for verbose polling data:
```python
import logging
logging.getLogger("cb_events").setLevel(logging.DEBUG)
```
Example output:
```text
DEBUG:cb_events.client:Polling https://eventsapi.chaturbate.com/events/user/************************/?timeout=10
DEBUG:cb_events.client:Received 1 events for user
DEBUG:cb_events.router:Dispatching chatMessage event 1775683684418-0 to 2 handlers
```
## Star History
## License
MIT
---
Not affiliated with Chaturbate.