> For the complete documentation index, see [llms.txt](https://txnlab.gitbook.io/haystack-dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://txnlab.gitbook.io/haystack-dev/haystack-api/trades-and-liquidity.md).

# Trades & Liquidity

An asset's trades, liquidity adds and removes, top holders, and the wallets linked to its creator.

All paths are under `https://api.hay.app/api`. The full schemas are in the [OpenAPI specification](https://api.hay.app/info/openapi3.yaml).

## Activity

`GET /assets/activity?asset=<id>`

An asset's trades and the liquidity adds and removes in its pools, in one list, newest first. Only Tinyman V2, Pact and Pact V2 adds and removes are tracked.

| Parameter          | Type      | Description                                                                                                                                          |
| ------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asset`            | integer   | Required.                                                                                                                                            |
| `kinds`            | string\[] | `trade`, `liquidity`, or both (the default).                                                                                                         |
| `type`             | string    | `buy` or `sell`: trades of that side only.                                                                                                           |
| `account`          | address   | Only this trader or liquidity provider.                                                                                                              |
| `creatorSide`      | boolean   | Only the asset's creator side: its creator, reserve, HayLaunch creator and their [linked wallets](#creator-links). Can't be combined with `account`. |
| `minUsd`           | number    | Smallest USD value to include.                                                                                                                       |
| `excludeLiquidity` | boolean   | Leave out adds and removes and the swaps inside them. Can't be combined with `kinds=liquidity` alone.                                                |
| `start`, `end`     | RFC 3339  | A time range. Give both or neither.                                                                                                                  |
| `limit`            | integer   | 1 to 250, default 40.                                                                                                                                |
| `paginationToken`  | string    | A `cursor` token from the previous page.                                                                                                             |

```bash
curl -H "X-API-Key: $HAY_KEY" "https://api.hay.app/api/assets/activity?asset=31566704&kinds=trade&limit=20"
```

The response is `{ "items": [...], "cursor": { nextToken, prevToken } }`. Each item has a `kind`:

* **`trade`**: `trade` holds the swap. Fields include:
  * `timestamp`, `round`, `roundPos`, `groupId`, `type` (`buy` or `sell`), `account`, and `nfd`/`nfdAvatar` when the trader has an NFD.
  * `amount`, in whole tokens.
  * `liquidityOp` (`addFlexible`, `addSingle` or `removeSingle`), when the trade is the swap inside a liquidity add or remove rather than one the account made. See below.
  * `priceInAlgo` and `priceInUsd`, per whole token, and `totalCostUsd`.
* **`liquidity`**: `liquidity` holds the add or remove. Fields include:
  * `type` (`bootstrap`, `addFlexible`, `addSingle`, `removeProportional` or `removeSingle`), `side` (`add` or `remove`), `account`, `protocol`, `poolAddress`.
  * `asset1` and `asset2`: each with its `amount` in whole tokens and `amountUsd`.
  * `totalUsd` and `poolSharePct`.
  * Item-level `priceInAlgo` and `priceInUsd`: the asset's price at the time.

An uneven or single-sided add or remove also swaps one asset for the other:

* When adds and removes are listed, that swap is in the item's `swap`.
* Otherwise (`kinds=trade`, and on the [WebSocket](/haystack-dev/haystack-api/websocket.md)) it is a trade with `liquidityOp` set.

Pass `excludeLiquidity=true` to leave it out.

With `creatorSide=true`, `accounts` lists the wallets it covered, so you can tell which live trades belong in the list. When the asset has no creator side, `accounts` is left out and `items` is empty.

{% hint style="info" %}
`/assets/history` is deprecated. Use activity with `kinds=trade`, which lists the same trades.
{% endhint %}

## Liquidity

`GET /assets/liquidity?asset=<id>` lists only the adds and removes, as `{ "events": [...], "cursor": {...} }`, newest first. It takes `account` (a liquidity provider), `limit` (1 to 100, default 40) and `paginationToken`. Activity with `kinds=liquidity` returns the same events, with their swaps and prices folded in.

## Top holders

`GET /assets/topHolders?asset=<id>`

The asset's largest holders: `[{ address, nfd, nfdAvatar, amount, stakedAmount, type, poolId }]`. Amounts are in whole tokens.

* `amount` includes `stakedAmount` (HAY staking or Pact farms) and any tokens the HayLaunch app holds for the account.
* `type` is empty for an ordinary account. Otherwise it names the exchange of a pool (`TinymanV2`, `PactV2`, ...) with its `poolId`, `Burn`, `PactV2Farm` (a Pact farm's unpaid rewards, `poolId` the farm's app ID), or `PactV2Vault` (Pact V2 Vault holdings that couldn't be assigned to a pool or farm).

What the Pact V2 Vault holds is split out onto its pools, farms and stakers rather than listed as one holder.

## Creator links

`GET /assets/creatorLinks?asset=<id>`

The wallets tied straight to an asset's creator by how they were created, to tag beside the creator in trades, liquidity and holders:

* `links`: `[{ address, relation, insider, via }]`.
  * `relation`: `fundedCreator` (the wallet paid the ALGO that created the creator), `fundedByCreator` (the creator paid the ALGO that created the wallet), or `sameFunder` (the wallet that created the creator created this one too, around the same time; `via` is that wallet).
  * `insider`: whether the tie is to the `creator` or to the asset's `reserve` address.
* `declared`: `[{ address, label, verified }]`: wallets whose holdings don't circulate, such as the reserve or a project's team and treasury wallets. `verified` means Haystack checked it. Otherwise the token declares it on chain itself, which whoever manages the token can change.

A funding counts only when the account signs for itself, the payment wasn't made by a contract, and the funder isn't an exchange or another wallet that funds many accounts. Only wallets Haystack has looked up are listed, so a wallet missing from `links` isn't proof it's unrelated.

## Rate limits

| Endpoint                                   | Requests per minute |
| ------------------------------------------ | ------------------- |
| `assets/activity`                          | 60                  |
| `assets/creatorLinks`, `assets/topHolders` | 30                  |
| `assets/liquidity`                         | 20                  |
