twitch-sdk

Complete Twitch Helix API SDK with Pydantic validation for 170+ endpoints.

Features

• Full API Coverage - All Twitch Helix endpoints (chat, streams, moderation, etc.)
• Pydantic Validation - Type-safe request/response models with automatic validation
• Async/Await - Built for modern Python async applications
• EventSub WebSocket - Real-time event subscriptions built-in
• Auto Token Refresh - Handles OAuth token management via twitch-client

Installation

pip install twitch-sdk

Quick Start

import asyncio
from twitch_sdk import TwitchSDK
from twitch_sdk.schemas.streams import GetStreamsRequest

async def main():
    async with TwitchSDK() as sdk:
        # Get live streams for "Just Chatting"
        params = GetStreamsRequest(game_id=["509658"])
        streams = await sdk.streams.get_streams(sdk.http, params)

        for stream in streams.data:
            print(f"{stream.user_name}: {stream.title} ({stream.viewer_count} viewers)")

asyncio.run(main())

Credentials Setup

Create ~/.twitch-secrets/.env with your Twitch credentials:

TWITCH_CLIENT_ID=your_client_id
TWITCH_CLIENT_SECRET=your_client_secret
TWITCH_ACCESS_TOKEN=your_access_token
TWITCH_REFRESH_TOKEN=your_refresh_token

See twitch-client for detailed setup instructions.

Usage Examples

Send Chat Message

from twitch_sdk import TwitchSDK
from twitch_sdk.schemas.chat import SendMessageRequest

async def main():
    async with TwitchSDK() as sdk:
        params = SendMessageRequest(
            broadcaster_id="123456",
            sender_id="123456",
            message="Hello from the SDK!"
        )
        result = await sdk.chat.send_chat_message(sdk.http, params)
        print(f"Message sent: {result.data[0].is_sent}")

Create a Poll

from twitch_sdk import TwitchSDK
from twitch_sdk.schemas.polls import CreatePollRequest, PollChoiceInput

async def main():
    async with TwitchSDK() as sdk:
        params = CreatePollRequest(
            broadcaster_id="123456",
            title="Favorite game?",
            choices=[
                PollChoiceInput(title="Option A"),
                PollChoiceInput(title="Option B"),
            ],
            duration=60,
        )
        poll = await sdk.polls.create_poll(sdk.http, params)
        print(f"Poll created: {poll.data[0].id}")

EventSub WebSocket

from twitch_sdk import TwitchSDK

async def main():
    async with TwitchSDK() as sdk:
        async with sdk.create_eventsub_websocket() as ws:
            # Subscribe to chat messages
            await ws.subscribe(
                event_type="channel.chat.message",
                version="1",
                condition={
                    "broadcaster_user_id": "123456",
                    "user_id": "123456"
                }
            )

            # Process events
            async for event in ws.events():
                print(f"Event: {event}")

API Coverage

The SDK covers all Twitch Helix API endpoints:

Pydantic Validation

All requests and responses use Pydantic models for validation:

from twitch_sdk.schemas.chat import SendMessageRequest

# Validation happens automatically
params = SendMessageRequest(
    broadcaster_id="123",
    sender_id="456",
    message="Hello!"
)

# Access validated fields
print(params.broadcaster_id)

# Serialize for API
print(params.model_dump(exclude_none=True))

Related Projects

• twitch-client - OAuth layer with auto token refresh
• twitch-mcp - MCP server exposing this SDK as AI tools

License

MIT License - see LICENSE for details.