# Tokens

> tokens.get, tokens.search, tokens.subscribe and tokens.update.

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.

## `tokens.get`

Tokens, filtered and sorted, once. HTTP: `/tokens`.

| Param | Description |
| --- | --- |
| `fields` | **Required.** [Token fields](https://docs.intear.tech/api/reference/token-fields.md) to return |
| `ids` | Only these tokens, up to 2,000 |
| `where` | Filters, see [below](#where) |
| `sort` | `{ "by": "<field>", "desc": true }`, by a numeric field. `null` values come last, ascending or descending, but a missing price is `"0"` and sorts as 0. Without `sort`, tokens are in account ID order |
| `limit`, `offset` | A page of the sorted tokens. Both need `sort` |
| `precision` | 1 to 30, rounds string prices, see [Token fields](https://docs.intear.tech/api/reference/token-fields.md#prices) |
| `min_change` | Thresholds, as for [`tokens.subscribe`](#tokenssubscribe). The values are those subscribers with the same thresholds were sent |
| `since` | The `height` of an earlier result with the same params, for only what changed after it. Not with `sort`, `limit` or `offset`. See [Keeping every token](https://docs.intear.tech/api/guides/syncing-tokens.md) |

Result:

```json
{ "height": 219969220, "timestamp_millis": 1792003477277, "columns": ["account_id", "symbol"], "rows": [["wrap.near", "wNEAR"]], "total": 1, "missing": [] }
```

- `total`: how many tokens matched, before `limit` and `offset`.
- `missing`: the `ids` that aren't tokens.
- With `since`, also `resumed`, and `left` when it's `true`. With `"resumed": true`, `rows` are only the tokens that changed after that height, each with every field, and `left` the tokens that stopped matching `where`. With `"resumed": false`, `rows` has every token.

### `where`

All optional:

| Filter | Description |
| --- | --- |
| `parent` | An account or a list of them: only tokens directly under one. `meme-cooking.near` has `abc.meme-cooking.near` but not `x.abc.meme-cooking.near` |
| `min_reputation` | `Spam`, `Unknown`, `NotFake` or `Reputable` |
| `deleted` | `true` for only deleted tokens, `false` for only ones that aren't |
| `min`, `max` | `{ "<field>": number }`, inclusive bounds on numeric fields |
| `created_after_millis` | Only tokens created after this time |

## `tokens.search`

Tokens matching a search, best match first. HTTP: `/tokens/search`.

| Param | Description |
| --- | --- |
| `q` | **Required.** Matched against symbol, name, account ID and social links |
| `fields` | **Required.** Token fields to return |
| `limit` | At most 100, default 10 |
| `min_reputation` | Default `Unknown` |
| `holder` | An account whose tokens rank higher |
| `parent` | Only tokens directly under this account, or a list of them |
| `precision` | As for `tokens.get` |

The result is `{ "height", "timestamp_millis", "columns", "rows" }`.

## `tokens.subscribe`

Follows tokens as they change. See [Live token lists](https://docs.intear.tech/api/guides/live-token-lists.md) for how to use it.

Takes the params of `tokens.get` except `offset` and `since`, and:

| Param | Description |
| --- | --- |
| `min_change` | `{ "<field>": "<threshold>" }`: that field only changes once it's moved by the threshold since the value last sent, either way. A change from or to 0 always counts. Thresholds: `0.01%`, `0.1%`, `0.25%`, `0.5%`, `1%`, `2%`, `5%`, `10%` |
| `min_interval_ms` | At most one push per this much block time: `200`, `600`, `1000`, `5000`, `15000` or `60000` |
| `snapshot` | Default `true`. `false` leaves `rows` in the result empty |
| `resume_from` | The `height` of the last reply or push before a reconnect, for only what changed since |

With `sort` and `limit`, it follows the top `limit` tokens as they change places. The sort field has to be one of `fields`.

The result is `{ "height", "timestamp_millis", "columns", "rows" }`. Each push is:

```json
{ "sub": 1, "height": 219969292, "timestamp_millis": 1792003519000, "set": { "<token>": { "<field>": "value" } }, "created": ["<token>"], "left": ["<token>"] }
```

- `set`: the fields that changed. A token the subscription didn't have before has every field.
- `created`: tokens in `set` that were just created.
- `left`: tokens the subscription is no longer about.

Each of the three is left out when empty.

With `resume_from`, the result is `{ "height", "timestamp_millis", "resumed": true, "set", "created", "left" }`, shaped like a push. A token that may have come to match `where` since has every field, and `left` can name tokens the client never had. When the server can't work out what changed (it restarted since, or the subscription has a `limit`), the result has `"resumed": false` and every row.

## `tokens.update`

Changes the tokens a `tokens.subscribe` with `ids` follows, say the ones on screen.

| Param | Description |
| --- | --- |
| `sub` | **Required.** The subscription's `id` |
| `add` | Tokens to start following |
| `remove` | Tokens to stop following |

The result is `{ "height", "timestamp_millis", "columns", "rows", "missing" }`: the added tokens as of that `height`, and `missing` the ones that aren't tokens. Pushes after it carry changes to the added tokens after that `height`.