Example: Streaming and Events

Streaming & Events Demo - Real-Time Power This demo showcases the real-time capabilities of the Quicksilver SDK, allowing developers to implement continuous payment streams and subscribe to live updates for granular control and dynamic interactions.

The Quicksilver SDK provides a robust set of tools for building and managing streaming payments, which are crucial for agent-to-agent interactions, content monetization, and usage-based billing. This example illustrates how to initiate streaming transactions, subscribe to real-time events using StreamConnection, and control the lifecycle of these streams.

Core Concepts

Streaming Payments

Unlike one-time payments or escrows, streaming payments allow for continuous transfer of funds over time or based on usage. Key characteristics include:

• transaction_type: 'Stream': Designates a transaction as a streaming payment.
• Rate and Unit: Defined in the meta field (e.g., rate: 0.01, rate_unit: 'per_second') to specify how funds are accumulated.
• Accumulated Cost: The Transaction model's getCost() method will dynamically reflect the accumulated amount for streaming transactions.

Real-time Events with StreamConnection

The SDK leverages Server-Sent Events (SSE) to provide real-time updates for streaming transactions.

• StreamConnection: An EventEmitter (src/realtime/sse.ts) that encapsulates an EventSource and provides a convenient interface to listen for various stream-related events.
• Events:
  • 'stream_event': Generic events indicating changes in stream status (started, paused, resumed, stopped).
  • 'batch_created': Notifies when an actual payment batch has been processed and funds transferred.
  • 'open', 'error', 'close', 'message': Standard EventSource events for connection management.

Stream Lifecycle Management

The StreamsResource (exposed via client.streams) and methods on the Transaction active model (see API Reference: Transaction Model) provide comprehensive control over streaming payments:

• Start: Initiated by executing a Transaction of type 'Stream'.
• Pause/Resume: Temporarily halt or restart the flow of funds without terminating the stream.
• Update: Modify stream parameters like the rate or end time.
• Stop: Permanently terminate a stream.

Step-by-Step Walkthrough

This example demonstrates how to set up two types of streaming payments and monitor their progress.

1. Initialize the Client

First, initialize the QuicksilverClient using your API key. For sandbox environments, you might not need a specific key.

2. Create Active Accounts

Create two Account instances: one for the streamer (sender) and one for the viewer (recipient). These accounts will be active models, allowing for fluent method calls.

3. Create Streaming Transactions

Create two distinct streaming transactions: a contentStream (representing payment for a video stream) and a microPaymentStream (for general micro-payments). Note the transaction_type: 'Stream' and the rate/rate_unit defined in the meta object. Calling .execute() initiates the stream.

4. Subscribe to Real-Time Events

Subscribe to real-time updates for each streaming transaction using the subscribe() method available directly on the Transaction model. This returns a StreamConnection instance, which is an EventEmitter.

You can then attach listeners for specific events like stream_event (general stream status changes) and batch_created (notifications for actual fund transfers).

5. Simulate Streaming Activity

A setTimeout simulates the passage of time, allowing the streams to accrue payments and trigger events.

6. Control Stream Operations

The client.streams resource (part of API Reference: Resources (Legacy/Advanced)) provides methods to manage the stream's lifecycle:

• client.streams.pause(id): Halts the streaming.
• client.streams.resume(id): Resumes a paused stream.
• client.streams.update(id, payload): Modifies stream parameters, such as the rate.
• client.streams.retrieve(id): Fetches the current state and accumulated amount of a specific stream for monitoring and analytics.

7. List All Streams

Retrieve a list of all active streams in the system using client.streams.list().

8. Stop Streams and Cleanup

Gracefully stop active streams using client.streams.stop(id) and close the StreamConnection instances.

9. Final Transaction Status

After the streams have been stopped, refresh the Transaction models to get their final state, accumulated cost, and metadata.

10. Advanced Conditional Streaming

The example briefly touches upon creating a conditional streaming transaction, where payments might be influenced by factors beyond just time, such as viewer engagement or content quality.

---

Full Code Example

---

Conclusion

🎉 Streaming & Events Demo completed successfully!

This example demonstrates how the Quicksilver SDK simplifies the creation and management of streaming payments, providing powerful real-time capabilities for modern financial applications. By combining fluent transaction creation with StreamConnection for event-driven updates, you can build dynamic, responsive payment systems for a wide range of use cases from content monetization to micro-service billing.

This page showcased how to effectively use the Quicksilver SDK for real-time streaming payments and event handling. For more details on the individual components used here, refer to:

• API Reference: Transaction Model
• API Reference: Resources (Legacy/Advanced) (specifically StreamsResource)