> 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/assets.md).

# Assets

Search assets, read prices and details, and list trending assets and movers.

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

## List and search assets

`GET /assets`

| Parameter         | Type      | Description                                                                                                                                                |
| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q`               | string    | Name or asset ID to search for: 3 to 20 letters, digits, spaces, `_` or `-`.                                                                               |
| `asset`           | string\[] | Up to 10 asset IDs to fetch. Overrides every other parameter.                                                                                              |
| `filter`          | string\[] | All must match: `verified`, `haylaunch` (launched on HayLaunch), `haylaunchBonding` (still on its bonding curve), `haylaunchBonded` (graduated to a pool). |
| `sortBy`          | string    | `tvl` (default), `volume`, `mcap`, `chg1h`, `chg24h`, `chg7d`, `chg30d` or `creation`.                                                                     |
| `order`           | string    | `desc` (default) or `asc`.                                                                                                                                 |
| `limit`           | integer   | 1 to 100, default 40.                                                                                                                                      |
| `paginationToken` | string    | A `cursor.nextToken` or `cursor.prevToken` from the previous page.                                                                                         |

```bash
curl -H "X-API-Key: $HAY_KEY" "https://api.hay.app/api/assets?q=usdc&limit=5"
```

The response is `{ "assets": [Asset], "cursor": { "nextToken", "prevToken" } }`. Each asset has:

| Field                                | Description                                                                                                                                                                                                                |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`, `name`, `unitName`, `decimals` | The ASA's parameters. ALGO is `0`.                                                                                                                                                                                         |
| `creator`, `image`, `url`            | Creator address, logo URL, the asset's URL.                                                                                                                                                                                |
| `creationTime`                       | When the asset was created (missing for some older assets).                                                                                                                                                                |
| `verified`                           | Verification tier from Pera: `trusted`, `verified` or `suspicious`. Absent when unverified.                                                                                                                                |
| `launchpad`                          | `haylaunch` or `rugninja`, for tokens from a launchpad.                                                                                                                                                                    |
| `bondingState`, `bondingProgress`    | HayLaunch tokens: `preBonding` or `bonded`, and how far the curve is to bonding, in percent.                                                                                                                               |
| `price`                              | `{ timestamp, price, usdPrice }`: the current price of one whole token in ALGO and in USD. `timestamp` is when the response was made, not when the price last moved.                                                       |
| `priceConfidence`                    | 0 to 1: how hard the price is to move, from the depth of the pools that set it. Treat a low value's price with care.                                                                                                       |
| `mktData`                            | `change` (percent changes over 5 minutes, 1 hour, 24 hours, 7 days and 30 days), `volume24h` (USD), `marketCap`, `fdmarketCap`, `tvl` (USD), `totalSupply`, `circulatingSupply`, `burnedSupply` (whole tokens), `holders`. |
| `moderation`                         | `{ flagged: true }` when Haystack's moderation flagged the asset (for example as NSFW). Hide or blur its image.                                                                                                            |
| `marketSignals`                      | Present only when the asset's recent trading looks manipulated. See [Market signals](#market-signals).                                                                                                                     |

{% hint style="info" %}
A HayLaunch token still on its bonding curve reports its price changes in the asset it bonds in, so in USD it moves with that asset whether it trades or not.
{% endhint %}

## Prices

`GET /assets/prices?asset=<id>&asset=<id>...`

The current price of up to 100 assets: `{ "prices": [{ id, decimals, price, usdPrice, priceConfidence, moderation }] }`, in request order. `price` is in ALGO and `usdPrice` in USD, both per whole token. Unknown or unpriced assets are left out, so match results by `id`, not by position.

Use this for polling many prices. For a live feed, use the [WebSocket](/haystack-dev/haystack-api/websocket.md). Don't call the router's `fetchQuote` for prices: it is far slower, and it prices one trade of a given size, not the asset.

## Asset details

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

An unknown asset gets `404`. Otherwise it returns project details: `Description`, `Url`, `Name`, `twitterUrl`, `telegramUrl`, `discordUrl`, and for HayLaunch tokens a `haylaunch` object with the token's curve state:

* `bondingState`, `bondingProgress`, and `bondingTokenId`: the asset it bonds in, ALGO (`0`) or an ASA.
* Curve reserves and targets (`realTokenReserves`, `realBondingReserves`, `virtualTokenReserves`, `virtualBondingReserves`, `bondingTarget`, ...), in base units.

Every integer in `haylaunch` (IDs, reserves, fees) is a JSON string.

* `bondingOn` (`0` still on the curve, `2` bonded into Pact, `3` bonded into Pact V2) and, once bonded, `pactPoolId` and `lpTokenId`.
* `feeBpsPlatform` and `feeBpsCreator`: the curve's fees in basis points.
* `creatorFees`: the fees its creator has earned. See [Accounts](/haystack-dev/haystack-api/accounts.md#creator-earnings).

## Check asset IDs

`POST /assets/validAssets` with body `{ "assetIds": ["31566704", "123"] }` (1 to 100 IDs, as strings) returns `{ "assets": { "31566704": true, "123": false } }`: whether Haystack knows each asset.

## Trending, movers and boosts

| Endpoint               | Returns                                                                                                                                                                                                                                                                           |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /assets/trending` | Up to `limit` (max 40) assets: boosted assets first (as in `/assets/boosts`), then by 24-hour volume, leaving out common assets such as stablecoins and liquid-staking tokens. Assets with a market-signals warning stay in, with their `marketSignals`. `{ "assets": [Asset] }`. |
| `GET /assets/movers`   | The biggest gainers and losers, up to `limit` (max 20) each: `{ "gainers": [{ asset, change }], "losers": [...] }`, `change` in percent. Assets with a market-signals warning are left out.                                                                                       |
| `GET /assets/boosts`   | Boosted assets in order: `[{ assetId, boost }]`, `assetId` as a string.                                                                                                                                                                                                           |

## Market signals

`marketSignals` flags an asset whose recent trading looks manipulated: a few wallets, the creator among them, moving the price. It has:

* `level`: `caution` or `warning`. A warning means the creator, or wallets linked to the creator by how they were funded, are central to it. Warned assets are left out of the movers.
* `reasons`: which signs were seen. `volumeConcentrated` (a few wallets did nearly all the volume), `creatorTrading` (the creator and its linked wallets did a large share), `roundTrip` (much of it was bought and sold back by the same wallets), `pullThenPump` (liquidity pulled, then the same wallets did most of the buying), `liquidityChurn` (liquidity pulled more than once), `linkedSupply` (the creator and its linked wallets hold a large share of the supply).
* The figures behind the reasons given, the USD volume and price swing in the window, the window (`windowStart`, `windowEnd`), and `expiresAt`: when the level lapses unless trading reaches it again.

Show signals as a warning to your users, not as a verdict. [`/assets/creatorLinks`](/haystack-dev/haystack-api/trades-and-liquidity.md#creator-links) lists the linked wallets.

## Rate limits

| Endpoint                                           | Requests per minute |
| -------------------------------------------------- | ------------------- |
| `assets`                                           | 330                 |
| `assets/prices`                                    | 300                 |
| `assets/validAssets`                               | 80                  |
| `assets/trending`                                  | 300                 |
| `assets/details`, `assets/movers`, `assets/boosts` | 30                  |
