Skip to content

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
  • 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, feed or coin), its badge (relayed, history or chainlink), its venue and source, its reading_fee ("0" on pool history and Chainlink markets), its status, mint_open, accrued_burn_sol (the burn share collect_fees would send to the burn vault), and by kind: a stock’s issuer and session, a feed’s Chainlink account and round, a memecoin’s pool and manipulation_cost_sol and, on the $SAGITTA market, the burn. manipulation_cost_sol is 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, and null while the pool is still being measured (see Manipulation cost). A stock or Chainlink market’s row has no such field.
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.

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.

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 its epoch, whether it is the side’s current one, its token, 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) and cost_sol (the basis still held).
  • tickets: its tickets until they are delivered, each with its state (waiting, matured, or settled and waiting for delivery), its amount, its target and, once settled, owed_shares and owed_lamports.
  • sol and credits_sol: the wallet’s SOL and its market wallet’s balance, read live; null when the API could not read the chain, or the wallet has no market wallet.
  • at and slot: 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_sol and equity_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).

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.

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 is listable once its PumpSwap graduation pool exists.
  • Major: Jupiter verifies it and a Chainlink feed on Solana prices it, such as SOL or JUP. Its feed is 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.

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.

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" }.

  • /health;
  • the reference itself, GET /api, and its document, GET /api?spec=1;
  • the link-preview routes /api/og and /api/page when 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>.json uses;
  • 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.

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.