> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/gotts-safe-mcp-server/mcp-server/06-tools-realtime.md).

# Streaming and Fee Tools

> **Package**: `packages/safe/` | **Prerequisites**: [02-architecture.md](/docs/gotts-safe-mcp-server/mcp-server/02-architecture.md)
>
> Real-time streaming tools and protocol fee tools (Phase 4). For other tool categories, see the [README](/docs/gotts-safe-mcp-server/mcp-server.md).

***

## Streaming / Real-Time Data Tools

These tools leverage MCP's Streamable HTTP transport to provide real-time data streams via Server-Sent Events (SSE). Agents subscribe to streams and receive events as they occur on-chain, enabling reactive strategies (market making, position monitoring, arbitrage detection).

#### `subscribe_price_feed`

Subscribe to real-time price updates for a token or token pair. Emits events when the price changes beyond a configurable threshold.

**Parameters**:

| Name            | Type     | Required | Description                                                          |
| --------------- | -------- | -------- | -------------------------------------------------------------------- |
| `token`         | `string` | Yes      | Token symbol or address                                              |
| `chain`         | `string` | Yes      | Chain name or chain ID                                               |
| `quoteCurrency` | `string` | No       | Quote currency. Default: "USD".                                      |
| `threshold`     | `number` | No       | Minimum price change (%) to trigger an event. Default: 0.1.          |
| `pool`          | `string` | No       | Specific pool address to monitor. If omitted, uses highest-TVL pool. |

**Stream Events**:

```json
{
  "type": "price_update",
  "token": "WETH",
  "chain": "ethereum",
  "price": 3247.82,
  "previousPrice": 3245.67,
  "changePercent": 0.066,
  "pool": "0x88e6...",
  "blockNumber": 19234568,
  "timestamp": "2026-02-06T12:00:15Z"
}
```

**Implementation**: WebSocket subscription to RPC node for new block headers → read pool slot0 on each block → emit event if price change exceeds threshold. For high-frequency feeds, use `eth_subscribe("newPendingTransactions")` filtered to target pool.

***

#### `subscribe_trades`

Subscribe to real-time swap events on a specific pool or for a specific token.

**Parameters**:

| Name           | Type     | Required | Description                                              |
| -------------- | -------- | -------- | -------------------------------------------------------- |
| `pool`         | `string` | No       | Pool address to monitor                                  |
| `token`        | `string` | No       | Token symbol/address (monitors all pools for this token) |
| `chain`        | `string` | Yes      | Chain name or chain ID                                   |
| `minAmountUsd` | `number` | No       | Minimum trade size filter. Default: 0 (all trades).      |

**Stream Events**:

```json
{
  "type": "swap",
  "pool": "0x88e6...",
  "txHash": "0xABCD...",
  "blockNumber": 19234568,
  "timestamp": "2026-02-06T12:00:15Z",
  "sender": "0x1234...",
  "tokenIn": { "symbol": "USDC", "amount": "50000.00" },
  "tokenOut": { "symbol": "WETH", "amount": "15.38" },
  "priceImpact": 0.05,
  "amountUsd": 50000.0,
  "newPrice": 3249.1
}
```

**Implementation**: `eth_subscribe("logs")` with filter for `Swap` event signature on target pool contract(s).

***

#### `subscribe_lp_events`

Subscribe to real-time liquidity provision events (mint, burn, collect) on a pool or for a specific position.

**Parameters**:

| Name         | Type       | Required | Description                                         |
| ------------ | ---------- | -------- | --------------------------------------------------- |
| `pool`       | `string`   | No       | Pool address to monitor                             |
| `positionId` | `string`   | No       | Specific position ID to monitor                     |
| `chain`      | `string`   | Yes      | Chain name or chain ID                              |
| `eventTypes` | `string[]` | No       | Filter: \["mint", "burn", "collect"]. Default: all. |

**Stream Events**:

