Stream API Reference
The Stream API provides real-time streaming data for Cardano DeFi trading events and pool state changes.
Base URL
/api/v1
Authentication
All endpoints require Bearer token authentication.
Authorization: Bearer YOUR_API_TOKEN
Stream Trading Events
POST /tokens/stream
Subscribe to real-time trading events for specific pools. This endpoint returns a continuous stream of trading data as Server-Sent Events.
Important Limitations:
- Maximum of 1 concurrent connection per API key
- Currently only supports tokens with
group_id = 'Aggregate'
- Stream includes health-check pings every 20 seconds
Request Body
Send a JSON array of pool IDs to subscribe to:
["pool_id_1", "pool_id_2", "pool_id_3"]
Example Request
curl -X POST "https://api.charli3.io/api/v1/tokens/stream" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '[
"fa8dee6cf0627a82a2610019596758fc36c1ebc4b7e389fdabc44857fdf5c9b0e29ac56f1a584bccd487c445ad45383c6347d03d39869f759daad68284781723",
"88726ba865186558078abd49d8b1d1eb2418b824a99afef443197445ee0bab70a96d2f5ab0f7256309b5df0ef56e7f9b0f8a37e84f0f36816badbcee18f04f34",
"b752b73a8a38773b7499a6f9d516ecd14fb68e4c14b1e9a81cc8dac15ee4af1ce83ad10ec59b89f3a9ba38e6a77946239758b370523b57e6ca590472161d048e"
]' \
--no-buffer
Stream Response Format
The stream returns UTF-8 encoded JSON objects, one per line. There are two types of events:
1. Health Check Ping
Sent every 20 seconds to keep the connection alive:
{"s": "ok"}
2. Trading Events
Real-time pool state changes with price and TVL information:
{
"block_time": 1748507314,
"pool_id": "fa8dee6cf0627a82a2610019596758fc36c1ebc4b7e389fdabc44857fdf5c9b0e29ac56f1a584bccd487c445ad45383c6347d03d39869f759daad68284781723",
"current_price": 0.004056495075744993,
"previous_price": 0.003955358842960321,
"current_tvl": 12269324.690049993,
"previous_tvl": 12268951.464835992,
"volume": 186.6126069999882
}
Event Fields:
block_time
: Unix timestamp when the trade occurredpool_id
: Unique identifier of the trading poolcurrent_price
: New price after the tradeprevious_price
: Price before the tradecurrent_tvl
: New Total Value Locked after the tradeprevious_tvl
: TVL before the tradevolume
: Trading volume for this event
3. Error Events
Error messages when something goes wrong:
{
"s": "error",
"errmsg": "Connection limit exceeded"
}
Example Usage
Refer to how-to guide in Use Cases section.
Connection Limits
- 1 concurrent connection per API key
- Attempting multiple connections will result in errors
Error Handling
Common errors and solutions:
Connection Limit Exceeded
{"s": "error", "errmsg": "Connection limit exceeded"}
Solution: Close existing connections before creating new ones.
Invalid Pool IDs
{"s": "error", "errmsg": "Invalid pool ID format"}
Solution: Ensure pool IDs are valid hex strings from the symbol_info endpoint.
Authentication Failed
{"s": "error", "errmsg": "Invalid authentication"}
Solution: Check your Bearer token is valid and included in headers.
Rate Limiting
-
Stream connections count towards your API rate limits. You can subscribe to a limited number of pools on one connection, the number of pools can be managed through your subscription plan. If you don’t have a subscription yet choose the plan.
-
Each trading event received does NOT count as a separate API call.
-
Health check pings do NOT count towards rate limits.
Best Practices
- Handle Reconnections: Implement automatic reconnection with exponential backoff
- Monitor Health: Track ping messages to detect connection issues
- Limit Subscriptions: Only subscribe to pools you actively need
- Buffer Data: Consider buffering events if processing is slow
- Error Logging: Log all errors for debugging connection issues