WebSocket stream of live trades, activities and conversions

curl --request GET \
  --url https://data.gravia.trade/api/v1/streams/transactions \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://data.gravia.trade/api/v1/streams/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://data.gravia.trade/api/v1/streams/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://data.gravia.trade/api/v1/streams/transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://data.gravia.trade/api/v1/streams/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "type": "welcome",
  "server_time": "2026-08-17T12:00:00.123456789Z",
  "sequence": 918473,
  "streams": [
    "trades",
    "activities",
    "conversions"
  ],
  "mempool": false,
  "filters": {
    "wallets": 1,
    "condition_ids": 0,
    "token_ids": 0
  },
  "limits": {
    "max_wallets": 25000,
    "max_markets": 25000,
    "max_filter_batch": 5000
  },
  "source": {
    "connected": true,
    "last_message_at": "2026-08-17T12:00:00.031000000Z",
    "dropped_total": 0
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "user is required",
    "request_id": "01f6c90f31d24db3a25c7dba6ca071ee"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "user is required",
    "request_id": "01f6c90f31d24db3a25c7dba6ca071ee"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "user is required",
    "request_id": "01f6c90f31d24db3a25c7dba6ca071ee"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "user is required",
    "request_id": "01f6c90f31d24db3a25c7dba6ca071ee"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "user is required",
    "request_id": "01f6c90f31d24db3a25c7dba6ca071ee"
  }
}

Streams

WebSocket stream of live trades, activities and conversions

A WebSocket channel, not a request/response endpoint. Connect, and the server pushes rows as they are decoded — confirmed on-chain trades, activities and conversions, plus unconfirmed mempool trades if you ask for them.

wss://data.gravia.trade/api/v1/streams/transactions?streams=trades,activities,conversions&mempool=false

The 101 below is the handshake and carries no HTTP body. Everything the server says afterwards is a WebSocket text frame holding one JSON object. Your WebSocket client performs the upgrade, so Upgrade, Connection and the Sec-WebSocket-* headers are never yours to set, and the query parameters are read once, at connect time.

Browsers cannot set request headers on a handshake, so authenticate there with ?api_key=<your-api-key> and with the Authorization header everywhere else.

const socket = new WebSocket(
  "wss://data.gravia.trade/api/v1/streams/transactions" +
    "?streams=trades&api_key=" + apiKey,
);

socket.addEventListener("message", (frame) => {
  const message = JSON.parse(frame.data);
  switch (message.type) {
    case "trade":
      // status is "confirmed", or "pending" for a mempool trade
      break;
    case "retraction":
      // drop whatever you hold for message.tx_hash on message.stream
      break;
  }
});

// Filters are managed in band, once the socket is open.
socket.send(JSON.stringify({action: "filter.add", wallets: [wallet]}));

Concurrent connections are limited per API key. The service default is one, but a key may be assigned a different allowance. Exceeding it returns 429 with the stream_limit_reached code, which is distinct from ordinary rate limiting: close an existing stream rather than backing off.

Fixed at connect. streams and mempool cannot be changed in band. wallet and market only seed the filters, which are then managed with the client messages below, so a caller holding thousands of selectors is not limited by URL length.

Filters. Both sets are optional; omitting them streams everything. They are ANDed, and selectors within each are ORed. wallet matches the row subject (user_address) only — the counterparty of a fill appears as the subject of its own row, so matching taker_address as well would deliver the same fill several times. A filter change is not retroactive.

Liveness. The server sends a protocol ping every 20 seconds, and a heartbeat frame on any tick where it wrote nothing else, so a quiet stream stays visibly alive to application code that cannot observe protocol pings. A connection that sends nothing at all for 60 seconds is closed; the automatic pong your client already sends is enough to hold it open.

Delivery is at-most-once with no replay. sequence is a server-global ordinal, so a filtered client sees gaps by design; it is not a gap detector, and it is absent from a control frame sent before the server has decoded anything. source.dropped_total in each heartbeat counts rows the server discarded because it was behind, which is the only loss a client cannot otherwise detect. Read the REST endpoints when completeness matters.