```json
{
  "type": "lp_event",
  "eventType": "mint",
  "pool": "0x88e6...",
  "txHash": "0xABCD...",
  "blockNumber": 19234568,
  "timestamp": "2026-02-06T12:00:15Z",
  "owner": "0x5678...",
  "tickLower": 200000,
  "tickUpper": 210000,
  "amount0": "50000.00",
  "amount1": "15.38",
  "liquidityDelta": "1234567890"
}
```

**Implementation**: `eth_subscribe("logs")` with filter for `Mint`, `Burn`, `IncreaseLiquidity`, `DecreaseLiquidity`, `Collect` event signatures.

***

#### `subscribe_pool_state`

Subscribe to comprehensive pool state changes. Emits a consolidated update on every block that modifies the pool (swaps, LP changes, fee collection). Useful for agents that need to track full pool dynamics.

**Parameters**:

| Name                 | Type      | Required | Description                                                            |
| -------------------- | --------- | -------- | ---------------------------------------------------------------------- |
| `pool`               | `string`  | Yes      | Pool address                                                           |
| `chain`              | `string`  | Yes      | Chain name or chain ID                                                 |
| `includeTickChanges` | `boolean` | No       | Include tick-level liquidity changes. Default: false (more expensive). |

**Stream Events**:

```json
{
  "type": "pool_state_update",
  "pool": "0x88e6...",
  "blockNumber": 19234568,
  "timestamp": "2026-02-06T12:00:15Z",
  "currentTick": 201235,
  "sqrtPriceX96": "1234567890123456789012345679",
  "price": 3249.1,
  "liquidity": "12345678901234567891",
  "tvlUsd": 245050000,
  "events": [
    { "type": "swap", "volumeUsd": 50000 },
    { "type": "mint", "liquidityDelta": "1234567890" }
  ]
}
```

**Implementation**: Combination of block header subscription + batch RPC reads for pool state on each block where the pool was active.

***

## Protocol Fee Tools (TokenJar / Firepit)

Tools for querying and interacting with Uniswap's protocol fee system -- the TokenJar (fee accumulation vault) and Firepit (UNI burn-to-release mechanism). Critical for searcher agents that monitor accumulated fees and execute profitable burn-and-claim transactions.

**Contract Addresses**: See [shared/chains.md](/docs/prd-shared/chains.md) for canonical contract addresses (TokenJar, Firepit, UNI Token).

#### `get_tokenjar_balances`

Get all assets currently accumulated in the TokenJar vault, including ETH, ERC-20 tokens, and LP tokens with USD valuations and fee source attribution.

**Parameters**:

| Name          | Type      | Required | Description                                  |
| ------------- | --------- | -------- | -------------------------------------------- |
| `chain`       | `string`  | No       | Chain name or chain ID. Default: "ethereum". |
| `includeLP`   | `boolean` | No       | Include LP tokens (V2 pairs). Default: true. |
| `minValueUsd` | `number`  | No       | Minimum USD value filter. Default: 0.        |

**Returns**:

```json
{
  "tokenJarAddress": "0xf38521f130fcCF29dB1961597bc5d2B60F995f85",
  "chain": "ethereum",
  "totalValueUsd": 2450000,
  "assetCount": 15,
  "assets": [
    {
      "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "symbol": "WETH",
      "name": "Wrapped Ether",
      "decimals": 18,
      "balance": "425000000000000000000",
      "balanceFormatted": "425.00",
      "usdValue": 1381250,
      "percentOfTotal": 56.4,
      "feeSource": "v3-fees",
      "tokenType": "erc20",
      "logoUri": "https://..."
    },
    {
      "address": "0x0000000000000000000000000000000000000000",
      "symbol": "ETH",
      "name": "Ether",
      "balance": "50000000000000000000",
      "balanceFormatted": "50.00",
      "usdValue": 162500,
      "percentOfTotal": 6.6,
      "feeSource": "native",
      "tokenType": "native"
    }
  ],
  "feeSourceBreakdown": [
    { "source": "v3-fees", "valueUsd": 1800000, "percent": 73.5 },
    { "source": "v4-fees", "valueUsd": 350000, "percent": 14.3 },
    { "source": "uniswapx", "valueUsd": 150000, "percent": 6.1 },
    { "source": "native", "valueUsd": 150000, "percent": 6.1 }
  ],
  "releaserAddress": "0x0D5Cd355e2aBEB8fb1552F56c965B867346d6721",
  "lastUpdated": "2026-02-06T12:00:00Z"
}
```

