> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Swap Fees
> Subscribe to real-time per-swap fee accounting for pool economics and yield modeling.
## Overview
* **Dataset ID:** [`0303 - Liquidity Pool Swap Fees`](/data-catalog/evm/swaps/liquidity-pools-swap-fees)
* **Description:** Per-swap fee accounting: executed swap sizes plus computed fee amounts using the pool's fee terms (`blockdb_evm.b0212_liquidity_pools_fee_terms_v1`).
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Swap-Fees-Ethereum-And-EVM-Cryptocurrency-Data)
## Subscription Parameters
Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
Filter updates to specific BlockDB pool identifiers.
Filter by input token addresses (hex strings, 20 bytes, no `0x` prefix).
## Message Fields
BlockDB pool identifier.
Exchange/DEX identifier.
Pool type identifier.
Block height where the swap occurred.
Block time (ISO-8601).
Transaction index.
Log index.
Address of the input token.
Address of the output token.
Token address the fee is denominated in.
Executed input amount (raw units, integer string).
Executed output amount (raw units, integer string).
Total fee amount in `fee_token` units.
User/LP share of fees (raw units, nullable).
Protocol share of fees (raw units, nullable).
Extra destination share of fees (raw units, nullable).
Row-level lineage hash for correlation.
Parent lineage ids (hex).
Record creation time (ISO-8601).
Record last update time (ISO-8601).
## Subscription Example
```bash bash theme={null}
# Use wscat to connect and subscribe
wscat -c wss://api.blockdb.io/v1/evm/ \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-x '{"action": "subscribe", "dataset_id": "0303", "chain_id": 1, "params": {"token_in_addresses": ["c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]}}'
```
```c C theme={null}
#include
#include
#include
static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
void *user, void *in, size_t len) {
switch (reason) {
case LWS_CALLBACK_CLIENT_ESTABLISHED:
lws_callback_on_writable(wsi);
break;
case LWS_CALLBACK_CLIENT_RECEIVE:
printf("Received: %s\n", (char *)in);
break;
case LWS_CALLBACK_CLIENT_WRITEABLE: {
unsigned char buf[LWS_PRE + 512];
unsigned char *p = &buf[LWS_PRE];
size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0303\", \"chain_id\": 1, \"params\": {\"token_in_addresses\": [\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"]}}");
lws_write(wsi, p, n, LWS_WRITE_TEXT);
break;
}
}
return 0;
}
```
```csharp .NET theme={null}
using System;
using System.Net.WebSockets;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var ws = new ClientWebSocket();
ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);
var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0303\", \"chain_id\": 1, \"params\": {\"token_in_addresses\": [\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"]}}";
await ws.SendAsync(new ArraySegment(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);
var buffer = new byte[1024 * 4];
while (ws.State == WebSocketState.Open) {
var result = await ws.ReceiveAsync(new ArraySegment(buffer), CancellationToken.None);
Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
}
}
}
```
```python Python theme={null}
import websocket
import json
import os
def on_message(ws, message):
print(f"Received: {message}")
def on_open(ws):
msg = {
"action": "subscribe",
"dataset_id": "0303",
"chain_id": 1,
"params": {
"token_in_addresses": ["c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
}
}
ws.send(json.dumps(msg))
ws = websocket.WebSocketApp(
"wss://api.blockdb.io/v1/evm/",
header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
on_message=on_message,
on_open=on_open
)
ws.run_forever()
```
```javascript Node.js theme={null}
const WebSocket = require('ws');
const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
});
ws.on('open', () => {
ws.send(JSON.stringify({
action: 'subscribe',
dataset_id: '0303',
chain_id: 1,
params: {
token_in_addresses: ["c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
}
}));
});
ws.on('message', (data) => {
console.log('Received:', JSON.parse(data));
});
```
```go Go theme={null}
package main
import (
"fmt"
"log"
"net/http"
"os"
"github.com/gorilla/websocket"
)
func main() {
header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
if err != nil {
log.Fatal("dial:", err)
}
defer c.Close()
sub := `{"action": "subscribe", "dataset_id": "0303", "chain_id": 1, "params": {"token_in_addresses": ["c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]}}`
err = c.WriteMessage(websocket.TextMessage, []byte(sub))
if err != nil {
log.Fatal("write:", err)
}
for {
_, message, err := c.ReadMessage()
if err != nil {
log.Fatal("read:", err)
}
fmt.Printf("Received: %s\n", message)
}
}
```
## Response Example
```json Response theme={null}
{
"chain_id": 1,
"dataset_id": "0303",
"is_reorg": false,
"data": {
"pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
"exchange_id": 1,
"type_id": 201,
"block_number": 19000042,
"block_time": "2025-12-20T12:34:56Z",
"tx_index": 15,
"log_index": 88,
"token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"fee_token": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"amount_in": "5.000000000000000000",
"amount_out": "15850.000000000000000000",
"fee_amount_total": "0.015000000000000000",
"fee_amount_user": "0.012000000000000000",
"fee_amount_protocol": "0.003000000000000000",
"fee_amount_extra": "0.000000000000000000",
"_tracing_id": "0303c0ffee000000000000000000000000000000000000000000000000000001",
"_parent_tracing_ids": [
"0103c0ffee000000000000000000000000000000000000000000000000000001",
"0204c0ffee000000000000000000000000000000000000000000000000000001"
],
"_created_at": "2025-12-20T12:35:01Z",
"_updated_at": "2025-12-20T12:35:01Z"
}
}
```
## AsyncAPI
````yaml specs/wss/evm/swaps/swap-fees.yaml swap-fees
id: swap-fees
title: Swap-fees
description: ''
servers:
- id: production
protocol: wss
host: api.blockdb.io/v1/evm/
bindings: []
variables: []
address: /
parameters: []
bindings: []
operations:
- &ref_2
id: onSubscribe
title: On subscribe
type: receive
messages:
- &ref_5
id: subscribe
payload:
- name: subscribe
type: object
properties:
- name: action
type: string
description: subscribe
required: true
- name: chain_id
type: integer
required: true
- name: dataset_id
type: string
description: '0303'
required: true
- name: params
type: object
required: true
properties:
- name: pool_uids
type: array
required: false
properties:
- name: item
type: string
required: false
- name: token_in_addresses
type: array
required: false
properties:
- name: item
type: string
required: false
headers: []
jsonPayloadSchema:
type: object
properties:
action:
type: string
const: subscribe
x-parser-schema-id:
chain_id:
type: integer
x-parser-schema-id:
dataset_id:
type: string
const: '0303'
x-parser-schema-id:
params:
type: object
properties:
pool_uids:
type: array
items:
type: string
x-parser-schema-id:
x-parser-schema-id:
token_in_addresses:
type: array
items:
type: string
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id:
required:
- action
- chain_id
- dataset_id
- params
x-parser-schema-id:
title: Subscribe
example: No examples found
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribe
- id: x-parser-message-name
value: subscribe
bindings: []
extensions: &ref_0
- id: x-parser-unique-object-id
value: swap-fees
- &ref_3
id: onUnsubscribe
title: On unsubscribe
type: receive
messages:
- &ref_6
id: unsubscribe
payload:
- name: unsubscribe
type: object
properties:
- name: action
type: string
description: unsubscribe
required: true
- name: chain_id
type: integer
required: true
- name: dataset_id
type: string
description: '0303'
required: true
headers: []
jsonPayloadSchema:
type: object
properties:
action:
type: string
const: unsubscribe
x-parser-schema-id:
chain_id:
type: integer
x-parser-schema-id:
dataset_id:
type: string
const: '0303'
x-parser-schema-id:
required:
- action
- chain_id
- dataset_id
x-parser-schema-id:
title: Unsubscribe
example: |-
{
"action": "",
"chain_id": 123,
"dataset_id": ""
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: unsubscribe
- id: x-parser-message-name
value: unsubscribe
bindings: []
extensions: *ref_0
- &ref_4
id: emitUpdates
title: Emit updates
type: send
messages:
- &ref_7
id: subscribe_response
payload:
- name: subscribe_response
type: object
properties:
- name: action
type: string
description: subscribe
required: true
- name: chain_id
type: integer
required: true
- name: dataset_id
type: string
description: '0303'
required: true
- name: status
type: string
enumValues:
- success
- error
required: true
- name: error
type: object
required: false
properties:
- name: code
type: string
description: Machine-readable error code.
required: true
- name: message
type: string
description: Human-readable summary of the error.
required: true
- name: hint
type: string
description: Diagnostic hint to help resolve the issue.
required: false
- name: severity
type: string
enumValues:
- info
- warning
- error
- critical
required: true
- name: retryable
type: boolean
description: Whether the client should attempt to retry the operation.
required: true
- name: details
type: object
description: Additional structured metadata about the error.
required: false
- name: docs_url
type: string
description: Link to relevant documentation for the error.
required: false
headers: []
jsonPayloadSchema:
type: object
properties:
action:
type: string
const: subscribe
x-parser-schema-id:
chain_id:
type: integer
x-parser-schema-id:
dataset_id:
type: string
const: '0303'
x-parser-schema-id:
status:
type: string
enum:
- success
- error
x-parser-schema-id:
error: &ref_1
type: object
properties:
code:
type: string
description: Machine-readable error code.
x-parser-schema-id:
message:
type: string
description: Human-readable summary of the error.
x-parser-schema-id:
hint:
type: string
description: Diagnostic hint to help resolve the issue.
x-parser-schema-id:
severity:
type: string
enum:
- info
- warning
- error
- critical
x-parser-schema-id:
retryable:
type: boolean
description: Whether the client should attempt to retry the operation.
x-parser-schema-id:
details:
type: object
description: Additional structured metadata about the error.
x-parser-schema-id:
docs_url:
type: string
format: uri
description: Link to relevant documentation for the error.
x-parser-schema-id:
required:
- code
- message
- severity
- retryable
x-parser-schema-id: ErrorObject
required:
- action
- chain_id
- dataset_id
- status
x-parser-schema-id:
title: Subscribe_response
example: No examples found
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribe_response
- id: x-parser-message-name
value: subscribe_response
- &ref_8
id: unsubscribe_response
payload:
- name: unsubscribe_response
type: object
properties:
- name: action
type: string
description: unsubscribe
required: true
- name: chain_id
type: integer
required: true
- name: dataset_id
type: string
description: '0303'
required: true
- name: status
type: string
enumValues:
- success
- error
required: true
- name: error
type: object
required: false
properties:
- name: code
type: string
description: Machine-readable error code.
required: true
- name: message
type: string
description: Human-readable summary of the error.
required: true
- name: hint
type: string
description: Diagnostic hint to help resolve the issue.
required: false
- name: severity
type: string
enumValues:
- info
- warning
- error
- critical
required: true
- name: retryable
type: boolean
description: Whether the client should attempt to retry the operation.
required: true
- name: details
type: object
description: Additional structured metadata about the error.
required: false
- name: docs_url
type: string
description: Link to relevant documentation for the error.
required: false
headers: []
jsonPayloadSchema:
type: object
properties:
action:
type: string
const: unsubscribe
x-parser-schema-id:
chain_id:
type: integer
x-parser-schema-id:
dataset_id:
type: string
const: '0303'
x-parser-schema-id:
status:
type: string
enum:
- success
- error
x-parser-schema-id:
error: *ref_1
required:
- action
- chain_id
- dataset_id
- status
x-parser-schema-id:
title: Unsubscribe_response
example: No examples found
bindings: []
extensions:
- id: x-parser-unique-object-id
value: unsubscribe_response
- id: x-parser-message-name
value: unsubscribe_response
- &ref_9
id: update
payload:
- name: update
type: object
properties:
- name: chain_id
type: integer
required: true
- name: dataset_id
type: string
description: '0303'
required: true
- name: is_reorg
type: boolean
required: true
- name: data
type: object
required: true
properties:
- name: pool_uid
type: string
required: false
- name: token_in
type: string
required: false
- name: token_out
type: string
required: false
- name: amount_in
type: string
required: false
- name: amount_out
type: string
required: false
- name: fee_amount_total
type: string
required: false
- name: block_number
type: integer
required: false
- name: _tracing_id
type: string
required: false
headers: []
jsonPayloadSchema:
type: object
properties:
chain_id:
type: integer
x-parser-schema-id:
dataset_id:
type: string
const: '0303'
x-parser-schema-id:
is_reorg:
type: boolean
x-parser-schema-id:
data:
type: object
properties:
pool_uid:
type: string
x-parser-schema-id:
token_in:
type: string
x-parser-schema-id:
token_out:
type: string
x-parser-schema-id:
amount_in:
type: string
x-parser-schema-id:
amount_out:
type: string
x-parser-schema-id:
fee_amount_total:
type: string
x-parser-schema-id:
block_number:
type: integer
x-parser-schema-id:
_tracing_id:
type: string
x-parser-schema-id:
x-parser-schema-id:
required:
- chain_id
- dataset_id
- is_reorg
- data
x-parser-schema-id:
title: Update
example: |-
{
"chain_id": 123,
"dataset_id": "",
"is_reorg": true,
"data": {
"pool_uid": "",
"token_in": "",
"token_out": "",
"amount_in": "",
"amount_out": "",
"fee_amount_total": "",
"block_number": 123,
"_tracing_id": ""
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: update
- id: x-parser-message-name
value: update
bindings: []
extensions: *ref_0
sendOperations:
- *ref_2
- *ref_3
receiveOperations:
- *ref_4
sendMessages:
- *ref_5
- *ref_6
receiveMessages:
- *ref_7
- *ref_8
- *ref_9
extensions:
- id: x-parser-unique-object-id
value: swap-fees
securitySchemes: []
````