Retractions ignore the wallet and market filters, because a reorg retraction carries no rows and therefore no wallet or market; stream selection still applies. Ignore one for a tx_hash you hold no state for. Pending trades are never retracted, and a pending trade may never land — time out your own pending state. With mempool=true a landed trade is delivered twice, once pending and once confirmed; deduplicate on (tx_hash, order_hash).

Close codes. 1008 with client is too slow means the server gave up writing to you and dropped the connection rather than waiting; reconnect with tighter filters or a faster reader. 1001 with server is shutting down is a deploy — reconnect. Anything that fails before the upgrade is ordinary HTTP, listed under Responses below.

Client messages

One JSON object per text frame, discriminated by action. Unknown keys are rejected, and every frame — ping included — is counted against a budget of 20 commands per second with a burst of 40.

{"action": "filter.add", "wallets": ["0x674887d1ac838099a48b629dff53f25b7b87ee08"]}
{"action": "filter.remove", "markets": ["67568438763601610729831023256910933987242052537121118642143709840881218761985"]}
{"action": "filter.set", "markets": ["0xb4386b7dacda0f3148be799de8d992e1f3cb3646ecb42b6c09485ed7d6feffc7"]}
{"action": "filter.clear", "target": "wallets"}
{"action": "filter.list", "include_values": true}
{"action": "ping"}

wallets entries are 0x-prefixed 20-byte addresses; usernames are rejected. markets entries are classified by shape: 0x followed by 64 hex is a condition id, a decimal string is a CLOB token id. Market slugs and category: selectors are not accepted here. target is wallets, markets or all, and defaults to all. A batch applies atomically: one malformed entry rejects the whole message and leaves the filter set untouched. At most 5,000 entries per message; welcome reports the standing caps in limits.

Server messages

Every frame carries a type, and type is the only field to dispatch on.

`type`	Sent when	Structure
`welcome`	Once, immediately after the handshake.	`TransactionStreamWelcome`
`trade`	A trade was decoded. `status` is `confirmed`, or `pending` for a mempool trade.	`TransactionStreamTrade`
`activity`	A split, merge or redemption was decoded.	`TransactionStreamActivity`
`conversion`	A NegRisk conversion was decoded.	`TransactionStreamConversion`
`retraction`	A transaction was reorged out.	`TransactionStreamRetraction`
`heartbeat`	A ping tick passed with nothing else to write.	`TransactionStreamHeartbeat`
`filter.updated`	A filter command was applied.	`TransactionStreamFilterUpdated`
`filter.rejected`	A filter command was refused and nothing changed.	`TransactionStreamFilterRejected`
`filter.snapshot`	Reply to `filter.list`.	`TransactionStreamFilterSnapshot`
`error`	A frame could not be handled. The socket stays open.	`TransactionStreamError`
`pong`	Reply to `{"action": "ping"}`.	`TransactionStreamPong`

A trade, activity or conversion frame is the decoded upstream row forwarded whole, with type and sequence added in front, so treat unrecognized fields as forward-compatible additions rather than errors. v is the upstream row schema version, currently 2. Money, size and price fields cross as decimal strings, and so do token ids: they are 256-bit, and a JSON number would silently lose precision. partial marks a row where the fields named in missing read as unknown rather than zero.

welcome — once, immediately after the handshake:

{
  "type": "welcome",
  "server_time": "2026-08-17T12:00:00.123456789Z",
  "sequence": 918473,
  "streams": ["trades", "activities", "conversions"],
  "mempool": false,
  "filters": {"wallets": 1, "condition_ids": 0, "token_ids": 0},
  "limits": {"max_wallets": 25000, "max_markets": 25000, "max_filter_batch": 5000},
  "source": {
    "connected": true,
    "last_message_at": "2026-08-17T12:00:00.031000000Z",
    "dropped_total": 0
  }
}

trade — a confirmed fill:

