Transaction Streams

Real-time WebSocket streams for monitoring agent wallet transactions, settlement events, and payment status updates.

Overview

WebSocket URL: wss://api.clawfirst.xyz/v1/transactions/stream

Connection Limits:

  • Developer: 2 concurrent connections, 10 updates/second

  • Production: 10 concurrent connections, 100 updates/second

  • Enterprise: Custom limits

Use Cases

  • Real-time agent dashboards: Monitor active agent transactions live

  • Reactive workflows: Trigger agent actions on settlement events

  • Multi-agent coordination: Synchronize agents based on transaction state

  • Testing & debugging: Watch transaction flow during development

Connecting

Python/OpenClaw

TypeScript/MCP

Authentication

Send API key immediately after connection:

Response:

Subscription Methods

Subscribe to Wallet

Monitor all transactions for a specific wallet address:

Response:

Subscribe to Transaction

Monitor a specific transaction signature:

Unsubscribe

Event Types

Transaction Update

Emitted when transaction status changes:

Settlement Finalized

Emitted when transaction reaches 32 confirmations:

Transaction Failed

Emitted when transaction fails on-chain:

Error Event

Advanced Usage

Reconnection with Exponential Backoff

Multi-Agent Transaction Coordination

Heartbeat/Keep-Alive

Send periodic pings to maintain connection:

Error Codes

Code
Description
Action

AUTHENTICATION_FAILED

Invalid API key

Check API key validity

SUBSCRIPTION_FAILED

Invalid wallet address

Verify wallet address format

RATE_LIMIT_EXCEEDED

Too many messages

Reduce message frequency

CONNECTION_LIMIT_EXCEEDED

Too many concurrent connections

Close unused connections

Best Practices

  1. Implement Reconnection: Always handle disconnections with exponential backoff

  2. Authenticate Immediately: Send auth message right after connection opens

  3. Track Subscriptions: Maintain list of subscriptions for reconnection

  4. Use Heartbeats: Send periodic pings to detect connection issues early

  5. Handle Errors: Monitor error events and log them for debugging

  6. Limit Subscriptions: Don't subscribe to more wallets than necessary

  7. Clean Disconnection: Properly close connections when shutting down

Rate Limiting

WebSocket connections have separate rate limits from MCP tool calls:

Plan
Concurrent Connections
Updates/Second
Messages/Minute

Developer

2

10

100

Production

10

100

1,000

Enterprise

Custom

Custom

Custom

Exceeding rate limits results in temporary connection throttling or disconnection.

Next Steps

Last updated