> ## 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.

# Swaps Overview

> Access per-swap fee accounting for pool economics, revenue attribution, and yield modeling.

## Overview

The Swaps endpoint provides per-swap fee accounting for AMM pools. Each swap record includes executed token amounts, computed fee amounts, and fee splits across recipients (LPs/users, protocol, extra destinations). This data enables revenue attribution, pool economics analysis, and feeds into yield prediction models.

### Endpoint Matrix

| Endpoint                                                     | Summary                                                | Dataset ID | Typical Latency |
| ------------------------------------------------------------ | ------------------------------------------------------ | ---------- | --------------- |
| [`POST /evm/swaps/fees`](/api-reference/evm/swaps/swap-fees) | Per-swap fee accounting (executed sizes + fee amounts) | `0303`     | \< 250 ms       |

### Parameter Conventions

<ParamField body="from_block" type="number">
  Starting block height (inclusive) for swap fee records.
</ParamField>

<ParamField body="to_block" type="number">
  Ending block height (inclusive) for swap fee records.
</ParamField>

<ParamField body="from_timestamp" type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField body="to_timestamp" type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<ParamField body="pool_uids" type="string[]">
  BlockDB pool identifiers for filtering swap fees by pool.
</ParamField>

<ParamField body="pool_addresses" type="string[]">
  Pool contract addresses to scope swap fee data.
</ParamField>

<ParamField body="token_in_addresses" type="string[]">
  Filter by input token addresses.
</ParamField>

<ParamField body="token_out_addresses" type="string[]">
  Filter by output token addresses.
</ParamField>

<ParamField body="fee_token_addresses" type="string[]">
  Filter by fee token addresses.
</ParamField>

<ParamField body="chain_id" type="number" required>
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

### Usage Guidance

* **Join with fee terms** — Link swap fees to pool fee configuration via `pool_uid` to understand fee splits
* **Time-series analysis** — Swap fees are ordered by block/time; use ranges for historical revenue analysis
* **Filter by tokens** — Use `token_in_addresses` and `token_out_addresses` to analyze specific trading pairs
* **Revenue attribution** — Fee split fields (`fee_amount_user`, `fee_amount_protocol`, `fee_amount_extra`) enable precise revenue attribution
* **Feed yield models** — Swap fee data is the primary input for yield/ROI predictions (see `/evm/yields`)

### Fee Calculation

Swap fees are computed using the pool's fee terms (from `/evm/entities/pools/fee-terms`):

* `fee_amount_total ≈ amount_in * total_fee`
* `fee_amount_user ≈ amount_in * user_fee` (when available)
* `fee_amount_protocol ≈ amount_in * protocol_fee` (when available)
* `fee_amount_extra ≈ amount_in * extra_fee` (when available)

Fee amounts are denominated in the `fee_token`, which may differ from `token_in` or `token_out` depending on the pool type.

### Common Patterns

**Calculate pool revenue over time:**

```json theme={null}
{
  "chain_id": 1,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_timestamp": "2025-01-01T00:00:00Z",
  "to_timestamp": "2025-01-31T23:59:59Z"
}
```

**Analyze fees for a specific trading pair:**

```json theme={null}
{
  "chain_id": 1,
  "token_in_addresses": [
    "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
  ],
  "token_out_addresses": [
    "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  ],
  "from_block": 19000000
}
```

**Track protocol revenue:**

```json theme={null}
{
  "chain_id": 1,
  "pool_addresses": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f564"
  ],
  "from_timestamp": "2025-12-01T00:00:00Z",
  "to_timestamp": "2025-12-31T23:59:59Z"
}
```

### Dataset Relationships

* **Pools → Swap Fees**: Join pool metadata to swap fees using `pool_uid`
* **Fee Terms → Swap Fees**: Fee terms define the fee calculation rules applied to each swap
* **Swap Fees → Yields**: Yield predictions are derived from historical swap fees and current reserves
* **Swap Fees → Reserves**: Swap fees indicate liquidity changes that affect reserve snapshots
* **Swap Fees → Prices**: Swap execution prices are captured in the pricing layers

### See Also

* [`POST /evm/swaps/fees`](/api-reference/evm/swaps/swap-fees) — Per-swap fee accounting endpoint
* [`POST /evm/entities/pools/fee-terms`](/api-reference/evm/entities/fee-terms) — Pool fee configuration
* [`POST /evm/yields`](/api-reference/evm/yields/yields) — Yield/ROI predictions derived from swap fees
* [`POST /evm/reserves`](/api-reference/evm/reserves/reserves) — Pool reserve snapshots
* [`POST /evm/entities/pools`](/api-reference/evm/entities/pools) — Pool metadata registry
* [Pool Type](/api-reference/enumerations/pool-type) — AMM pool classifications