{
  "type": "trade",
  "sequence": 918501,
  "v": 2,
  "stream": "trades",
  "status": "confirmed",
  "block_number": 91937590,
  "block_hash": "0x7c1b9f3a2d8e4c5b6a0f9e8d7c6b5a4938271605f4e3d2c1b0a9f8e7d6c5b4a3",
  "block_timestamp": 1786924800,
  "tx_hash": "0x3f8c1d9b7a5e4c2b0d9f8e7a6c5b4d3e2f1a09b8c7d6e5f4a3b2c1d0e9f8a7b6",
  "tx_row_index": 1,
  "tx_row_count": 3,
  "partial": false,
  "missing": [],
  "published_at": 1786924801.312,
  "log_index": 42,
  "order_hash": "0x5e4d3c2b1a09f8e7d6c5b4a3928170615f4e3d2c1b0a9f8e7d6c5b4a39281706",
  "order_hash_alt": null,
  "user_address": "0x674887d1ac838099a48b629dff53f25b7b87ee08",
  "taker_address": "0x9c1a5f3b2d8e4c6b7a0f9e8d7c6b5a4938271605",
  "side": "BUY",
  "token_id": "67568438763601610729831023256910933987242052537121118642143709840881218761985",
  "canonical_token_id": "67568438763601610729831023256910933987242052537121118642143709840881218761985",
  "condition_id": "0xb4386b7dacda0f3148be799de8d992e1f3cb3646ecb42b6c09485ed7d6feffc7",
  "shares": "20000",
  "usdc_amount": "9800.5",
  "share_price": "0.49",
  "fee_amount": "0",
  "fee_refund_amount": "0",
  "trade_timestamp": 1786924800,
  "contract_version": 2,
  "is_taker_order": true,
  "builder": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "metadata": "0x0000000000000000000000000000000000000000000000000000000000000000"
}

A pending mempool trade is the same frame with status: "pending". It has no block yet, so block_number and log_index are 0, block_hash and block_timestamp are null, and canonical_token_id is null; order_hash_alt may carry the NegRisk candidate order hash, so match a pending trade against its confirmation on either hash.

activity — a split, merge or redemption:

{
  "type": "activity",
  "sequence": 918502,
  "v": 2,
  "stream": "activities",
  "status": "confirmed",
  "block_number": 91937590,
  "block_hash": "0x7c1b9f3a2d8e4c5b6a0f9e8d7c6b5a4938271605f4e3d2c1b0a9f8e7d6c5b4a3",
  "block_timestamp": 1786924800,
  "tx_hash": "0x3f8c1d9b7a5e4c2b0d9f8e7a6c5b4d3e2f1a09b8c7d6e5f4a3b2c1d0e9f8a7b6",
  "tx_row_index": 2,
  "tx_row_count": 3,
  "partial": false,
  "missing": [],
  "published_at": 1786924801.312,
  "event_type": "RedeemPosition",
  "log_index": 7,
  "user_address": "0x674887d1ac838099a48b629dff53f25b7b87ee08",
  "token_id": "67568438763601610729831023256910933987242052537121118642143709840881218761985",
  "canonical_token_id": "34460519301295595556376203968565021162434252843477398085423120621766516073216",
  "condition_id": "0xb4386b7dacda0f3148be799de8d992e1f3cb3646ecb42b6c09485ed7d6feffc7",
  "price": "1",
  "amount": "20000",
  "collateral_token": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  "parent_collection_id": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "activity_timestamp": 1786924800,
  "is_neg_ctf": false,
  "contract_version": 2,
  "auto_redeem": false
}

conversion — a NegRisk conversion leg:

{
  "type": "conversion",
  "sequence": 918503,
  "v": 2,
  "stream": "conversions",
  "status": "confirmed",
  "block_number": 91937590,
  "block_hash": "0x7c1b9f3a2d8e4c5b6a0f9e8d7c6b5a4938271605f4e3d2c1b0a9f8e7d6c5b4a3",
  "block_timestamp": 1786924800,
  "tx_hash": "0x3f8c1d9b7a5e4c2b0d9f8e7a6c5b4d3e2f1a09b8c7d6e5f4a3b2c1d0e9f8a7b6",
  "tx_row_index": 3,
  "tx_row_count": 3,
  "partial": false,
  "missing": [],
  "published_at": 1786924801.312,
  "log_index": 3,
  "user_address": "0x674887d1ac838099a48b629dff53f25b7b87ee08",
  "token_id": "67568438763601610729831023256910933987242052537121118642143709840881218761985",
  "canonical_token_id": "34460519301295595556376203968565021162434252843477398085423120621766516073216",
  "condition_id": "0xb4386b7dacda0f3148be799de8d992e1f3cb3646ecb42b6c09485ed7d6feffc7",
  "negrisk_market_id": "0x0b8f7e6d5c4b3a29180706f5e4d3c2b1a0f9e8d7c6b5a4938271605f4e3d2c1b",
  "amount": "250",
  "conversion_timestamp": 1786924800,
  "contract_version": 2
}

retraction — the transaction was reorged out. It carries no row fields at all, so undo state by tx_hash and stream:

{
  "type": "retraction",
  "sequence": 918504,
  "v": 2,
  "stream": "trades",
  "status": "retracted",
  "tx_hash": "0x3f8c1d9b7a5e4c2b0d9f8e7a6c5b4d3e2f1a09b8c7d6e5f4a3b2c1d0e9f8a7b6",
  "block_number": 91937590,
  "block_hash": "0x7c1b9f3a2d8e4c5b6a0f9e8d7c6b5a4938271605f4e3d2c1b0a9f8e7d6c5b4a3",
  "published_at": 1786924802.881
}

heartbeat — nothing else was written on this tick:

{
  "type": "heartbeat",
  "server_time": "2026-08-17T12:00:20.001002003Z",
  "sequence": 918504,
  "source": {
    "connected": true,
    "last_message_at": "2026-08-17T12:00:19.900000000Z",
    "dropped_total": 12
  }
}

filter.updated — the command was applied. added and removed are net count deltas, not the values applied, so a filter.set that swaps one wallet for another reports zero of each:

{
  "type": "filter.updated",
  "filters": {"wallets": 2, "condition_ids": 0, "token_ids": 1},
  "added": {"wallets": 1, "condition_ids": 0, "token_ids": 1},
  "removed": {"wallets": 0, "condition_ids": 0, "token_ids": 0}
}

filter.rejected — nothing was applied. A validation failure names every entry it refused; a cap failure carries only code and message:

{
  "type": "filter.rejected",
  "code": "invalid_filter",
  "message": "no changes were applied",
  "rejected": [
    {"value": "polymarket-btc-up-or-down", "reason": "market slugs are not supported; use a condition id or CLOB token id"},
    {"value": "@trader", "reason": "usernames are not supported; use a 0x-prefixed 20-byte address"}
  ]
}

{
  "type": "filter.rejected",
  "code": "filter_limit_reached",
  "message": "txstream: filter limit reached: at most 25000 wallets"
}

filter.snapshot — the reply to filter.list. values is present only when the request set include_values: true, each list is capped at 1,000 entries, and truncated says whether any list was cut short:

{
  "type": "filter.snapshot",
  "sequence": 918505,
  "filters": {"wallets": 1, "condition_ids": 1, "token_ids": 0},
  "values": {
    "wallets": ["0x674887d1ac838099a48b629dff53f25b7b87ee08"],
    "condition_ids": ["0xb4386b7dacda0f3148be799de8d992e1f3cb3646ecb42b6c09485ed7d6feffc7"],
    "token_ids": [],
    "truncated": false
  }
}

error — the frame could not be handled. Non-fatal: the socket stays open and the filters are untouched:

{
  "type": "error",
  "code": "unsupported_message",
  "message": "action must be filter.add, filter.remove, filter.set, filter.clear, filter.list or ping"
}

pong — the reply to {"action": "ping"}, and nothing more:

