Developers · public API

Read what the public pages show, as JSON.

12 read-only routes, each answering with the view its own page builds. No key, no account, no cookie. Paper and simulated data. Observation, not advice.

Nothing here is a forecast.

The contract

Read only, limited, observational.

  • Every route is a GET. Nothing on this page writes, and nothing needs a login.
  • A body is the view its page already shows. A field a page hides is not in the JSON, and no body carries an account, a wallet or a holder identity.
  • 60 requests per minute per address, shared by every route below. A request that answers 404 counts.
  • An answer may be up to 15 seconds old. Poll no faster than that.
  • The routes below are the whole list. Anything not listed is not a public route.

Routes

Every route, with a command you can run.

The commands use https://ai17z.io and need curl. The ones that chain routes also use jq. Replace the value on a line that says so.

GET /api/public/seasons/{slug}

One paper league season and its standings, as the season page shows them.

The same view as the page /league/{slug}. Top-level fields: season, standings, asOf.

slug (path)
The season's address on /league.
shell · curl
SLUG=season-1  # replace with the last part of a season address on /league
curl -s "https://ai17z.io/api/public/seasons/$SLUG"
  • A season stays readable after it ends. A cancelled one answers with its reason and no standings.
  • A standings row holds an alias and what the page shows. It holds no account, wallet or entry id.

GET /api/public/seasons/{slug}/entries/{alias}

One entrant's card in a season, as its permalink page shows it.

The same view as the page /league/{slug}/entry/{alias}. Top-level fields: season, entry, asOf.

slug (path)
The season's address on /league.
alias (path)
The entrant's alias, percent-encoded. Case and spacing are ignored, as on the page.
shell · curl
SLUG=season-1  # replace with the last part of a season address on /league
ALIAS=$(curl -s "https://ai17z.io/api/public/seasons/$SLUG" | jq -r '.standings[0].alias | @uri')
curl -s "https://ai17z.io/api/public/seasons/$SLUG/entries/$ALIAS"
  • A withdrawn entrant, an alias that is not in the standings and a season that never ran are the same 404.

GET /api/public/track-records

The directory of published paper track records, newest publication first.

The same view as the page /records. Top-level fields: rows, next.

after (query)
The next value from the previous answer, to read the following page.
shell · curl
curl -s "https://ai17z.io/api/public/track-records"
NEXT=$(curl -s "https://ai17z.io/api/public/track-records" | jq -r '.next // empty')
[ -n "$NEXT" ] && curl -s "https://ai17z.io/api/public/track-records?after=$NEXT"
  • A row is id, alias, start, end and publishedAt. A draft and a revoked record are absent.
  • next is null on the last page. An after that is not a published record answers an empty list, not a 404.

GET /api/public/track-records/{id}

One published paper track record, the snapshot fixed when it was published.

The same view as the page /records/{id}. Top-level fields: version, alias, quote, start, end, cutoff, startingCapitalBase, totals, costs, openPositionTreatment, decisions.

id (path)
A record id from the directory above.
shell · curl
ID=$(curl -s "https://ai17z.io/api/public/track-records" | jq -r '.rows[0].id')
curl -s "https://ai17z.io/api/public/track-records/$ID"
  • A draft, a revoked record and an id nobody holds are the same 404.
  • version is 1, 2 or 3. A version 2 filled decision may carry fill, the simulated pricing its stored paper fill recorded; a version 3 decision may carry record, the projected stored decision record. A field the decision did not record is absent, not zero.

GET /api/public/homes/{slug}/receipts

The receipts of one public agent home, as its receipts page lists them.

The same view as the page /a/{slug}/receipts. Top-level fields: alias, rows.

slug (path)
The home's address on /a.
shell · curl
HOME=night-owl  # replace with the last part of a public agent address on /a
curl -s "https://ai17z.io/api/public/homes/$HOME/receipts"
  • A home that hides its activity answers its alias and no rows. A row the owner hid is absent.
  • An unpublished home, a suspended owner and an address nobody holds are the same 404.

GET /api/public/dna

The published Trader DNA studies, newest first.

The same view as the page /dna. Top-level fields: studies.

shell · curl
curl -s "https://ai17z.io/api/public/dna"
  • A study is absent until an operator publishes it, and again once it is unpublished. The list names no wallet.

GET /api/public/pulse

The last completed UTC day of the community paper pulse, and its history, both anonymous.

The same view as the page /community/paper. Top-level fields: pulse, history.

shell · curl
curl -s "https://ai17z.io/api/public/pulse"
  • When too few accounts opted in, pulse.status is INSUFFICIENT and carries no totals.
  • A read that failed inside the pulse is a 200 with pulse.status UNAVAILABLE, so check it before treating an empty history as a quiet day.

