# Trades

> trades.query and trades.subscribe, and the fields of a trade.

This page is part of the Intear API docs. The Intear API is at `https://api.intea.rs` and `wss://api.intea.rs/ws`, with no API key. https://docs.intear.tech/api/llms-full.txt has all of its pages in one file, and https://docs.intear.tech/llms.txt lists every page of the Intear docs.

## Filters

Both methods take these, all optional:

| Param | Description |
| --- | --- |
| `fields` | **Required.** [Trade fields](#trade-fields) to return. `id` always comes first |
| `token` | Trades with this token on either side, or a list of up to 100 tokens. Each trade appears once per listed token it has, seen from that token, so a trade between two listed tokens appears twice |
| `parent` | Instead of `token`: the tokens directly under an account or a list of them, as they are when the request is made, up to 100 tokens |
| `counterparty` | The other token. Needs `token` |
| `trader` | Trades by this account |
| `pool` | Trades in this pool, like `REF-6063`. Needs `token` |
| `side` | `sell`, `buy`, `add_liquidity` or `remove_liquidity`. With `token`, only trades where it went in or came out, or only that kind of liquidity change. Without it, `sell` and `buy` pick which token each trade is seen from (`buy` means `token_out`) |
| `include_liquidity` | Default `false`. Liquidity changes alongside swaps, when `side` isn't given |
| `min_usd` | One of `10`, `50`, `100`, `500`, `1000`, `5000`, `10000` |

Every page is read off an index for its filters, so filters that would read through trades they don't match are a `bad_request`, for `trades.subscribe` from now on too. `token` here means `token` or `parent`:
- `counterparty` with `trader` or `min_usd`.
- `min_usd` with `trader`.
- `pool` without `token`, or with `trader` or `min_usd`.
- `side: "buy"` without `token` or `trader`.
- A liquidity `side` without `token` or `trader`, or with `min_usd`.

## `trades.query`

A page of trades, newest first, or oldest first with `order`. HTTP: `/trades`.

| Param | Description |
| --- | --- |
| `limit` | 1 to 200, default 50 |
| `cursor` | `next_cursor` from the page before |
| `after_millis` | Inclusive |
| `before_millis` | Exclusive |
| `order` | `newest` (default) or `oldest`: from `after_millis` toward the present, to read on from a time |

Result:

```json
{ "height": 219969289, "timestamp_millis": 1792003517185, "columns": ["id", "side"], "rows": [[6860365, "buy"]], "next_cursor": "RHvi3clKJUycH_jE84V6ZFXMlvFoouR5I4CvZFyguT06BPYukH7NsUSGUij8b20CrxugtPeSNjGBUPYz2GyPowI62A", "latest_id": 6860368 }
```

- `next_cursor`: pass as `cursor`, with the same `order`, for the next page. `null` on the last page, which oldest first is the newest one.
- `latest_id`: the newest trade the result accounts for, of all trades, not just matching ones.

## `trades.subscribe`

History, then live trades. See [History, then live](https://docs.intear.tech/api/guides/history-then-live.md). Takes one of:

| Param | Description |
| --- | --- |
| `history` | 1 to 200: the newest trades, newest first, in the result, with `next_cursor` if there are more |
| `after_id` | Every trade after this one, oldest first, in the result. More than 10,000 is `too_far_behind` |
| neither | Only trades from now on |

The result is `{ "height", "timestamp_millis", "columns", "rows", "latest_id" }`, plus `next_cursor` with `history`. Each push is `{ "sub", "height", "timestamp_millis", "rows" }` with a block's matching trades, oldest first, in the result's columns.

To pick up after a reconnect, subscribe again with `after_id` set to the newest `id` you have, or the result's `latest_id` if that's newer.

## Trade fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | number | Identifies this view of the trade. The same trade seen from its other token has another `id` |
| `height`, `timestamp_millis` | number | The block it's in |
| `trader` | string | The account that swapped, or the liquidity provider |
| `pool_id` | string | Like `REF-6063` |
| `pool_url` | string | The pool's page on its DEX |
| `transaction_id`, `receipt_id` | string | |
| `token_in`, `amount_in` | string or `null` | What was sold. `null` for liquidity changes |
| `token_out`, `amount_out` | string or `null` | What was bought. `null` for liquidity changes |
| `token`, `amount` | string | The trade seen from one of its tokens: the filtered one with a `token` or `parent` filter. Otherwise `token_out` with a `side: "buy"` filter, and `token_in` without one |
| `counterparty`, `counterparty_amount` | string | The other token |
| `side` | string | `sell` if `token` went in, `buy` if it came out, or `add_liquidity` or `remove_liquidity` |
| `usd_value` | string or `null` | At the prices from before its block. `null` when neither token had a price yet. For a liquidity change, both tokens together |
| `referrer` | string or `null` | The app or aggregator the swap came through, as the DEX reports it. Always `null` for liquidity changes |

- Amounts are in each token's smallest units.
- Native NEAR is always `wrap.near`, so its trades are found with `token: "wrap.near"`. Wrapping and unwrapping aren't trades.
- For liquidity changes, `token` and `counterparty` are the pool's two tokens.

## Referrers' names and icons

`GET /cosmetics` returns how to show trades: the name, emoji and icon of the apps and aggregators that trades name as their `referrer`, and an emoji for some traders. Nothing on chain says these, so Intear sets them by hand, and only some accounts have them. It's HTTP only, and can be cached for a minute.

```json
{
  "referrers": {
    "<account id>": {
      "emoji": "💦",
      "telegram_custom_emoji_id": "5953988320630415439",
      "name": "Intear DEX",
      "icon": "/referral/inteardex.png"
    }
  },
  "users": {
    "<account id>": { "emoji": "🐳" }
  }
}
```

`referrers` and `users` are keyed by account ID. `icon` is the path of an image on `https://api.intea.rs`. `telegram_custom_emoji_id` is the ID of a Telegram custom emoji to show instead of `emoji` where Telegram can.