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

# Identity trades

> Page through trades by notable wallets across every chain and token.

```http theme={null}
GET /v1/trades
```

Recent trades by one identity feed, newest first, across every token. This is the only trade read not scoped to a token.

## Query parameters

<ParamField query="identity" type="string" required>
  Which feed to read. `kol` covers wallets labelled as key opinion leaders. `fomoscan` covers wallets with a fomo.family profile.
</ParamField>

<ParamField query="chains" type="string">
  Comma-separated [chain slugs](/concepts/chains) to scope to, such as `solana,base`. Absent means every spot chain. A list that names nothing is refused.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Rows per page. A value outside 1–100 is clamped, not refused.
</ParamField>

<ParamField query="cursor" type="string">
  The opaque `nextCursor` from the previous page.
</ParamField>

## Response

The page shape of [Token trades](/reference/rest/token-trades#response): `trades`, `nextCursor` and `hasMore`. Each trade names its own `chain` and `token`, because one page spans both.

### Trade object

<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 |
| - | - |
| `UNSUPPORTED_CHAIN` | A slug in `chains` is not supported |
| `VALIDATION_ERROR` | An unknown `identity`, an empty `chains` list, a cursor that does not decode, or an unknown parameter |

<RequestExample>
  ```bash cURL theme={null}
  curl "https://{{API_HOST}}/v1/trades?identity=kol&limit=50" \
    -H "Authorization: Bearer $API_KEY"
  ```

  ```bash Scoped theme={null}
  curl "https://{{API_HOST}}/v1/trades?identity=fomoscan&chains=solana,base" \
    -H "Authorization: Bearer $API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const url = new URL("https://{{API_HOST}}/v1/trades");
  url.searchParams.set("identity", "kol");
  url.searchParams.set("chains", "solana,base");

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.API_KEY}` },
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const { trades, nextCursor, hasMore } = await response.json();
  ```

  ```rust Rust theme={null}
  use serde_json::Value;

  let page: Value = reqwest::Client::new()
      .get("https://{{API_HOST}}/v1/trades")
      .query(&[("identity", "kol"), ("chains", "solana,base")])
      .bearer_auth(std::env::var("API_KEY")?)
      .send()
      .await?
      .error_for_status()?
      .json()
      .await?;

  for trade in page["trades"].as_array().into_iter().flatten() {
      println!("{} {} {}", trade["chain"], trade["symbol"], trade["volume"]["usd"]);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Page theme={null}
  {
    "trades": [
      {
        "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" },
        "identities": [
          {
            "source": "fomoscan",
            "handle": "degenspartan",
            "displayName": "Degen Spartan",
            "avatar": "https://cdn.example.com/avatars/degenspartan.png",
            "twitter": "degenspartan",
            "telegram": null,
            "farcaster": null
          }
        ],
        "timestamp": 1789632015120
      }
    ],
    "nextCursor": null,
    "hasMore": false
  }
  ```

  ```json Unknown feed theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "One or more parameters are invalid.",
      "details": [{ "field": "identity", "message": "Must be one of: kol, fomoscan." }]
    }
  }
  ```
</ResponseExample>


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