Real-time
Our real-time API pushes new rates, exchange rates, and tickers to you as soon as they are calculated. The REST endpoints update once a minute; a real-time connection delivers every update in between, without polling.
Topics
There are three topics. Each one is available over both transports, with the same query parameters and the same messages.
| Topic | What you receive | Subscribe to |
|---|---|---|
| Rates | The aggregated price and 24 hour volume of a coin, across all exchanges. | Coins |
| Exchange Rates | The price and 24 hour volume of a coin on one exchange. | Exchange-coin pairs, exchanges, or coins |
| Tickers | Trading pair data per market, including base and quote volumes. | Markets, exchanges, or coins |
Choosing a transport
WebSockets and Server-Sent Events (SSE) deliver exactly the same JSON messages. Only the way you connect differs, so you can switch from one to the other without changing how you handle the data. The URLs only differ in the scheme and the /sse segment:
wss://api.coinranking.com/v2/real-time/rates
https://api.coinranking.com/v2/real-time/sse/rates
| WebSockets | Server-Sent Events | |
|---|---|---|
| Connection | Two-way WebSocket connection | One-way: a regular GET request whose response stays open |
| Changing subscriptions | Send a subscription message on the open connection | Close the current stream and open a new one with the new URL |
| Reconnecting | Reconnect with the same URL; send subscriptions you set with a message again | Reconnect with the same URL, which restores everything; EventSource does this automatically |
| Errors | An error message on the open connection; browsers hide why a connection is refused | A normal HTTP status with a JSON error body |
| Trying it out | Needs a WebSocket client | curl in a terminal |
| Clients | The browser's WebSocket, or any WebSocket library |
curl, fetch, the browser's EventSource, or any HTTP library that can read a streaming response |
Delivery is the same on both: the server sends every message to WebSocket and Server-Sent Events clients at the same moment, both transports send a heartbeat every 25 seconds, and both end when the real-time service is deployed, so every client needs to reconnect. Neither replays messages that were sent while you were disconnected. Choose the transport that fits how your application works.
Server-Sent Events: the simplest to build and debug
- Works with
curl,fetch, and any HTTP library, without an extra dependency. - A rejected request explains itself with an HTTP status and an error
code. - The subscription lives in the URL, so reconnecting restores everything.
- Easy to proxy through your own server, which keeps your API key out of the browser.
WebSockets: the best fit when subscriptions change
- Change what you receive on the open connection, for example when a user edits a watchlist, without reconnecting.
- Connect once, then subscribe and resubscribe as the user moves through your application.
- Supported by the browser and by WebSocket libraries for every major language.
Plans and API usage
Real-time connections count toward the API usage of your plan. See pricing for the limits of each plan.
Starting values
A connection carries updates only; it does not send the current values when it opens. If your application needs a starting value before the first update arrives, fetch it from the coins, exchange coin listings, or markets endpoints first.
Previous
Next