How jerempjerem/opensea-stream-py works
Project Type and Purpose
• This is a Python SDK (client library) named opensea-stream that connects to the OpenSea Stream API over WebSockets.
• Its job is to let user applications subscribe to NFT collection events (listed, sold, transferred, metadata updates, bids, offers, cancellations) and receive updates via callback functions or webhooks.
File Structure
• Top‐level files:
– setup.py & requirements.txt (packaging + dependencies)
– README.md, LICENSE, .gitignore
• Main module folder: opensea-stream/
– opensea_stream.py (contains OpenseaStreamClient, event types, connection logic, subscription methods)
– utils.py (helper code for message formatting, backoff, validation)
• No separate frontend or database—this is purely a library connecting to an external service.
Key Architecture Insights from README
• Uses websockets to connect to wss://stream.openseabeta.com/socket (mainnet) or testnet endpoint.
• Exposes methods like onItemListed(…), onEvents(…), startListening().
• Internally manages authentication via API key, channel subscription, message parsing, and callback dispatch.
• Optionally integrates with a Discord webhook (via discord_webhook library).
Main Components
1. User Application
– Importing and instantiating OpenseaStreamClient.
– Registering callbacks or webhook handlers.
2. SDK Library
– Module: opensea_stream.py
• Connection Manager (handles WebSocket lifecycle)
• Subscription Manager (tracks event types & collection slugs)
• Event Dispatcher (observer/publish-subscribe pattern)
– Module: utils.py
• Message serialization/deserialization
• Retry/backoff logic
• Validation of payloads
3. External OpenSea Stream Service
– WebSocket endpoint (Mainnet or Testnet)
– Event feed server pushing JSON payloads over channels
4. Optional External Service
– Discord (Webhook) endpoint
– Any other third-party callback destinations
Relationships & Data Flows
• From User App → calls SDK subscription methods → updates Subscription Manager.
• OpenseaStreamClient → connects over WebSocket → authenticates with API key → subscribes to channels.
• External Stream Service → pushes events → SDK Connection Manager receives messages → passes to Event Dispatcher.
• Event Dispatcher → looks up matching user callback(s) → invokes callback function or sends to webhook via discord_webhook.
• Callbacks run in user’s process—handle payload however they choose (database writes, UI updates, logs, etc.).
Architectural Patterns & Design Principles
• Observer / Publish-Subscribe pattern for event callbacks
• Separation of concerns: connection handling, subscription management, message parsing in distinct modules
• Extensibility: new event types and networks (mainnet/testnet) can be added via enums and helper functions
• Resilience: automatic reconnect/backoff logic in utils.py