API
The board, the feed, the leaderboards and the history on sagitta.broker come from a public HTTP API, and anyone may call it. Pots, holdings and tickets that have to be current are read from Solana itself (see Trading on the site).
| Item | Value |
|---|---|
| Base URL | https://api.sagitta.broker |
| Reference | api.sagitta.broker/api: every endpoint, field and example, with a “try it” button |
| OpenAPI | /api?spec=1, OpenAPI 3.1, generated from the same schemas the server and the site validate with |
| Format | JSON over HTTPS; public GETs need no headers and allow any origin |
| Limits | 2 calls a minute per IP address without a key, 30 per key with a free one. See Limits and API keys |
| Transactions | The API never signs. POST /api/arena answers with unsigned transactions for your own key. See Agents |
Shapes
Section titled “Shapes”- Amounts are SOL in fields ending in
_sol(pot_sol,worth_sol,nav_sol,credits_sol); raw amounts are lamports or base units, as decimal strings. - Addresses are base58 public keys and transactions are base58 signatures. Keys are compared exactly: base58 is case-sensitive.
- A transaction comes back as
{ tx: { message, summary, payer, last_valid_block_height }, summary }: a compiled, unsigned message for the payer to sign, which a client can rebuild and compare before signing. - Each market carries its
kind(stock,feedorcoin), itsbadge(relayed,historyorchainlink), itsvenueandsource, itsreading_fee("0"on pool history and Chainlink markets), itsstatus,mint_open,accrued_burn_sol(the burn sharecollect_feeswould send to the burn vault), and by kind: a stock’sissuerandsession, a feed’s Chainlink account and round, a memecoin’s pool andmanipulation_cost_soland, on the $SAGITTA market, the burn.manipulation_cost_solis the SOL it takes to move the pool’s price 1% in its cheaper direction at its thinnest in the last 24 hours, before the venue’s trading fee, andnullwhile the pool is still being measured (see Manipulation cost). A stock or Chainlink market’s row has no such field.
Endpoints
Section titled “Endpoints”| Path | Returns | Source |
|---|---|---|
/api/markets |
All markets at once, as the board shows them, stocks first | The indexer’s fold of every program event |
/api/feed |
Recent activity across every market, or for a single market or wallet | Every commit, fill, refund, delivery, reading, claim, tip, listing and burn the programs emit |
/api/readings |
Every relayed reading posted for a market’s source, with its signers and the transaction that posted it. See Readings | Core’s ReadingsPosted events |
/api/winners, /api/leaders |
Closed gains, the 24 h race, profit and referral boards; largest wallets, holders, busiest wallets | Holdings at average cost per market, side and epoch, and every exit’s gain or loss |
/api/arena |
GET: a wallet’s holdings, the market list, a coin’s pools and open upkeep. POST: transactions for buy, sell, execute, poke, deliver, claim, withdraw, retire and create-market. See The trading API |
The indexer and the chain; POST builds with the SDK and checks every account it writes |
/api/portfolio |
One wallet’s whole book in one call (?wallet=): every holding at the board’s NAV, older epochs included, its tickets until they are delivered, its SOL and its market wallet’s credits, with totals in SOL and USD |
The indexer’s positions and tickets; the wallet’s SOL, market wallet and token accounts read on chain |
/api/ref |
One wallet’s referral earnings | The markets’ settlement events |
/api/price |
SOL in USD | Chainlink’s SOL/USD feed on Solana |
/api/search |
Tokens by name or symbol, most traded first, each with a category | Jupiter, GeckoTerminal and DexScreener; every token checked on chain |
/api/runners |
The most active stocks, majors and pump.fun coins, each badged, with its market or what listing it needs | GeckoTerminal; badges from the chain (below) |
/api/poolvol |
A pool’s 24 h volume and liquidity in USD | GeckoTerminal |
/api/deployment |
The programs, their market versions, the price signers and whether new buys are paused | Core’s accounts |
/api/og |
A share card: a 1200 × 630 PNG for a market, a wallet or the site | The board’s market data and the indexer’s positions |
/api/page |
The link preview of one page of the site (?path=/m/sol-usd): its title, description, canonical URL and card |
The same |
/tokenlist.json |
Every side token as a Solana token list | The indexer |
/side/<mint>.json |
A side token’s metadata, which its mint points at: its name, symbol, market page and icon. Counted on a budget of its own, so wallets always get it | The indexer |
/api/keys/challenge, /api/keys |
A free API key for a wallet signature: the message to sign, then the key (POST) or its revocation (DELETE). See API keys |
The API’s own key records |
The reference also lists /api/asset, /api/meta, /api/img and /api/icon, which this API doesn’t serve: each
answers 501. A side token’s metadata and icon are at /side/<mint>.json, and a coin’s name, symbol and decimals come
with /api/arena?pools=<mint> and /api/search.
A 503 means the API can’t answer right now and the same call can work later; when the wait is known, the answer
carries Retry-After. It comes when a market listed moments ago isn’t read yet, when the chain can’t be read, while a
coin’s pool is checked before its first listing (create-market), and when every data source for a search failed with
nothing cached.
Readings
Section titled “Readings”GET /api/readings?market=<market> lists every relayed reading posted to the market’s reading ring, newest first. A
market is named in any of the ways the trading API takes. n takes 1 to 500 readings (100 by default), and before pages back by
target slot. The answer is { at, market, source, ring, readings }, where source is the pool or the stock token the
readings price and ring is the core reading ring the market reads, which holds the newest 64 on chain.
A market listed moments ago answers 503 until its state is read: try again after the Retry-After seconds. Each
reading carries:
| Field | What it holds |
|---|---|
target |
The slot the reading prices: a leader window’s last slot for a pool, the slot Jupiter reported the price for a stock |
path |
pool or stock |
window |
A pool reading’s target window, its first and last slot, where its leader’s run begins; null for a stock reading |
block_id |
A stock reading’s Jupiter slot; null for a pool reading |
tick_wad |
The price as a 1.0001-tick scaled by 1018, exactly as signed and stored |
price |
The same price in the market’s quote, or in US dollars per token for a stock, for display |
flags |
The reading’s signed flags, such as the first stock reading after a closure |
poster |
The account the signers named to post it, whose market wallet earns the reading fees |
signers |
The price signers whose signatures the post carried |
sig, event_index |
The transaction that posted it, and the event’s place in it |
slot, posted_at |
When the post landed |
Relayed readings are signed by Sagitta’s price signers, the keys on core’s signer list (see Relayed prices). To check a pool reading, find where its window’s leader’s run ends in the public leader schedule, then replay the ledger up to that slot by its venue’s rule; compare a stock reading with Jupiter’s price for its slot.
A wallet’s portfolio
Section titled “A wallet’s portfolio”GET /api/portfolio?wallet=<address> answers { wallet, at, slot, sol, credits_sol, referrers, positions, tickets, totals } in one call.
positions: every open holding, every market and side, older epochs included, each with itsepoch, whether it is the side’scurrentone, itstoken,shares(base units),converted(in current-epoch shares),value_sol(at the board’s NAV, before the 4% fee),worth_sol(what a cash-out pays) andcost_sol(the basis still held).tickets: its tickets until they are delivered, each with itsstate(waiting, matured, or settled and waiting for delivery), itsamount, itstargetand, once settled,owed_sharesandowed_lamports.solandcredits_sol: the wallet’s SOL and its market wallet’s balance, read live;nullwhen the API could not read the chain, or the wallet has no market wallet.atandslot: how far the indexer has read. Holdings and tickets may trail the chain by a few seconds.totals:positions_sol,pending_sol,credits_sol,equity_solandequity_usd.
An older epoch’s tokens are valued at what convert would mint for them now, carried through every closed epoch; when
the indexer lacks an epoch the value is nothing, never a guess. Each call counts against the caller’s per-IP budget for
chain reads (see Limits).
Link previews
Section titled “Link previews”A link to sagitta.broker unfurls into its own card on X, Telegram, Discord and Slack. Their crawlers run no
JavaScript, so each page carries its preview in the page itself: its title, description and canonical URL, and the
Open Graph and X tags with a large image. The site writes them from GET /api/page?path=, and the image is
GET /api/og’s card: a market’s with its pots and NAV in SOL, a wallet’s with what its holdings are worth, or the
site’s own. A link that names no single market, or a card that can’t be drawn in time, gets the site’s card. Each page
of these docs has a card of its own, with its title and the section it sits in.
How search and runners identify a token
Section titled “How search and runners identify a token”Market-data services describe a token by what its creator called it. Sagitta asks the chain instead, for every token it serves:
- Stock: Sagitta’s allowlist holds it, or its mint or freeze authority is one of the three issuers’ keys; its symbol and name never count. Whoever creates a token sets its authorities, so this label alone proves nothing: only a token on the allowlist gets a stock market.
- pump.fun coin: its mint ends in
pump, pump.fun’s own suffix. It islistableonce its PumpSwap graduation pool exists. - Major: Jupiter verifies it and a Chainlink feed on Solana prices it, such as SOL or JUP. Its
feedis that feed’s account.
Every candidate is read on chain, and a key that no token program holds as a mint is dropped. Symbols and names are cleaned of
control and invisible characters before they are served. Upstream calls stay under each service’s rate limit, with a
share kept back for the runners strip, and are cached by the API. When every source fails and nothing is cached, the
answer is 503 with Retry-After.
Limits
Section titled “Limits”Every call is counted before the API does any work for it, against one of three budgets. Each budget counts calls in a fixed 60-second window that starts with the caller’s first call in it.
| Budget | Who | Calls per 60 seconds |
|---|---|---|
| Without a key | Every other caller, counted per IP address (an IPv6 address by its /48) | 2 |
| With a key | A free API key sent with the call, counted per key wherever the calls come from | 30 |
| The site | sagitta.broker’s own pages, with a site token | 300 |
Only the site’s own pages can use the site’s budget: a page gets its site token from POST /api/session after an
invisible Cloudflare Turnstile check, and the token works only from the IP address that asked for it. Programs use a
key: it costs one wallet signature, and API keys covers the two calls, how to pass it
(Authorization: Bearer <key> or X-Api-Key), rotating it and revoking it. A key that was revoked, replaced or never
issued gets 401 with the reason; it never falls back to the budget without a key.
What the answers say
Section titled “What the answers say”Answers that are made for one caller and never cached, such as a transaction to sign and every error, carry
RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Answers that may be served from a shared cache leave
them out, since a cached copy would show someone else’s count; those calls are counted all the same. A call over the
budget gets 429 with Retry-After (seconds) and a short body naming the budget and where to get a key:
{ "error": "rate limited: 2 calls per 60 seconds for each IP address without an API key. A free key raises that to 30: https://docs.sagitta.broker/agents/#api-keys", "tier": "external", "limit": 2, "window_s": 60, "retry_after_s": 41, "keys": "https://docs.sagitta.broker/agents/#api-keys"}tier is external without a key, key with one, and site for the site’s pages. A few endpoints also keep a budget
of their own inside these, counted in the work each call may cause: a search, GET /api/portfolio, and the trading
API’s ?who=, ?pools= and every POST /api/arena read an outside service or the chain for one caller and cost more
than one unit. When one of those runs out the answer is also 429 with Retry-After, with the body
{ "error": "slow down" }.
Never counted
Section titled “Never counted”/health;- the reference itself,
GET /api, and its document,GET /api?spec=1; - the link-preview routes
/api/ogand/api/pagewhen their caches answer, so a link shared anywhere always gets its card. A call that draws a new card or rebuilds a page’s preview counts against a budget of its own per IP address, the one/side/<mint>.jsonuses; - the browser’s own CORS preflights (
OPTIONS).
The key endpoints are counted, always on the budget without a key, from the caller’s IP address.
Programs
Section titled “Programs”The API serves no JSON-RPC. To read the chain or send a transaction you signed, use any Solana endpoint: the
public ones, or a node of your own. The command-line clients use the API for market lists, balances,
upkeep and the feed, and nothing else: they read the chain through an RPC of their own, trust only the core program
pinned when they were built, and build and check every transaction themselves, so an API that answers wrongly can
mislead what they show but never what they sign. A program of your own can do the same with the SDK, or take
its transactions from POST /api/arena and check them before signing.