> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coingecko.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OnchainTrade
> Real-time onchain DEX trade updates by pool address
### Notes
* Streams real-time trade/swap updates for pools by network and pool address.
* Returns transaction type (buy/sell), tx hash, token amounts, volume, and price data.
* Lookup format: `network_id:pool_address` (e.g. `bsc:0x172fcd41e0913e95784454622d1c3724f546f849`).
* Find supported network IDs via [Networks List](/reference/networks-list).
* Use [Top Pools by Token Address](/reference/top-pools-contract-address) to find the most liquid pool address.
* Fields may return `null` when data is unavailable. Ensure your application handles null values.
Update Frequency:
As fast as \~0.1 seconds for actively traded pools.
### Data Payload
| Key | Field | Type | Description | Example |
| ----- | -------------------------- | ------- | --------------------------------------- | -------------------------------------------- |
| `c` | `channel_type` | string | Channel type subscribed to. | `G2` |
| `n` | `network_id` | string | Blockchain network identifier. | `bsc` |
| `pa` | `pool_address` | string | Pool contract address. | `0x172fcd41e0913e95784454622d1c3724f546f849` |
| `tx` | `tx_hash` | string | Transaction hash. | `0x743b271e...5adf698` |
| `ty` | `type` | string | Trade type (`b` = buy, `s` = sell). | `b` |
| `to` | `token_amount` | number | Base token amount. | 0.037 |
| `toq` | `quote_token_amount` | number | Quote token amount. | 0.0000626 |
| `vo` | `volume_in_usd` | number | Trade volume in USD. | 0.037 |
| `pc` | `price_in_native_currency` | number | Token price in network native currency. | 0.0017 |
| `pu` | `price_in_usd` | number | Token price in USD. | 0.999 |
| `t` | `last_updated_at` | integer | UNIX timestamp in milliseconds. | 1780840929000 |
***
### 1. Establish Connection
```bash theme={null}
wss://stream.coingecko.com/v1?x_cg_pro_api_key=YOUR_KEY
```
You can also pass the key as a header: `x-cg-pro-api-key: YOUR_KEY`
**Output:**
```json theme={null}
{
"code": 3000,
"message": "Connection established",
"uuid": "YOUR_SESSION_ID"
}
```
```json theme={null}
{
"type": "welcome",
"sid": "YOUR_SESSION_ID"
}
```
***
### 2. Subscribe to OnchainTrade
**Input:**
```json wrap theme={null}
{"command":"subscribe","identifier":"{\"channel\":\"OnchainTrade\"}"}
```
**Output:**
```json theme={null}
{
"type": "confirm_subscription",
"identifier": "{\"channel\":\"OnchainTrade\"}"
}
```
***
### 3. Stream Trade Data
**Input:**
```json wrap theme={null}
{"command":"message","identifier":"{\"channel\":\"OnchainTrade\"}","data":"{\"network_id:pool_addresses\":[\"bsc:0x172fcd41e0913e95784454622d1c3724f546f849\"],\"action\":\"set_pools\"}"}
```
**Output:**
```json theme={null}
{
"code": 2000,
"message": "Subscription successful for bsc:0x172fcd41e0913e95784454622d1c3724f546f849"
}
```
**Streaming output:**
```json theme={null}
{
"c": "G2",
"n": "bsc",
"pa": "0x172fcd41e0913e95784454622d1c3724f546f849",
"tx": "0x3aa702e87ebc87cc4f877ab494afa0ac59f46873c147ee406a546c1e12ab5f57",
"ty": "s",
"to": 0.0369078635593666,
"toq": 0.000062600168318069,
"vo": 0.036858979105679,
"pc": 0.0016961200752619,
"pu": 0.998675500314209,
"t": 1780840929000
}
```
Output keys may appear in any order.
***
### 4. Unsubscribe
**Unsubscribe from a specific pool:**
```json wrap theme={null}
{"command":"message","identifier":"{\"channel\":\"OnchainTrade\"}","data":"{\"network_id:pool_addresses\":[\"bsc:0x172fcd41e0913e95784454622d1c3724f546f849\"],\"action\":\"unset_pools\"}"}
```
```json theme={null}
{
"code": 2000,
"message": "Unsubscription is successful for bsc:0x172fcd41e0913e95784454622d1c3724f546f849"
}
```
**Unsubscribe from the channel entirely:**
```json wrap theme={null}
{"command":"unsubscribe","identifier":"{\"channel\":\"OnchainTrade\"}"}
```
```json theme={null}
{
"code": 2000,
"message": "Unsubscription is successful for all pools"
}
```
***
## AsyncAPI
````yaml websocket/asyncapi.json onchaintrade
id: onchaintrade
title: Onchaintrade
description: Real-time onchain DEX trade updates by pool address
servers:
- id: production
protocol: wss
host: stream.coingecko.com
bindings: []
variables: []
address: /v1
parameters: []
bindings: []
operations:
- &ref_1
id: subscribeToOnchainTrade
title: 'OnchainTrade: Subscribe'
description: To subscribe to the OnchainTrade channel for receiving DEX trade updates
type: receive
messages:
- &ref_4
id: subscribe
payload:
- name: Subscribe to OnchainTrade
description: Subscribe to the OnchainTrade channel
type: object
properties:
- name: command
type: string
description: Subscription command
enumValues:
- subscribe
required: true
- name: identifier
type: string
description: JSON string specifying the target channel
required: true
headers: []
jsonPayloadSchema:
type: object
required:
- command
- identifier
properties:
command:
type: string
enum:
- subscribe
default: subscribe
description: Subscription command
x-parser-schema-id:
identifier:
type: string
default: '{"channel":"OnchainTrade"}'
description: JSON string specifying the target channel
x-parser-schema-id:
x-parser-schema-id:
title: Subscribe to OnchainTrade
description: Subscribe to the OnchainTrade channel
example: |-
{
"command": "",
"identifier": ""
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribe
bindings: []
extensions: &ref_0
- id: x-parser-unique-object-id
value: onchaintrade
- &ref_2
id: streamOnchainTrade
title: 'OnchainTrade: Stream Data'
description: To set which pools to stream trade data for, by network and pool address
type: receive
messages:
- &ref_5
id: stream
payload:
- name: Stream OnchainTrade Data
description: Set pools to receive trade updates for
type: object
properties:
- name: command
type: string
description: Message command
enumValues:
- message
required: true
- name: identifier
type: string
description: JSON string specifying the target channel
required: true
- name: data
type: string
description: >-
JSON string with network_id:pool_addresses array, format:
network_id:pool_address
required: true
headers: []
jsonPayloadSchema:
type: object
required:
- command
- identifier
- data
properties:
command:
type: string
enum:
- message
default: message
description: Message command
x-parser-schema-id:
identifier:
type: string
default: '{"channel":"OnchainTrade"}'
description: JSON string specifying the target channel
x-parser-schema-id:
data:
type: string
default: >-
{"network_id:pool_addresses":["bsc:0x172fcd41e0913e95784454622d1c3724f546f849"],"action":"set_pools"}
example: >-
{"network_id:pool_addresses":["bsc:0x172fcd41e0913e95784454622d1c3724f546f849"],"action":"set_pools"}
description: >-
JSON string with network_id:pool_addresses array, format:
network_id:pool_address
x-parser-schema-id:
x-parser-schema-id:
title: Stream OnchainTrade Data
description: Set pools to receive trade updates for
example: |-
{
"command": "",
"identifier": "",
"data": ""
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: stream
bindings: []
extensions: *ref_0
- &ref_3
id: receiveOnchainTradeUpdates
title: 'OnchainTrade: Receive Updates'
description: >-
To receive real-time DEX trade updates including buy/sell type, amounts,
and prices
type: send
messages:
- &ref_6
id: update
payload:
- name: OnchainTrade Update
description: Real-time DEX trade update from server
type: object
properties:
- name: c
type: string
description: Channel type
required: false
- name: 'n'
type: string
description: Network identifier
required: false
- name: pa
type: string
description: Pool contract address
required: false
- name: tx
type: string
description: Transaction hash
required: false
- name: ty
type: string
description: Trade type (b=buy, s=sell)
required: false
- name: to
type: number
description: Base token amount
required: false
- name: toq
type: number
description: Quote token amount
required: false
- name: vo
type: number
description: Trade volume in USD
required: false
- name: pc
type: number
description: Price in quote token
required: false
- name: pu
type: number
description: Price in USD
required: false
- name: t
type: integer
description: UNIX timestamp in milliseconds
required: false
headers: []
jsonPayloadSchema:
type: object
properties:
c:
type: string
example: G2
description: Channel type
x-parser-schema-id:
'n':
type: string
example: bsc
description: Network identifier
x-parser-schema-id:
pa:
type: string
example: '0x172fcd41e0913e95784454622d1c3724f546f849'
description: Pool contract address
x-parser-schema-id:
tx:
type: string
example: >-
0x3aa702e87ebc87cc4f877ab494afa0ac59f46873c147ee406a546c1e12ab5f57
description: Transaction hash
x-parser-schema-id:
ty:
type: string
example: s
description: Trade type (b=buy, s=sell)
x-parser-schema-id:
to:
type: number
example: 0.0369078635593666
description: Base token amount
x-parser-schema-id:
toq:
type: number
example: 0.000062600168318069
description: Quote token amount
x-parser-schema-id:
vo:
type: number
example: 0.036858979105679
description: Trade volume in USD
x-parser-schema-id:
pc:
type: number
example: 0.0016961200752619
description: Price in quote token
x-parser-schema-id:
pu:
type: number
example: 0.998675500314209
description: Price in USD
x-parser-schema-id:
t:
type: integer
example: 1780840929000
description: UNIX timestamp in milliseconds
x-parser-schema-id:
x-parser-schema-id:
title: OnchainTrade Update
description: Real-time DEX trade update from server
example: |-
{
"c": "G2",
"n": "bsc",
"pa": "0x172fcd41e0913e95784454622d1c3724f546f849",
"tx": "0x3aa702e87ebc87cc4f877ab494afa0ac59f46873c147ee406a546c1e12ab5f57",
"ty": "s",
"to": 0.0369078635593666,
"toq": 0.000062600168318069,
"vo": 0.036858979105679,
"pc": 0.0016961200752619,
"pu": 0.998675500314209,
"t": 1780840929000
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: update
bindings: []
extensions: *ref_0
sendOperations:
- *ref_1
- *ref_2
receiveOperations:
- *ref_3
sendMessages:
- *ref_4
- *ref_5
receiveMessages:
- *ref_6
extensions:
- id: x-parser-unique-object-id
value: onchaintrade
securitySchemes:
- id: cgApiKey
name: x_cg_pro_api_key
type: httpApiKey
description: CoinGecko API key
in: query
extensions: []
````