***

#### `get_firepit_state`

Get the current state of the Firepit contract: burn threshold, current nonce, total UNI burned, and profitability analysis for a potential burn-and-claim.

**Parameters**:

| Name            | Type     | Required | Description                                                                                |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------------------ |
| `chain`         | `string` | No       | Chain name or chain ID. Default: "ethereum".                                               |
| `walletAddress` | `string` | No       | Wallet address to check UNI balance and allowance. If omitted, returns general state only. |

**Returns**:

```json
{
  "firepitAddress": "0x0D5Cd355e2aBEB8fb1552F56c965B867346d6721",
  "chain": "ethereum",
  "threshold": "4000000000000000000000",
  "thresholdFormatted": "4000 UNI",
  "thresholdUsd": 40000,
  "currentNonce": 42,
  "resourceToken": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
  "resourceRecipient": "0x000000000000000000000000000000000000dEaD",
  "maxReleaseLength": 20,
  "tokenJarTotalValueUsd": 2450000,
  "profitability": {
    "isProfitable": true,
    "netProfitUsd": 2410000,
    "costUsd": 40000,
    "returnMultiple": 61.25,
    "topAssets": [
      { "symbol": "WETH", "usdValue": 1381250 },
      { "symbol": "USDC", "usdValue": 650000 }
    ]
  },
  "wallet": {
    "address": "0x1234...",
    "uniBalance": "5000000000000000000000",
    "uniBalanceFormatted": "5000 UNI",
    "uniAllowance": "0",
    "hasEnoughUni": true,
    "needsApproval": true
  }
}
```

***

#### `get_burn_history`

Get historical Firepit burn events with details about who burned, what assets were released, and the value exchanged.

**Parameters**:

| Name        | Type     | Required | Description                                  |
| ----------- | -------- | -------- | -------------------------------------------- |
| `chain`     | `string` | No       | Chain name or chain ID. Default: "ethereum". |
| `limit`     | `number` | No       | Max events. Default: 20. Max: 100.           |
| `startTime` | `string` | No       | ISO 8601 start time filter                   |

**Returns**:

```json
{
  "chain": "ethereum",
  "totalBurnEvents": 42,
  "totalUniBurned": "168000000000000000000000",
  "totalUniBurnedFormatted": "168,000 UNI",
  "totalValueReleased": 15400000,
  "events": [
    {
      "nonce": 41,
      "txHash": "0xABCD...",
      "blockNumber": 19234567,
      "timestamp": "2026-02-05T14:30:00Z",
      "burner": "0x1234...",
      "recipient": "0x1234...",
      "uniBurned": "4000 UNI",
      "assetsReleased": [
        { "symbol": "WETH", "amount": "200.5", "usdValue": 651625 },
        { "symbol": "USDC", "amount": "300000", "usdValue": 300000 }
      ],
      "totalValueUsd": 951625,
      "costUsd": 40000,
      "profitUsd": 911625
    }
  ]
}
```

**Data Source**: RPC event log scan for `Released` events on the Firepit contract, enriched with token prices at time of event (from subgraph or historical price data).

***

#### `execute_burn`

Execute the full burn-and-claim workflow: approve UNI spending (if needed), select optimal assets from TokenJar, and execute the Firepit release. This is the primary tool for searcher agents.

**Parameters**:

| Name          | Type       | Required | Description                                                                                                         |
| ------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `chain`       | `string`   | No       | Chain name or chain ID. Default: "ethereum".                                                                        |
| `assets`      | `string[]` | No       | Specific asset addresses to claim. If omitted, auto-selects top assets by value (up to MAX\_RELEASE\_LENGTH of 20). |
| `recipient`   | `string`   | No       | Address to receive released assets. Default: connected wallet.                                                      |
| `autoApprove` | `boolean`  | No       | Automatically approve UNI if allowance is insufficient. Default: true.                                              |
| `simulate`    | `boolean`  | No       | Simulate only, don't execute. Default: false.                                                                       |

**Returns**:

```json
{
  "success": true,
  "nonce": 42,
  "txHash": "0xDEAD...",
  "blockNumber": 19234568,
  "uniBurned": "4000 UNI",
  "costUsd": 40000,
  "assetsReceived": [
    { "symbol": "WETH", "amount": "425.00", "usdValue": 1381250 },
    { "symbol": "USDC", "amount": "650000", "usdValue": 650000 }
  ],
  "totalValueReceivedUsd": 2031250,
  "profitUsd": 1991250,
  "approvalTxHash": "0xAAAA..."
}
```

**Safety**: This tool goes through the full safety pipeline (simulation, spending limits, token validation). The `simulate` flag allows agents to preview the outcome before committing.

***

#### `get_fee_accumulation_rate`

Get the rate at which fees are accumulating in the TokenJar, helping agents estimate when the next burn will be profitable.

**Parameters**:

| Name    | Type     | Required | Description                                                |
| ------- | -------- | -------- | ---------------------------------------------------------- |
| `chain` | `string` | No       | Chain name or chain ID. Default: "ethereum".               |
| `days`  | `number` | No       | Lookback period for rate calculation. Default: 7. Max: 90. |

**Returns**:

```json
{
  "chain": "ethereum",
  "lookbackDays": 7,
  "currentTotalValueUsd": 2450000,
  "accumulationRate": {
    "perDay": 350000,
    "perWeek": 2450000,
    "perMonth": 10500000
  },
  "byFeeSource": [
    { "source": "v3-fees", "perDayUsd": 257000 },
    { "source": "v4-fees", "perDayUsd": 50000 },
    { "source": "uniswapx", "perDayUsd": 21500 },
    { "source": "native", "perDayUsd": 21500 }
  ],
  "burnThresholdUsd": 40000,
  "estimatedTimeToNextProfitableBurn": "already profitable",
  "historicalBurns": {
    "avgTimeBetweenBurns": "4.2 days",
    "avgProfitPerBurn": 411000
  }
}
```

**Data Source**: Subgraph transfer events to TokenJar address aggregated over time, combined with current balances and burn threshold.

***

#### `subscribe_tokenjar`

Subscribe to real-time TokenJar balance changes. Emits events when fees are deposited into the vault. Essential for searcher agents that need to know when a burn becomes profitable.

**Parameters**:

| Name            | Type     | Required | Description                                          |
| --------------- | -------- | -------- | ---------------------------------------------------- |
| `chain`         | `string` | No       | Chain name or chain ID. Default: "ethereum".         |
| `minDepositUsd` | `number` | No       | Minimum deposit size to trigger event. Default: 100. |

**Stream Events**:

```json
{
  "type": "tokenjar_deposit",
  "token": { "symbol": "WETH", "address": "0xC02a...", "amount": "10.5" },
  "usdValue": 34125,
  "feeSource": "v3-fees",
  "txHash": "0xABCD...",
  "blockNumber": 19234568,
  "timestamp": "2026-02-06T12:05:00Z",
  "newTotalValueUsd": 2484125,
  "profitability": {
    "isProfitable": true,
    "netProfitUsd": 2444125
  }
}
```

**Implementation**: `eth_subscribe("logs")` for `Transfer` events to the TokenJar address, plus `receive()` for native ETH deposits.

***