Token Stream API Reference

The Token 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 occurred
• pool_id: Unique identifier of the trading pool
• current_price: New price after the trade
• previous_price: Price before the trade
• current_tvl: New Total Value Locked after the trade
• previous_tvl: TVL before the trade
• volume: 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

1. Handle Reconnections: Implement automatic reconnection with exponential backoff
2. Monitor Health: Track ping messages to detect connection issues
3. Limit Subscriptions: Only subscribe to pools you actively need
4. Buffer Data: Consider buffering events if processing is slow
5. Error Logging: Log all errors for debugging connection issues