Low-latency real-time WebSocket streaming over a JSON-RPC 2.0 subscribe interface for spot trades and prices, DEX data, and on-chain events, authenticated with the x-api-key header.
asyncapi: '2.6.0'
id: 'urn:io:amberdata:ws:web3api:streaming'
info:
title: Amberdata WebSocket Streaming API
version: '1.0.0'
description: |
AsyncAPI 2.6 description of Amberdata's **real-time WebSocket streaming**
surface.
Unlike the Groq reference (which exposes no WebSocket), Amberdata DOES
publish a documented public WebSocket API. Clients open a secure WebSocket
connection to `wss://ws.web3api.io` and authenticate with the same
`x-api-key` header used for REST. Subscriptions are managed with
**JSON-RPC 2.0** request messages (`method: "subscribe"` /
`method: "unsubscribe"`); the server then pushes a stream of update
messages for each subscribed topic.
Example connection (from Amberdata docs):
`wscat -c "wss://ws.web3api.io" -H "x-api-key: <api-key>"`
Topics are colon-delimited channel names such as `market:spot:trades`,
`market:spot:prices`, and on-chain event channels. A subscription's params
array carries the channel name plus a filter object (e.g. exchange + pair).
This document models the JSON-RPC subscribe/unsubscribe control messages
and the streamed update messages. REST request/response shapes are modeled
in the companion OpenAPI document at `openapi/amberdata-openapi.yml`.
contact:
name: API Evangelist
email: kin@apievangelist.com
url: https://apievangelist.com
license:
name: API documentation - Amberdata Terms of Service
url: https://www.amberdata.io/terms-of-service
x-transport-notes:
transport: WebSocket (secure)
protocol: wss
direction: bidirectional
controlProtocol: JSON-RPC 2.0
auth: 'x-api-key header sent on the WebSocket upgrade request'
source: https://docs.amberdata.io/real-time/websocket-getting-started
defaultContentType: application/json
servers:
web3api:
url: ws.web3api.io
protocol: wss
description: |
Amberdata real-time WebSocket endpoint for blockchain and market data.
Authenticate by sending the `x-api-key` header on the connection upgrade
request. After connecting, send JSON-RPC 2.0 `subscribe` messages to
begin receiving topic updates.
security:
- apiKeyAuth: []
channels:
market:spot:trades:
description: |
Real-time spot trade stream. Subscribe with a JSON-RPC 2.0 message whose
params are `["market:spot:trades", { "exchange": "binance", "pair":
"btc_usdt" }]`. The server then pushes a trade update message for each
executed trade matching the filter.
publish:
operationId: subscribeSpotTrades
summary: Send a JSON-RPC subscribe/unsubscribe request for spot trades.
message:
oneOf:
- $ref: '#/components/messages/SubscribeRequest'
- $ref: '#/components/messages/UnsubscribeRequest'
subscribe:
operationId: receiveSpotTrades
summary: Receive streamed spot trade updates.
message:
$ref: '#/components/messages/SpotTradeUpdate'
market:spot:prices:
description: |
Real-time spot price stream. Subscribe with params
`["market:spot:prices", { "pair": "eth_usd" }]` to receive latest price
updates as they occur.
publish:
operationId: subscribeSpotPrices
summary: Send a JSON-RPC subscribe/unsubscribe request for spot prices.
message:
oneOf:
- $ref: '#/components/messages/SubscribeRequest'
- $ref: '#/components/messages/UnsubscribeRequest'
subscribe:
operationId: receiveSpotPrices
summary: Receive streamed spot price updates.
message:
$ref: '#/components/messages/SpotPriceUpdate'
components:
securitySchemes:
apiKeyAuth:
type: httpApiKey
in: header
name: x-api-key
description: |
Amberdata API key sent as the `x-api-key` header on the WebSocket
upgrade (connection) request. The same key used for the REST API.
messages:
SubscribeRequest:
name: SubscribeRequest
title: JSON-RPC subscribe request
summary: Client message that subscribes to a topic.
contentType: application/json
payload:
$ref: '#/components/schemas/JsonRpcSubscribe'
examples:
- name: subscribeTrades
summary: Subscribe to Binance BTC/USDT spot trades
payload:
jsonrpc: '2.0'
id: 1
method: subscribe
params:
- market:spot:trades
- exchange: binance
pair: btc_usdt
UnsubscribeRequest:
name: UnsubscribeRequest
title: JSON-RPC unsubscribe request
summary: Client message that unsubscribes from a topic by subscription id.
contentType: application/json
payload:
$ref: '#/components/schemas/JsonRpcUnsubscribe'
examples:
- name: unsubscribe
summary: Unsubscribe from a previously returned subscription id
payload:
jsonrpc: '2.0'
id: 2
method: unsubscribe
params:
- 0xb
SpotTradeUpdate:
name: SpotTradeUpdate
title: Spot trade update
summary: A single real-time spot trade event pushed by the server.
contentType: application/json
payload:
$ref: '#/components/schemas/SpotTrade'
examples:
- name: trade
summary: Trade update message
payload:
jsonrpc: '2.0'
method: subscription
params:
subscription: '0xb'
result:
exchange: binance
pair: btc_usdt
price: '64850.10'
volume: '0.0125'
timestamp: 1750464000000
isBuySide: true
SpotPriceUpdate:
name: SpotPriceUpdate
title: Spot price update
summary: A real-time latest-price event pushed by the server.
contentType: application/json
payload:
$ref: '#/components/schemas/SpotPrice'
examples:
- name: price
summary: Price update message
payload:
jsonrpc: '2.0'
method: subscription
params:
subscription: '0xc'
result:
pair: eth_usd
price: '3420.55'
timestamp: 1750464000000
schemas:
JsonRpcSubscribe:
type: object
required:
- jsonrpc
- id
- method
- params
properties:
jsonrpc:
type: string
enum:
- '2.0'
id:
type: integer
description: Client-generated request identifier.
method:
type: string
enum:
- subscribe
params:
type: array
description: >-
First element is the channel/topic name (e.g. market:spot:trades);
the second element is an optional filter object.
items: {}
JsonRpcUnsubscribe:
type: object
required:
- jsonrpc
- id
- method
- params
properties:
jsonrpc:
type: string
enum:
- '2.0'
id:
type: integer
method:
type: string
enum:
- unsubscribe
params:
type: array
description: The subscription id returned when the subscription was created.
items:
type: string
SpotTrade:
type: object
description: Envelope of a streamed spot trade update.
properties:
jsonrpc:
type: string
enum:
- '2.0'
method:
type: string
enum:
- subscription
params:
type: object
properties:
subscription:
type: string
description: The subscription id this update belongs to.
result:
type: object
properties:
exchange:
type: string
pair:
type: string
price:
type: string
volume:
type: string
timestamp:
type: integer
description: Event time in milliseconds since epoch.
isBuySide:
type: boolean
SpotPrice:
type: object
description: Envelope of a streamed spot price update.
properties:
jsonrpc:
type: string
enum:
- '2.0'
method:
type: string
enum:
- subscription
params:
type: object
properties:
subscription:
type: string
result:
type: object
properties:
pair:
type: string
price:
type: string
timestamp:
type: integer
description: Event time in milliseconds since epoch.