Market data API

02Where to start

• The API itself, whose front page lists the main requests with a working example (the full list is in the agent guide and the OpenAPI below): https://apiops.saturnx.cc
• The guide written for AI agents, which explains the conventions that are easy to get wrong, lists the fields of a token, a pool and a supply answer, and shows an example of every answer: https://apiops.saturnx.cc/llms.txt
• The full technical description (OpenAPI) is https://apiops.saturnx.cc/openapi.json and the market data part alone, small enough to read in one go, is https://apiops.saturnx.cc/openapi/core.json
• This site's guide for agents, which pairs each page with the request behind it: https://ops.saturnx.cc/llms.txt

03Six requests that answer most questions

Two more come up often:

• SOUL in dollars, and a dollar price for every token: https://apiops.saturnx.cc/v1/prices?network=mainnet
• How fresh all of it is: https://apiops.saturnx.cc/v1/health

04Names and symbols

The API is keyed by symbol, but people say names. The search request turns a name, a symbol or part of either into symbols, best match first. Ask it for 'ghostdogs' on mainnet and two tokens come back: GHOSTDOGS, whose name is GHOST, and GDOG, whose name is Ghost DOG. When more than one token fits, the answer carries a note saying so. An agent should then ask which one the person means rather than pick one.

05Supply, and what a maximum of 0 means

• totalSupply is everything minted, minus everything burned.
• circulatingSupply carries the same number: nothing is taken off for team, treasury or pooled tokens. marketCapUsd uses circulatingSupply.
• maxSupply is the cap. On Phantasma a maxSupply of 0 means there is no cap at all, and the owner can keep minting. TAZ, SOUL and KCAL all show 0. supplyCapped says the same in plain terms: false means no cap.
• burnedSupply is everything burned so far. Burned tokens never make room under a cap again: since token semantics V4 (October 2026) the chain checks current plus burned supply against the cap.
• mintable says whether the token's supply rules still allow minting, and mintableRemaining how much still fits under the cap, which burned tokens keep filling. Neither says the owner will mint.
• sealed says the token is sealed, so no contract can ever be attached; hasContract says a token contract is attached now. Both are empty (null) until Saturn has read the token.
• launch.sealedAtBirth says the creation itself sealed the token; launch.needsSeal says a launch fails its rule only for want of a seal.

06Emission and inflation

Saturn records each token's supply every few minutes and keeps the first and last reading of each day. The supply request returns that daily history, and once a token has at least a day of it, the emission over the window: the net change between the first and last reading (new tokens minted minus tokens burned), per day and as a simple yearly percentage of the starting supply. The answer states its own formula.

Supply history is recorded from October 2026 on, when Saturn started keeping it. Nothing earlier is filled in, so for the first weeks every window is short, and until a token has a full day of history its emission is empty and a note says why. It is the change Saturn observed on the chain, not a token's planned inflation schedule: SOUL staking rewards or KCAL generation show up only as the supply they actually added.

07Asking for less

• pair=A,B keeps the pools between two tokens, token=SYM the pools of one token, and active=true leaves out pools that were removed: https://apiops.saturnx.cc/v1/pools?network=mainnet&pair=TAZ,GHOSTDOGS&active=true
• symbols= keeps only the tokens you name: https://apiops.saturnx.cc/v1/tokens?network=mainnet&symbols=TAZ,GHOSTDOGS
• fields= keeps only the fields you name, and limit= caps the number of rows: https://apiops.saturnx.cc/v1/pools?network=mainnet&token=TAZ&fields=id,tokenA,tokenB,tvlUsd&limit=20
• A field name the API does not know is refused, and the error lists the names it does know.

08Limits and freshness

• 300 requests a minute for each address, without a key. The health request is never limited.
• Prices and pool reserves are read from the chain about every 15 seconds. To check they still are, read the health answer, where indexer.stale and indexer.ageMs say whether the chain data is current and soulStale whether the dollar price of SOUL is: https://apiops.saturnx.cc/v1/health
• Every answer except the health check has the same shape: what you asked for under data, and the network and cache times under meta. The health answer is not wrapped, so indexer.stale, indexer.ageMs and soulStale sit at the top level, and an error comes back as error, with a code and a message.
• Each answer also carries a Link header that names the OpenAPI description and the agent guide, so a program holding any answer can find both.

Does Saturn publish inflation figures?

It publishes what it observes: each token's supply day by day from October 2026 on, and the emission worked out from it, per day and per year. It does not publish a token's planned inflation schedule. For SOUL and KCAL that comes from Phantasma itself.

Why does a price read null?

Null means the token has no usable route to SOUL, so it cannot be priced, not that it is worth nothing. Never read a null price as zero.

Why do pools labelled V3 here say v2 in the API?

They are the same pools. The API has always called the older exchange v2; the site calls it V3, after the version its contract reports.