Referência

Linguagem de consulta

Esta referência está em inglês. A navegação e os rótulos estão traduzidos.

One small language describes a query everywhere: the Explorer's Query mode, GET /instruments?q= and the MCP tool screen_instruments. Write it once, paste it anywhere.

Examples

A query is a list of conditions, optionally followed by sort and limit clauses:

<condition> and <condition> … sort <field> [asc|desc] limit <n>

Field names and keywords are case-insensitive. Text values can be bare words (ethereum, prt_aave-v3) or quoted ("Aave V3"). Protocol and chain filters accept the id or the display name.

Exemplo

apy >= 6.5 and band = low and class = stablecoin sort apy desc limit 20

chain in (ethereum, base) and tvl > 100m and verdict = pass sort score desc, tvl desc

verdict = fail and rule = recent_incident sort tvl desc

class = ether and signals contains incentive_dependent

search "usdc" and protocol = prt_aave-v3

apy between 4 and 8 and not il and exit = instant

id in (ins_4c29f40abec73e1b, ins_0abd5ec576be07e6)

Conditions

Syntax	Meaning	Example
= !=	Equal, not equal (also == and <>)	band = low
> >= < <=	Compare numbers and dates	tvl >= 250m
between … and …	Inclusive range	apy between 4 and 8
in (…) not in (…)	One of a list	chain in (ethereum, arbitrum)
contains	Text: case-insensitive substring. Signals: has the signal	signals contains exit_queue
not contains	Signals: does not have it	signals not contains small_tvl
is null is not null	Missing or present value	exit is not null
field not field	Boolean fields	not screen.in_report
search "…"	Free text over name, detail, protocol and chain	search "usdc"
id in (…)	Only these instruments, up to 200	id in (ins_4c29f40abec73e1b)

not in front of a condition negates it: not chain = ethereum.

Joining conditions

Join conditions with and or with or, one of the two per level. Use parentheses to group, and keep one kind of join inside each group:

search "usdc" and (chain = base or chain = arbitrum)

search and id in always combine with and. Mixing and and or without parentheses is an error, so a query never means something you didn't write.

Sort, limit and paging

sort field [asc|desc], field [asc|desc]: without a direction, numbers and dates sort descending and text ascending.
limit n: rows per page, up to 100 in the API and 25 in MCP.
offset n: for page-number interfaces, up to 10,000. API clients should prefer cursor.

Clauses go at the end, in any order.

Values

Numbers accept k, m and b: tvl > 10m, tvl >= 1.5b.
A trailing % is accepted and ignored, because rates are already in percent: apy >= 5% is apy >= 5. Ratio fields take 0–1: incentive_share < 0.5.
Dates are YYYY-MM-DD: first_seen >= 2026-10-01.
Enum values are checked: an unknown value returns the list of valid ones.

Fields and aliases

Every field of the Instrument you can filter or sort on, with its short aliases. The same list, with operators and facet counts, comes from GET /schema.

Field	Aliases	Type
name	asset, token	string
detail	label	string
venue.protocol	protocol	string
venue.chain	chain, network	string
asset_class	class	enum
exposure.stable_only	stable_only, stable	boolean
exposure.single_asset	single_asset, single	boolean
exposure.impermanent_loss	impermanent_loss, il	boolean
yield.total_apy	apy, total_apy	number · percent
yield.native_apy	native_apy, native	number · percent
yield.incentive_apy	incentive_apy, incentive	number · percent
yield.incentive_share	incentive_share	number · 0–1
yield.trailing_7d_apy	apy_7d, trailing_7d_apy	number · percent
yield.trailing_30d_apy	apy_30d, trailing_30d_apy	number · percent
yield.change_1d_pp	change_1d	number · percent
yield.change_7d_pp	change_7d	number · percent
yield.change_30d_pp	change_30d	number · percent
yield.consistency_30d	consistency	number · 0–1
yield.realized_30d_apy	realized_apy	number · percent
yield.realized_confidence	confidence	enum
liquidity.tvl	tvl	number · USD
liquidity.volume_24h	volume	number · USD
liquidity.depositor_count	depositors	number
liquidity.top10_concentration	top10, concentration	number · 0–1
liquidity.exit.state	exit	enum
liquidity.exit.eta_seconds	exit_eta	integer · seconds
liquidity.exit.capacity	exit_capacity	number · USD
safety.score	score	number
safety.band	band, risk	enum
safety.signals	signals, signal	enum[]
safety.audit.on_record	audited	boolean
safety.audit.count	audits	number
safety.incidents.count	incidents	number
safety.incidents.last_at	last_incident	string · YYYY-MM-DD
safety.incidents.total_lost	total_lost	number · USD
safety.protocol_age_days	age, protocol_age	integer · days
screen.verdict	verdict	enum
screen.failed_rule	rule, failed_rule	enum
screen.in_report	in_report, report	boolean
screen.report_rank	rank	number
screen.first_seen	first_seen	string · YYYY-MM-DD

How a query is parsed

The API parses the text into a structured query and returns it in query, so you can check how it was read. The same structure can be sent as JSON to POST /instruments/search.

A query that doesn't parse returns 400 invalid_query with position, the character offset of the problem in q.

query (from the response)

{
  "where": [
    {
      "field": "yield.total_apy",
      "op": "gte",
      "value": 6.5
    },
    {
      "field": "safety.band",
      "op": "eq",
      "value": "low"
    },
    {
      "field": "asset_class",
      "op": "eq",
      "value": "stablecoin"
    }
  ],
  "match": "all",
  "sort": [
    {
      "field": "yield.total_apy",
      "direction": "desc"
    }
  ],
  "limit": 20
}

400 invalid_query400

{
  "type": "https://yieldsniper.finance/developers/errors#invalid_query",
  "title": "Invalid query",
  "status": 400,
  "code": "invalid_query",
  "detail": "Unknown field \"yield.apy\".",
  "position": 0,
  "request_id": "req_5670f65858310f3c37f932e4"
}