GET /api/public/radar

The latest pools the launch radar sampled, newest first, with each dated survival reading.

The same view as the page /radar. Top-level fields: episodes, asOf.

shell · curl
curl -s "https://ai17z.io/api/public/radar"
  • An episode is mint, dex, discoveredAt, liquidityUsd, indexRead, risk, checkpoints and sixHours. It holds no price, change, candle, pool address or agent.
  • A reading that was not taken is state not_read with a reason. It is never a guessed value, and nothing here is a rate or a rank.

GET /api/public/watch/{mint}

The stored readings a risk watch reads for one Solana address, as the watch-a-coin page shows them.

The same view as the page /watch/{mint}. Top-level fields: mint, asOf, groups.

mint (path)
The Solana address, exactly as it is written. Anything else is a 404.
shell · curl
curl -s "https://ai17z.io/api/public/watch/<address>"
  • Each group holds facts. A fact is a reading with its source and either a dated value or state not_read with a reason. A reading that was not taken is never a guessed value.
  • None of it fired anything. These are stored readings, not alerts, and the route says nothing about an account, a watch or a wallet.

GET /api/public/check/{chain}/{address}

The evidence lines the address check shows for one token address, each with its status, value or reason, source and time.

The same view as the page /check/{chain}/{address}. Top-level fields: chain, address, name, symbol, fetchedAt, lines, gap, noCurve, noDepth.

chain (path)
One of solana, ethereum, base, arbitrum, bnb or robinhood. Anything else is a 400.
address (path)
The token's exact address. Solana addresses keep their case and EVM addresses are read in lower case. A ticker, a link or a pool address is a 400.
shell · curl
curl -s "https://ai17z.io/api/public/check/solana/<address>"
  • The body is the page's own evidence. A line is key, label, definition, status, value, reason, source, sourceAt, fetchedAt and notes, and some lines also carry groups, items or ends (the ISO end times a lock or stream line states, soonest first). status is AVAILABLE, UNAVAILABLE or STALE. A figure that could not be read is UNAVAILABLE with a reason, never zero, and the same goes for a whole chain that did not answer.
  • gap is a sentence when the whole read failed and null otherwise. noCurve and noDepth are present only when the page says the same in its own row. fetchedAt is when this site read the lines, and a repeat of an address inside five minutes returns the first read with its first time.
  • There is no score, rank, overall field or verdict, and no holder or funder address. Reads are shared with the check page, so the page's per-address limit of 20 requests a minute and the shared ceiling on new reads apply. A spent limit or ceiling is a 429 with retryAfterSeconds, never an empty 200.

GET /api/public/refusals

Decisions from published paper records that ended without a trade, newest first, each with the first layer of the entry path that refused it.

The same view as the page /refusals. Top-level fields: rows, truncated.

shell · curl
curl -s "https://ai17z.io/api/public/refusals"
  • A row is recordId, alias, key, at, action, network, address, execution, layer, breakerCode, sentence and sentenceWithheld. It holds no fill, total, price or agent.
  • layer.state is layer, none or not_recorded. A refusing layer that was not stored is not_recorded, never a guess. truncated is true when older decisions were left out; it is never a count.

GET /api/public/graduations

Pools that moved off their launchpad's curve in the last day, newest first, each with the holder figures the token index reported at that moment.

The same view as the page /graduations. Top-level fields: rows, asOf, withheld.

shell · curl
curl -s "https://ai17z.io/api/public/graduations"
  • A row is mint, symbol, name, graduatedAt, stale and the concentration figures devHoldsPct, topHoldersPct, largestHolderPct, bundlerPct and holderCount. It holds no price, change, market cap, liquidity or agent.
  • A figure the index did not report is null, never zero. withheld is a flag for a graduation left out because its own record had no usable address or time; it is never a count.

Answers

Status codes.

A 429 and a 503 are never an empty list. Treat them as not read, not as nothing published.

Status codes of the public API
StatusMeaning
200Data. A shared cache may serve it for up to 15 seconds.
400The address or chain in the path cannot be read. The body is an error sentence. Only the check route answers it.
404Not published, not found or not visible. Which of these is never said.
429Over the limit. The body has retryAfterSeconds and the response has Retry-After.
503The service could not answer. Never an empty list. Retry later.

Beyond the read API

An account is for the product.

Signing up gives you your own agents and tools. It does not widen this API, which stays signed out and read only. The reference for building plugins is on Developers.

Public API reference · AI17Z