> ## 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
> Subscribe to receive real-time transaction (trade/swap) updates for pools, as seen on GeckoTerminal.com
This WebSocket channel allows you to subscribe to real-time updates of token trades of a pool.
* Lookup by Network + Pool Address
* It will return transaction type (buy/sell), tx hash, amount of token transacted, volume, and current price data of the specified pool.
**Update Frequency**: as fast as 0.1s, for actively traded pools.
**Tips**: use this REST API endpoint [Top Pools by Token Address](/reference/top-pools-contract-address) to obtain contract address of the most liquid pool.
### Data Payload
| | Field | Type | Description | Example |
| ----- | -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `ch` | `channel_type` | string | Indicates the type of channel subscribed to. | G2 |
| `n` | `network_id` | string | Identifier of the blockchain network. Check full list of IDs [here](https://api.geckoterminal.com/api/v2/networks?page=1). | eth |
| `pa` | `pool_address` | string | Contract address of the pool. | `0x88e6a0c2dd6fcb..3f5640` |
| `tx` | `tx_hash` | string | Transaction hash. | `0x0b8ac5a16c2d5a..4d422` |
| `ty` | `type` | string | Type of transaction (`b` for buy or `s` for sell). | b |
| `to` | `token_amount` | float | Amount of token transacted. | 100 |
| `toq` | `quote_token_amount` | float | Amount of quote token transacted. | 0.0124384489204242 |
| `vo` | `volume_in_usd` | float | The transaction value in USD. | 1000 |
| `pc` | `price_in_native_currency` | float | Current token price in network's native token currency. E.g. Base network's native currency is ETH. | 3639.78228844745 |
| `pu` | `price_in_usd` | float | Current token price in USD. | 3.566 |
| `t` | `last_updated_at` | integer | Timestamp of the last data update in UNIX time. | 1752072129000 |
**Tips**: The WebSocket payload will use the value `null` when specific data is unavailable. Ensure your application is capable of handling null values for fields that may not always have data.
***
## 1. Establish Connection to WebSocket
```bash Bash theme={null}
wss://stream.coingecko.com/v1?x_cg_pro_api_key=YOUR_KEY
OR
wss://stream.coingecko.com/v1
x-cg-pro-api-key: YOUR_KEY
```
## 2. Subscribe to a specific channel - OnchainTrade
**Input Example:**
```json JSON theme={null}
{"command":"subscribe","identifier":"{\"channel\":\"OnchainTrade\"}"}
```
**Output Example**:
```json JSON theme={null}
{"type":"confirm_subscription","identifier":"{\"channel\":\"OnchainTrade\"}"}
```
## 3. Stream OnchainTrade data
**Input Example:**
```json JSON theme={null}
{"command":"message","identifier":"{\"channel\":\"OnchainTrade\"}","data":"{\"network_id:pool_addresses\":[\"bsc:0x172fcd41e0913e95784454622d1c3724f546f849\"],\"action\":\"set_pools\"}"}
```
**Output Example**:
```json JSON theme={null}
{
"code": 2000,
"message": "Subscription successful for bsc:0x172fcd41e0913e95784454622d1c3724f546f849"
}
```
**Output Example**:
```json JSON theme={null}
{
"ch": "G2",
"n": "bsc",
"pa": "0x172fcd41e0913e95784454622d1c3724f546f849",
"tx": "0x3e71ee7da66000a5a92f13abd2ae95e0abc0bc828087d8dd210338fd262cf6c9",
"ty": "b",
"to": 11.0818733869477,
"toq": 0.0124384489204242,
"vo": "2.75413132131313",
"pc": "0.000274100995437363",
"pu": "3656.8970003075",
"t": 1724927796000
}
```
The output keys will be in random order.
## Tips:
### Unsubscribe to stop streaming OnchainTrade data
**Input Example:** Unsubscribe for 1 specific pool data:
```json JSON theme={null}
{"command":"message","identifier":"{\"channel\":\"OnchainTrade\"}","data":"{\"network_id:pool_addresses\":[\"bsc:0x172fcd41e0913e95784454622d1c3724f546f849\"],\"action\":\"unset_pools\"}"}
```
**Output Example**:
```json JSON theme={null}
{
"code":2000,
"message":"Unsubscription is successful for bsc:0x172fcd41e0913e95784454622d1c3724f546f849"
}
```
**Input Example:** Unsubscribe from OnchainTrade channel and all pools data:
```json JSON theme={null}
{"command":"unsubscribe","identifier":"{\"channel\":\"OnchainTrade\"}"}
```
**Output Example**:
```json JSON theme={null}
{
"code":2000,
"message":"Unsubscription is successful for all pools"
}
```
## AsyncAPI
````yaml websocket/asyncapi.json onchaintrade
id: onchaintrade
title: Onchaintrade
description: ''
servers:
- id: production
protocol: wss
host: stream.coingecko.com
bindings: []
variables: []
address: /v1
parameters: []
bindings: []
operations:
- &ref_1
id: subscribeToOnchainTrade
title: 'OnchainTrade: Subscribe'
description: Subscribe to OnchainTrade channel
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: Command to subscribe to a channel
enumValues:
- subscribe
required: true
- name: identifier
type: string
description: JSON string containing channel information
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
command:
type: string
enum:
- subscribe
default: subscribe
example: subscribe
description: Command to subscribe to a channel
x-parser-schema-id:
identifier:
type: string
default: '{"channel":"OnchainTrade"}'
example: '{"channel":"OnchainTrade"}'
description: JSON string containing channel information
x-parser-schema-id:
required:
- command
- identifier
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: Request trade streaming for pools
type: receive
messages:
- &ref_5
id: streamRequest
payload:
- name: Stream OnchainTrade Data
description: Set pools to receive trade updates
type: object
properties:
- name: command
type: string
description: Command to send a message
enumValues:
- message
required: true
- name: identifier
type: string
description: JSON string containing channel information
required: true
- name: data
type: string
description: >-
You may edit this. Format is network_id:pool_address.
Examples: ["bsc:0x172fc..."] or
["eth:0x88e6a...","bsc:0x172fc..."]
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
command:
type: string
enum:
- message
default: message
example: message
description: Command to send a message
x-parser-schema-id:
identifier:
type: string
default: '{"channel":"OnchainTrade"}'
example: '{"channel":"OnchainTrade"}'
description: JSON string containing channel information
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: >-
You may edit this. Format is network_id:pool_address. Examples:
["bsc:0x172fc..."] or ["eth:0x88e6a...","bsc:0x172fc..."]
x-parser-schema-id:
required:
- command
- identifier
- data
x-parser-schema-id:
title: Stream OnchainTrade Data
description: Set pools to receive trade updates
example: |-
{
"command": "",
"identifier": "",
"data": ""
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: streamRequest
bindings: []
extensions: *ref_0
- &ref_3
id: receiveOnchainTradeUpdates
title: 'OnchainTrade: Receive Updates'
description: Receive real-time trade updates
type: send
messages:
- &ref_6
id: tradeUpdate
payload:
- name: OnchainTrade Update
description: Real-time trade update
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: Transaction type (b=buy, s=sell)
required: false
- name: to
type: string
description: Token amount transacted
required: false
- name: toq
type: string
description: Quote token amount transacted
required: false
- name: vo
type: string
description: Transaction volume in USD
required: false
- name: pc
type: string
description: Price in token currency
required: false
- name: pu
type: string
description: Price in USD
required: false
- name: t
type: integer
description: Timestamp (UNIX with 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: >-
0x3e71ee7da66000a5a92f13abd2ae95e0abc0bc828087d8dd210338fd262cf6c9
description: Transaction hash
x-parser-schema-id:
ty:
type: string
example: b
description: Transaction type (b=buy, s=sell)
x-parser-schema-id:
to:
type: string
example: '1.51717616246451'
description: Token amount transacted
x-parser-schema-id:
toq:
type: string
example: '0.0124384489204242'
description: Quote token amount transacted
x-parser-schema-id:
vo:
type: string
example: '2.75413132131313'
description: Transaction volume in USD
x-parser-schema-id:
pc:
type: string
example: '0.000274100995437363'
description: Price in token currency
x-parser-schema-id:
pu:
type: string
example: '3656.8970003075'
description: Price in USD
x-parser-schema-id:
t:
type: integer
example: 1724927796000
description: Timestamp (UNIX with milliseconds)
x-parser-schema-id:
x-parser-schema-id:
title: OnchainTrade Update
description: Real-time trade update
example: |-
{
"c": "",
"n": "",
"pa": "",
"tx": "",
"ty": "",
"to": "",
"toq": "",
"vo": "",
"pc": "",
"pu": "",
"t": 123
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: tradeUpdate
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: Insert CoinGecko Pro API key to establish WebSocket connection
in: query
extensions: []
````