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

# Token trades

> Page through one token's executed trades, newest first, narrowed by trader or wallet classification.

```http theme={null}
GET /v1/tokens/{chain}/{address}/trades
```

Recent trades on one token, newest first. The page is cursor-paged; see [Pagination](/concepts/pagination).

## Path parameters

<ParamField path="chain" type="string" required>
  The [chain slug](/concepts/chains).
</ParamField>

<ParamField path="address" type="string" required>
  The token's address.
</ParamField>

## Query parameters

<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. Never build one yourself.
</ParamField>

<ParamField query="trader" type="string">
  Keep only this wallet's trades. The address must match the chain's format.
</ParamField>

<ParamField query="flags" type="string">
  Comma-separated [wallet classifications](/resources/glossary#wallet-classifications) to keep, such as `bundler,insider`. A trade is kept when its trader carries at least one. Absent or empty keeps every trade.
</ParamField>

## Response

<ResponseField name="trades" type="object[]" required>
  Trades on this page, newest first.
</ResponseField>

<ResponseField name="nextCursor" type="string | null" required>
  Cursor for the next page; `null` on the last page.
</ResponseField>

<ResponseField name="hasMore" type="boolean" required>
  Whether a next page exists.
</ResponseField>

### 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` | `chain` is not a supported slug |
| `VALIDATION_ERROR` | A malformed address, a `trader` that does not match the chain's format, an unknown flag, a cursor that does not decode, or an unknown parameter |

An unknown token answers an empty page, not a `404`.

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

  ```bash Filtered theme={null}
  curl "https://{{API_HOST}}/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/trades?flags=bundler,insider" \
    -H "Authorization: Bearer $API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const url = new URL(
    "https://{{API_HOST}}/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/trades",
  );
  url.searchParams.set("limit", "50");

  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/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/trades")
      .query(&[("limit", "50")])
      .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["side"], 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" },
        "timestamp": 1789632015120
      }
    ],
    "nextCursor": "eyJ0cyI6MTc4OTYzMjAxNTEyMCwiaWQiOiI0eFFtVmI4ZTJrVDFuUjdwWmNXM3NMZEhmQTlq",
    "hasMore": true
  }
  ```

  ```json Empty page theme={null}
  {
    "trades": [],
    "nextCursor": null,
    "hasMore": false
  }
  ```
</ResponseExample>


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