# Watchlists & screener

Your saved lists and screens, and a screener over every Hyperliquid market.

## list_watchlists

Your saved watchlists and screener screens, with live figures for each market if asked.

Marks: Reads only.

### Inputs

- `withMarketData`: `true` or `false`. Default `false`.

What the AI app reads: The user's watchlists saved to their account (id, name, sections, markets, the columns the list shows) and their saved screener screens (id, name, rules). Markets are symbols like BTC-PERP, xyz:AAPL-PERP or HYPE-SPOT. With withMarketData: true each market also carries its last price, 24h change in %, funding in % per 8 h, 24h volume and open interest in dollars.

## edit_watchlist

Makes, changes or deletes a watchlist: add or remove markets, choose its columns and sort.

Marks: Makes changes · Two steps to delete a list · A deleted list can’t come back.

### Inputs

- `listId`: text (letters, digits, `-` and `_`, up to 64). From `list_watchlists`; `favs` is Favourites. Leave out, with a `name`, to make a new list.
- `name`: text (not empty, up to 40 characters).
- `add`: list of up to 500; each text (not empty, up to 60 characters).
- `section`: text (up to 40 characters).
- `remove`: list of up to 500; each text (not empty, up to 60 characters).
- `columns`: list of up to 5; each one of `last`, `chg`, `funding`, `vol`, `oi`.
- `sort`: one of `manual`, `chg`, `price`.
- `delete`: `true` or `false`. `true` deletes the list, together with `confirm`.
- `confirm`: `true` or `false`. Needed with `delete`. Without it the tool asks the AI app to name the list and how many markets it holds first. Default `false`.

What the AI app reads: Make, change or delete one of the user's watchlists saved to their account. Leave listId out and give a name to make a new list. add and remove take markets as BTC-PERP, HYPE-SPOT, xyz:AAPL-PERP or a plain name (a plain name means the perpetual when there is one); add puts them in `section` (found by name, made when new; none = the first section). run_screen's allMatched can go straight into add. columns = the figures the list shows (last, chg, funding, vol, oi); sort = manual, chg or price. Favourites (listId "favs") can be changed but not renamed or deleted. Deleting can't be undone: tell the user which list first.

## run_screen

Screens every Hyperliquid market by change, volume, open interest, funding, RSI or distance from an average, or runs one of your saved screens.

Marks: Reads only.

### Inputs

- `screenId`: text (letters, digits, `-` and `_`, up to 64). From `list_watchlists`.
- `screenName`: text (not empty, up to 60 characters).
- `rules`: object.
  - `kind`: one of `all`, `perps`, `spot`, `hip3`.
  - `chgMin`: number or `null`.
  - `chgMax`: number or `null`.
  - `volMin`: number (at least 0) or `null`.
  - `oiMin`: number (at least 0) or `null`.
  - `fundMin`: number or `null`.
  - `fundMax`: number or `null`.
  - `tf`: one of `15m`, `1h`, `4h`, `1d`.
  - `rsiLen`: whole number (2 to 100).
  - `rsiMin`: number (0 to 100) or `null`.
  - `rsiMax`: number (0 to 100) or `null`.
  - `maType`: one of `sma`, `ema`.
  - `maLen`: whole number (2 to 200).
  - `maDistMin`: number or `null`.
  - `maDistMax`: number or `null`.
- `sortBy`: one of `market`, `last`, `chg`, `funding`, `vol`, `oi`, `rsi`, `maDist`.
- `sortDir`: one of `asc`, `desc`.
- `limit`: whole number (1 to 50). Default `20`.

What the AI app reads: Screen every Hyperliquid market (main perpetuals, HIP-3 markets and spot) by rules, or run one of the user's saved screens (screenId or screenName from list_watchlists). Rules: kind all|perps|spot|hip3; chgMin / chgMax = 24h change in %; volMin = 24h volume and oiMin = open interest, both in MILLIONS of dollars; fundMin / fundMax = funding in % per 8 h. Indicator rules are read on the last closed bar of tf (15m, 1h, 4h or 1d; default 1h): rsiMin / rsiMax with rsiLen (default 14), and maDistMin / maDistMax = how far the close is from its average, in %, with maType sma|ema and maLen (default 50). No rules = every market. Most traded first unless sortBy says otherwise. Markets whose price history could not be read are listed as not checked, with the reason — say so rather than treating them as failing. allMatched can go straight into edit_watchlist's add.

Updated: 2026-10-20

Web page: https://buildtrade.app/docs/tools/watchlists/