{"type": "pong"}

GET

api

streams

transactions

WebSocket stream of live trades, activities and conversions

curl --request GET \
  --url https://data.gravia.trade/api/v1/streams/transactions \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://data.gravia.trade/api/v1/streams/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://data.gravia.trade/api/v1/streams/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://data.gravia.trade/api/v1/streams/transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://data.gravia.trade/api/v1/streams/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "type": "welcome",
  "server_time": "2026-08-17T12:00:00.123456789Z",
  "sequence": 918473,
  "streams": [
    "trades",
    "activities",
    "conversions"
  ],
  "mempool": false,
  "filters": {
    "wallets": 1,
    "condition_ids": 0,
    "token_ids": 0
  },
  "limits": {
    "max_wallets": 25000,
    "max_markets": 25000,
    "max_filter_batch": 5000
  },
  "source": {
    "connected": true,
    "last_message_at": "2026-08-17T12:00:00.031000000Z",
    "dropped_total": 0
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "user is required",
    "request_id": "01f6c90f31d24db3a25c7dba6ca071ee"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "user is required",
    "request_id": "01f6c90f31d24db3a25c7dba6ca071ee"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "user is required",
    "request_id": "01f6c90f31d24db3a25c7dba6ca071ee"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "user is required",
    "request_id": "01f6c90f31d24db3a25c7dba6ca071ee"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "user is required",
    "request_id": "01f6c90f31d24db3a25c7dba6ca071ee"
  }
}

Authorizations

Authorization

string

header

required

Raw database-backed API key.

Query Parameters

wallet

string

Up to 100 comma-separated 0x-prefixed 20-byte addresses to seed the wallet filter. Usernames are not accepted. Use filter.add for larger sets.

market

string

Up to 100 comma-separated condition ids (0x + 64 hex) or decimal CLOB token ids. Market slugs and category: selectors are not supported. A condition id selects both outcomes; a token id selects one.

streams

string

Comma-separated subset of trades, activities, conversions. Defaults to all three. Fixed for the life of the connection.

mempool

boolean

Opt in to unconfirmed mempool trades in addition to confirmed ones. Requires the trades stream.

api_key

string

API key, for clients that cannot set request headers on a WebSocket handshake. The Authorization header takes precedence and should be preferred; this value is redacted from access logs and usage records.

Response

The handshake succeeded and the socket is open; the server sends welcome first. There is no HTTP response body — the schema below is the union of the JSON frames the server then pushes, discriminated by type.

One frame the transaction stream sends. These are WebSocket text frames on an open socket, not HTTP response bodies. type is the discriminator and the only field a client dispatches on.

type

enum<string>

required

Available options:

welcome

server_time

string<date-time>

required

streams

enum<string>[]

required

The streams this connection will receive, in a fixed order. Reflects ?streams=, which defaults to all three.

Available options:

trades,

activities,

conversions

mempool

boolean

required

Whether unconfirmed mempool trades are included.

filters

object

required

Sizes of a connection's filter sets. Counts rather than values: a client may hold tens of thousands of entries, and an acknowledgement should not echo them all back.

Show child attributes

Example:

{
  "wallets": 2,
  "condition_ids": 0,
  "token_ids": 1
}

limits

object

required

The caps this connection works within, reported on welcome so a client can batch correctly instead of discovering them by rejection.

Show child attributes

Example:

{
  "max_wallets": 25000,
  "max_markets": 25000,
  "max_filter_batch": 5000
}

source

object

required

Upstream feed health, on welcome and heartbeat frames.

Show child attributes

Example:

{
  "connected": true,
  "last_message_at": "2026-08-17T12:00:00.031000000Z",
  "dropped_total": 0
}

sequence

integer<int64>

The server-global ordinal at connect time. Absent when the server has not decoded any upstream message yet.

Webhooks

Operational

Markets

Users

Streams

WebSocket stream of live trades, activities and conversions

Client messages

Server messages

Authorizations

Query Parameters

Response