> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metastreams.io/llms.txt
> Use this file to discover all available pages before exploring further.

# spot.trades

> Every trade on a token, by a wallet, or by a notable identity, as it happens.

Subscribe on an open stream connection. See [Connecting to streams](/streams/overview) for the connection, frames and reconnecting.

## Filters

Send exactly one mode: `token`, `wallet` or `identity`.

<ParamField body="chain" type="string">
  The [chain slug](/concepts/chains). Required with `token` or `wallet`. Ignored with `identity`, which covers every chain, though an unsupported slug is still refused.
</ParamField>

<ParamField body="token" type="string">
  Stream every trade on this token.
</ParamField>

<ParamField body="wallet" type="string">
  Stream every trade by this wallet.
</ParamField>

<ParamField body="identity" type="string">
  Stream trades by notable wallets on every chain. `kol` covers wallets labelled as key opinion leaders. `fomoscan` covers wallets with a fomo.family profile.
</ParamField>

<ParamField body="flags" type="string[]">
  Keep only trades whose trader carries at least one of these [wallet classifications](/resources/glossary#wallet-classifications), such as `sniper` or `bundler`. `fomo` matches trades routed through the fomo.family terminal, and trades with no known terminal by wallets flagged `fomo`. Leave it out to keep every trade.
</ParamField>

## Update

Each update's `data` is one trade, in the same shape the REST trade endpoints return, with fields left out by mode:

| Mode | Left out |
| - | - |
| `token` | `flags`, `platforms` |
| `wallet` | `platforms` |
| `identity` | `platforms` |

The `flags` filter still applies in `token` mode, even though updates leave the field out.

[Token trades](/reference/rest/token-trades) documents every field of a trade.

## Errors

| Code | When |
| - | - |
| `VALIDATION_ERROR` | No mode or more than one mode; `chain` missing with `token` or `wallet`; an address in the wrong format for the chain; an unknown `identity` or `flags` value; an unknown filter field |
| `UNSUPPORTED_CHAIN` | `chain` is not a supported slug |

<RequestExample>
  ```json Token theme={null}
  {
    "action": "subscribe",
    "channel": "spot.trades",
    "filters": { "chain": "solana", "token": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" },
    "id": "bonk-trades"
  }
  ```

  ```json Wallet theme={null}
  {
    "action": "subscribe",
    "channel": "spot.trades",
    "filters": { "chain": "base", "wallet": "0x4c2f1b6a8e0d7c9b3a5f2e1d0c9b8a7f6e5d4c3b" }
  }
  ```

  ```json Identity theme={null}
  {
    "action": "subscribe",
    "channel": "spot.trades",
    "filters": { "identity": "kol", "flags": ["whale"] }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Update theme={null}
  {
    "type": "update",
    "channel": "spot.trades",
    "subscriptionId": "5f0c6d1e-8a2b-4c3d-9e4f-1a2b3c4d5e6f",
    "data": {
      "id": "4xQmVb8e2kT1nR7pZcW3sLdHfA9jEuY6gVnX1oB5iC0wQ2rT8yU3iO7pA1sD4fG6h:2",
      "chain": "solana",
      "token": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
      "name": "Bonk",
      "symbol": "Bonk",
      "trader": "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5",
      "transactionHash": "4xQmVb8e2kT1nR7pZcW3sLdHfA9jEuY6gVnX1oB5iC0wQ2rT8yU3iO7pA1sD4fG6h",
      "side": "buy",
      "amount": "12500000",
      "price": { "native": "0.000000121", "usd": "0.0000216" },
      "volume": { "native": "1.51", "usd": "270.12" },
      "marketCap": { "native": "10741962.1", "usd": "1917440000" },
      "timestamp": 1789632015120
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.