Empezar

Primeros pasos

Inicio rápido

Esta referencia está en inglés. La navegación y las etiquetas están traducidas.

Three steps from a new key to your first query. You need a paid Yield Sniper account.

1. Create a key

  1. Open Settings → API & MCP and choose Create key.
  2. Name it after where it will run, for example Research notebook, and keep the read scope.
  3. Copy the secret. It is shown once; we only store a hash of it.

Keep the secret in an environment variable or a secret manager, never in code you commit or ship to a browser. The samples on these pages read it from YS_API_KEY.

Shell
export YS_API_KEY="ys_live_…"

2. Make a request

Send the key as a Bearer token. GET /screens/latest returns the most recent daily screen: how many instruments were screened, how many passed, and why the rest failed.

Check as_of: it is the time of the screen, not of your request. The data changes once a day, so you can cache responses until the next screen.

Solicitud
curl https://yieldsniper.finance/api/v1/screens/latest \
  -H "Authorization: Bearer $YS_API_KEY"
Respuesta200
{
  "object": "screen",
  "id": "scr_2026-10-23",
  "date": "2026-10-23",
  "as_of": "2026-10-23T23:45:21.116Z",
  "universe": {
    "instruments": 15948,
    "protocols": 503,
    "chains": 105,
    "tvl": 152788660398
  },
  "outcome": {
    "passed": 131,
    "failed": 15817,
    "pass_rate": 0.008214,
    "in_report": 12
  },
  "failures_by_rule": [
    {
      "rule": "tvl_floor",
      "count": 15655
    },
    {
      "rule": "out_of_scope",
      "count": 88
    },
    {
      "rule": "apy_floor",
      "count": 62
    },
    {
      "rule": "unaudited_small",
      "count": 7
    },
    {
      "rule": "exit_blocked",
      "count": 2
    },
    {
      "rule": "recent_incident",
      "count": 2
    },
    {
      "rule": "score_floor",
      "count": 1
    }
  ],
  "leaders": [
    {
      "asset_class": "stablecoin",
      "total_apy": 8.13962,
      "instrument_id": "ins_f3cbaa85fd31098b"
    },
    {
      "asset_class": "bitcoin",
      "total_apy": 1.73072,
      "instrument_id": "ins_7f329ae62bbbf561"
    },
    {
      "asset_class": "ether",
      "total_apy": 3.6921,
      "instrument_id": "ins_e84a5c279e1c69c8"
    }
  ],
  "methodology_version": "3.0"
}

3. Run a query

GET /instruments takes a query in the query language. This one asks for passing stablecoin instruments in the low risk band paying at least 6.5%, highest yield first:

yield.total_apy >= 6.5 and safety.band = low and asset_class = stablecoin and screen.verdict = pass sort yield.total_apy desc
  • fields trims each row to the paths you list. id, object and as_of are always included.
  • total is the number of matches; has_more and next_cursor page through them.
  • query echoes the structured query that ran, useful to check how the text was parsed.
Solicitud
curl -G https://yieldsniper.finance/api/v1/instruments \
  -H "Authorization: Bearer $YS_API_KEY" \
  --data-urlencode "q=yield.total_apy >= 6.5 and safety.band = low and asset_class = stablecoin and screen.verdict = pass sort yield.total_apy desc" \
  -d fields=name,venue.protocol,venue.chain,yield.total_apy,liquidity.tvl,safety.score,safety.band \
  -d limit=3
Respuesta200
{
  "object": "list",
  "data": [
    {
      "object": "instrument",
      "id": "ins_f3cbaa85fd31098b",
      "name": "USD1",
      "venue": {
        "protocol": {
          "id": "prt_dolomite",
          "name": "Dolomite"
        },
        "chain": {
          "id": "ethereum",
          "name": "Ethereum"
        }
      },
      "yield": {
        "total_apy": 8.13962
      },
      "liquidity": {
        "tvl": 317526951
      },
      "safety": {
        "score": 80,
        "band": "low"
      },
      "as_of": "2026-10-23T23:45:21.116Z"
    },
    {
      "object": "instrument",
      "id": "ins_2f32db0cbfbb54dd",
      "name": "USDC",
      "venue": {
        "protocol": {
          "id": "prt_pareto-credit",
          "name": "Pareto Credit"
        },
        "chain": {
          "id": "ethereum",
          "name": "Ethereum"
        }
      },
      "yield": {
        "total_apy": 8.06349
      },
      "liquidity": {
        "tvl": 131498789
      },
      "safety": {
        "score": 85,
        "band": "low"
      },
      "as_of": "2026-10-23T23:45:21.116Z"
    },
    {
      "object": "instrument",
      "id": "ins_8da0acac29ee1d21",
      "name": "USDC",
      "venue": {
        "protocol": {
          "id": "prt_kamino-lend",
          "name": "Kamino Lend"
        },
        "chain": {
          "id": "solana",
          "name": "Solana"
        }
      },
      "yield": {
        "total_apy": 7.82297
      },
      "liquidity": {
        "tvl": 52538417
      },
      "safety": {
        "score": 80,
        "band": "low"
      },
      "as_of": "2026-10-23T23:45:21.116Z"
    }
  ],
  "total": 6,
  "has_more": true,
  "next_cursor": "eyJoIjoiODIzOTQ1MjUiLCJ2IjpbNy44MjI5NywiZGFkYTVjZWYwMjFhM2Q4ZSJdfQ",
  "access": "full",
  "as_of": "2026-10-23T23:45:21.116Z",
  "query": {
    "where": [
      {
        "field": "yield.total_apy",
        "op": "gte",
        "value": 6.5
      },
      {
        "field": "safety.band",
        "op": "eq",
        "value": "low"
      },
      {
        "field": "asset_class",
        "op": "eq",
        "value": "stablecoin"
      },
      {
        "field": "screen.verdict",
        "op": "eq",
        "value": "pass"
      }
    ],
    "match": "all",
    "sort": [
      {
        "field": "yield.total_apy",
        "direction": "desc"
      }
    ],
    "fields": [
      "name",
      "venue.protocol",
      "venue.chain",
      "yield.total_apy",
      "liquidity.tvl",
      "safety.score",
      "safety.band"
    ],
    "limit": 3
  }
}

Page through results

Pass next_cursor back as cursor with the same query until has_more is false. Cursors are opaque; don't build them yourself.

Up to 100 rows per page. For a fixed set of instruments, such as a watchlist, send their ids instead: id in (ins_4c29f40abec73e1b, ins_0abd5ec576be07e6).
curl
curl -G https://yieldsniper.finance/api/v1/instruments \
  -H "Authorization: Bearer $YS_API_KEY" \
  --data-urlencode "q=yield.total_apy >= 6.5 and safety.band = low and asset_class = stablecoin and screen.verdict = pass sort yield.total_apy desc" \
  -d limit=3 \
  -d cursor=eyJoIjoiODIzOTQ1MjUiLCJ2IjpbNy44MjI5NywiZGFkYTVjZWYwMjFhM2Q4ZSJdfQ

Go further