> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metastreams.dev/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.

<ResponseField name="id" type="string" required>
  A stable, opaque ID for the trade. One transaction can hold several trades, so this is not the transaction hash. Never parse it.
</ResponseField>

<ResponseField name="chain" type="string" required>
  The [chain slug](/concepts/chains) the trade executed on.
</ResponseField>

<ResponseField name="token" type="string" required>
  The traded token's address.
</ResponseField>

<ResponseField name="name" type="string" required>
  The token's name. Empty until the token's metadata resolves.
</ResponseField>

<ResponseField name="symbol" type="string" required>
  The token's symbol. Empty until the token's metadata resolves.
</ResponseField>

<ResponseField name="trader" type="string" required>
  The wallet that sent the swap.
</ResponseField>

<ResponseField name="transactionHash" type="string" required>
  The on-chain transaction hash.
</ResponseField>

<ResponseField name="side" type="string" required>
  `buy` or `sell`.
</ResponseField>

<ResponseField name="amount" type="decimal string" required>
  Token units traded.
</ResponseField>

<ResponseField name="price" type="money object" required>
  The token's price at execution.
</ResponseField>

<ResponseField name="volume" type="money object" required>
  The trade's value.
</ResponseField>

<ResponseField name="marketCap" type="money object" required>
  The token's market cap at execution.
</ResponseField>

<ResponseField name="flags" type="string[]">
  The trader's [wallet classifications](/resources/glossary#wallet-classifications), such as `sniper` or `bundler`. Left out when empty. New values can appear; keep ones you do not recognize.
</ResponseField>

<ResponseField name="platforms" type="object[]">
  The trading terminals the trade routed through. Left out when empty.

  <Expandable title="platform">
    <ResponseField name="platform" type="string" required>
      The terminal, such as `axiom`, `bananaGun`, `bullX`, `gmgn`, `maestro`, `photon`, `trojan` or `fomo`. New values can appear.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="identities" type="object[]">
  The trader's resolved public profiles, one per source. Left out when empty. Every field of a profile is present, and any field except `source` can be `null`.

  <Expandable title="identity">
    <ResponseField name="source" type="string" required>
      Who resolved the profile, such as `codex` or `fomoscan`. New values can appear.
    </ResponseField>

    <ResponseField name="handle" type="string | null" required>
      The wallet's handle on the source.
    </ResponseField>

    <ResponseField name="displayName" type="string | null" required>
      A name to display.
    </ResponseField>

    <ResponseField name="avatar" type="string | null" required>
      An avatar image URL. `null` until the image is available.
    </ResponseField>

    <ResponseField name="twitter" type="string | null" required>
      The linked X handle.
    </ResponseField>

    <ResponseField name="telegram" type="string | null" required>
      The linked Telegram handle.
    </ResponseField>

    <ResponseField name="farcaster" type="string | null" required>
      The linked Farcaster handle.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="integer" required>
  When the trade executed, in milliseconds.
</ResponseField>

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