Docs · For builders
Public API
The basics
Base URL
See below
The same host the site uses
Auth
None
Every read is public. A key is optional
Live data
SSE
One stream instead of polling
Described in
OpenAPI 3.1
/api/v1/openapi.json
<Submarine API URL>The API's address is filled in at launch, once Submarine is deployed on Zero.
curl "<Submarine API URL>/api/v1/tokens?sort=volume&limit=2"{
"tokens": [
{
"address": "0x…",
"name": "Example",
"symbol": "EXM",
"source": "terminal",
"price": 0.0000075,
"market_cap": 7500,
"raised": 2000.0,
"progress": 0.333,
"graduated": false,
"holders": 41,
"volume_24h": 4960,
"change_24h": 0.18,
…
}
]
}Addresses can be sent in any case and come back lowercased. A route that takes a list of addresses reads at most 200 of them. A missing token answers 404, a malformed address 400.
GET /api/v1/openapi.json describes every route in OpenAPI 3.1, open to any origin. Within v1, fields are only ever added, never renamed or removed.
A token card
Every list of tokens uses the same shape, so a card built for one route works for all of them.
| Field | Type | What it is |
|---|---|---|
address, name, symbol, uri | string | The token. uri is its metadata link, see /meta |
source | string | terminal for Submarine's own launchpad, external for anything else found on the chain |
launchpad | string | null | Which connected launchpad, for an external token |
creator, created_at, block | Who made it and when | |
price | number | ZRO per whole token, at the last trade |
market_cap | number | price × total_supply, in ZRO |
raised, progress | number | ZRO in the curve, and raised over the target (6,000 ZRO here), from 0 to 1 |
graduated, has_pool, tradable | boolean | Moved to a pool; has a Submarine pool, which only graduation opens; can be traded from Submarine |
fee_bps, dev_fee_bps, holders_bps, burn_bps, anti_snipe | The token's terms. fee_bps is its whole fee now, the 1% base included, which its creator may have lowered; dev_fee_bps is the part above the base. fee_route is holders when holders_bps is above 0, else creator | |
max_wallet, max_wallet_until, max_wallet_active | Its max wallet in whole tokens and when it ends, null for none, and whether it still holds now | |
holders, volume_24h, trades_24h, change_24h | number | Holders now, and the last 24 hours. change_24h is a fraction: 0.18 is +18% |
links | object | null | website, twitter, telegram, discord |
Tokens
GET/api/v1/tokens
?sort=new|volume|progress|mcap|active &stage=curve|graduating|graduated|external &launchpad=terminal,<id>,… &window=1h|6h|1d|7d &spark=1 &q= &creator= &addresses=a,b &limit=50 (max 500) &offset=
Lists tokens. graduating is a curve token that has raised at least a quarter of the target. launchpad takes several ids, comma separated; terminal is Submarine's own. window moves what volume_24h, trades_24h and change_24h cover, a day if not given; the names stay the same. spark=1 adds spark, closing prices over the same window, oldest first: 5 minute steps over 1h, 15 minutes over 6h, an hour over 1d, 4 hours over 7d.
GET/api/v1/tokens/:address
One token card, plus change_5m, change_1h, change_6h, buys_24h, sells_24h, buy_volume_24h, sell_volume_24h, what its fee has paid (creator_earned, holders_earned, burned_zro, burned_tokens and their sum earner_fees), and fee_changes: every time its creator lowered the fee, on the launchpad and then on the pool.
GET/api/v1/tokens/:address/trades
?limit=50 (max 1000) &trader=<address> | &traders=a,b
Latest trades, newest first. Each has tx_hash, ts, trader, is_buy, zro, amount, price and venue.
GET/api/v1/tokens/:address/candles
?interval=1|5|60|300|900|3600|14400|86400 &before=<unix> &limit=300 (max 4000)
Candles t, o, h, l, c, v, oldest first. interval is in seconds, 60 if not given. Use before to page back through history.
GET/api/v1/tokens/:address/holders
?limit=20
Holders and amounts, biggest first.
GET/api/v1/tokens/:address/holders/pnl
?limit=100 (max 200)
Holders with their labels, what each spent and got back, buys, sales, first buy, last trade, and profit by average cost: avg_entry, value, realized, unrealized, pnl and pnl_pct.
GET/api/v1/tokens/:address/bubbles
?limit=60 (max 150)
The bubble map: holders sized by share with their value, the transfers between them, the clusters they form, numbered, and clustered_share, how much of the supply sits in linked wallets.
GET/api/v1/tokens/:address/viewers
?id=<page id>
How many pages have this token open. A page that sends an id counts for 50 seconds; the site checks in every 20.
One token in depth
GET/api/v1/tokens/:address/holders/labelled
?limit=100 (max 200)
Holders with share, profit and labels: dev, insider, sniper, bundle, whale, top10, fresh, smart, bot, cluster. The glossary says what each means.
GET/api/v1/tokens/:address/traders
?limit=50 (max 200)
Everyone who traded it, with what they put in, took out and still hold.
GET/api/v1/tokens/:address/first-buyers
The first 70 buyers in order, and what each has done since.
GET/api/v1/tokens/:address/clusters
The holders map: wallets, the transfers between them, and linked groups.
GET/api/v1/tokens/:address/risk
Shares held by the dev, the top 10, snipers, bundles and insiders, smart holders, and ath, the highest price.
GET/api/v1/tokens/:address/security
For our tokens: no owner, not mintable, pool liquidity locked for good once graduated (lp_burned). For others: the owner() if any, and whether it is renounced.
GET/api/v1/tokens/:address/dev
The creator: every buy, sale, transfer and burn, what they hold and sold, wallets they sent coins to, how many bought in the launch block, and their other launches.
GET/api/v1/tokens/:address/orderbook
Up to 500 limit orders on it with what was resting at each moment, for the heatmap. Orders waiting on an event have no level and are left out.
Discovery
GET/api/v1/pulse/new | near | migrated
?min_age &max_age (s) &min_mcap &max_mcap &min_volume (ZRO) &min_holders &max_holders &min_progress &max_progress &max_dev &max_top10 &max_snipers &max_bundles &max_insiders (0 to 1) &min_smart &socials=1 &launchpad= &limit=60 (max 150)
Pulse's three columns: new launches, those 40% or more along their curve, and those that reached a pool. Every filter is optional. Each card carries its risk figures.
GET/api/v1/trending
?window=1m|5m|1h|6h|24h &sort=volume|change|trades
Up to 50 tokens moving in the window, with window_volume, window_trades, window_buyers and window_change.
GET/api/v1/radar
?tokens=a,b,c (up to 10)
Wallets early on several of the given tokens. With none given, today's five busiest.
GET/api/v1/search
?q=
Up to 8 tokens by name, ticker or address, and up to 5 wallets by address or its first four characters after 0x.
GET/api/v1/launchpads
Every launchpad Submarine works with: its own first, then one per file in launchpads/.
GET/api/v1/launchpads/stats
Tokens, graduations and 24 hour volume per launchpad, and contracts minting tokens that nobody has connected yet.
Wallets and orders
GET/api/v1/wallet/:address
Holdings with cost, the latest 50 trades, totals, tokens it launched, up to 100 closed positions, its stats, how many orders it has open, and tokens that pay it holder rewards.
GET/api/v1/wallet/:address/trades
?limit=5000 (max 20000)
Its whole history in a compact form: ts, token, is_buy, zro, amount.
GET/api/v1/wallet/:address/pnl
Profit on every token it traded or holds, by average cost, with realized, unrealized and pnl each, and the totals: value, spent, received, realized, unrealized, pnl, positions, open, wins, losses, win_rate and trades.
GET/api/v1/wallet/:address/record
?days=7|30
Profit, win rate, holding time, buy sizes and flags such as selling within 10 seconds of buying.
GET/api/v1/wallets
?addresses=a,b
Stats for many wallets in one call.
GET/api/v1/inflow
?wallets=a,b &window=1m|5m|1h|6h|24h
What a list of wallets put into each token over the window.
GET/api/v1/leaderboard
?kind=traders|creators|points &window=1d|7d|30d|all (7d if not given) &limit=100 (max 200) &address=
The leaderboard. traders: realised profit from sales by average cost, volume, trades, sells, wins and the best coin. creators: the creator's part of fees in the window, launches, graduated, others' volume and the best coin, plus removed and dump_share. points: all time. address adds that wallet's row as me. Worked out at most once a minute. See Leaderboard and portfolios.
GET/api/v1/leaderboard without kind
?window=24h|7d (all time if not given) &limit=50
The older board the token list's Leaders tab reads: traders by profit marked to the current price, with volume, trades, tokens and wins.
GET/api/v1/orders
?owner= &token= &open=1|0
Up to 200 orders with kind, limit_price, size_zro, left_zro, filled_share and status: open, partial, filled, cancelled, expired, or unfilled_expired (past its time and still holding funds).
GET/api/v1/orders/:id/fills
Each fill of an order: tx_hash, ts, zro, tokens and the keeper that made it.
GET/api/v1/vault
The copy vault as a whole: paused, guardian, fee_bps for follows made now, and fees_taken and fees_count, the copy fees paid so far.
GET/api/v1/vault/:address
A follower's copy vault: who they follow, with what rules and the fee_bps each follow was made under, their exits, positions, history, copy_fees_paid, the vault as above, and a balance estimate from events. The contract's balanceOf is the real figure.
GET/api/v1/staking/:wallet
A wallet's stake, what it holds of the token, what it can claim now, what it has claimed, fee_free, and its stakes, unstakes and claims.
GET/api/v1/referrals/:address
referrer, referred, active_traders, from_referrals, cashback, earned, claimed and unclaimed.
GET/api/v1/points/rules
The points rules: perZroTraded, perZroOnYourCoins, perZroElsewhere and minVolume, in ZRO.
GET/api/v1/points/leaders
?limit=50 (max 200)
Wallets whose points count, by points: total, wallets, and leaders with place, points, traded, onCoins and elsewhere.
GET/api/v1/points/:address
One address: points, traded, onCoins, elsewhere, live (whether it counts yet), place, share of all points, and the rules.
Calls, clans and partners
GET/api/v1/calls
?tab=latest|bought|following|mine|top &window=1d|7d|30d|all &callers=a,b (following) &caller= &token= &limit=50 (max 100) &offset=
Calls with their figures: market cap at the call, now and at its peak, the multiples, buyers and ZRO through the link, what the caller earned, whether they sold, ends_at, live and share_path. tab=top answers the callers' board.
GET/api/v1/calls/top
?window=30d &limit=100 (max 100) &address=
Callers by average peak multiple, then the share that went 2x, then how many calls, with each caller's best call. address adds that caller's row as me.
GET/api/v1/calls/:id
One call.
POST/api/v1/calls
Makes a call. Body: address, token, note (200 characters at most), time and signature. One live call per coin per caller, one call every 20 seconds. The text to sign is on Calls and clans.
GET/api/v1/clans
?window=7d|30d|all &sort=pnl|volume|holdings|members|volume_24h &q= &limit=100 (max 200)
Clans ranked by their members' figures, with member_cap.
GET/api/v1/clans/:tag
?window=7d
One clan: its row and rank, members with their own figures, and the requests waiting.
GET/api/v1/clans/of/:address
The clan a wallet is in or has asked to join, or null.
POST/api/v1/clans
A signed clan change. Body: action (create, edit, join, cancel, approve, reject, kick or leave), address, tag, member, name, image, time and signature.
GET/api/v1/partners
?kind=call|builder &limit=50 (max 200)
Everyone the router has paid as a partner, most first, with the total.
GET/api/v1/partners/:address
What the router has paid one wallet as a caller and as a builder: earned, trades, wallets, tokens and volume for each, and the latest 50 payments.
Market and protocol
GET/api/v1/market/stats
Tokens, graduations, external tokens, and 24 hour volume, trades and traders across the chain.
GET/api/v1/market/trades
?traders=a,b &limit=30
The latest trades across every token, with each token's name and the trader's holding.
GET/api/v1/protocol/stats
?range=24h|7d|30d|all
Submarine's own figures: totals, this window against the one before, a series to chart, venues, top tokens and creators, limit orders, and the treasury. Shared for 10 seconds between everyone asking.
GET/api/v1/stats/more
?range=24h|7d|30d|all
The rest of the Stats page: active, new and returning traders with a series, revenue by source and where every fee went (treasury, referrers, rebates, creators, holders, burn), each launchpad's share of volume, and a live feed of trades, launches and graduations.
GET/api/v1/buyback
The treasury and the Submarine token it buys back: the token, the treasury's balance, spent, burned and burned_share, rounds_count, last_at, next_at, max_round, and the latest 100 rounds.
GET/api/v1/staking
Staking: the token and its price, threshold, total_staked and staked_share, stakers, reward_rate_per_day, stream_ends, funded_week, total_funded, total_paid, from_treasury, apr at the current rate, and the latest 100 fundings.
GET/api/v1/airdrop
The airdrop: its share of the Submarine token's supply, the token, the amount and its value now, and the points it is split by.
GET/api/v1/status
Every service checked once a minute: overall, each one's state, uptimes over 24 hours, 7 and 90 days, a bar per day, and the latest 50 incidents. See Status.
GET/api/v1/zro-price
ZRO in US dollars, for display only. From Binance, or CoinGecko if that fails, refreshed every minute. usd is null when neither answered.
GET/health
chainId, the block the indexer has reached against the chain head, and the deployment: every contract address.
Quotes and the builder program
GET/api/v1/quote
?token= &side=buy|sell &amount= &slippageBps=100 &trader= &builder=
The best venue's quote, and with trader a transaction ready to sign, checked against the chain. With builder, it is buyPartner or sellPartner and pays the builder 30% of Submarine's cut. POST takes the same fields as JSON.
POST/api/v1/builder/nonce · /login · /logout · /keys · /keys/:id/revoke · /code
Sign in with a wallet, make and revoke API keys, claim a builder code.
GET/api/v1/builder/me · /api/v1/builder/code/:code
Your dashboard, and which wallet a code pays.
Everything about these, with the fields of the answer and the error codes, is on Builder program.
Profiles and metadata
GET/api/v1/profiles
?a=addr1,addr2 (up to 100)
Public names and pictures, keyed by address.
POST/api/v1/profile
Sets a wallet's own name and picture. Body: address, name, image (a data URL, or null to remove), time, and signature over the message below. One change every 15 seconds.
POST/api/v1/meta
Saves a token's picture, description and links before launch, and answers with the uri to launch it with. Body: image (PNG, JPEG, WebP or GIF data URL, 2 MB and 4096 by 4096 pixels at most) or imageUrl, description (600 characters at most), website, twitter, telegram, discord.
GET/api/v1/meta/:hash
The saved metadata. It never changes, so it can be cached for good.
GET/api/v1/images/:file
A saved picture, named by the hash of its bytes.
Submarine profile
Wallet: <address, lowercase>
Name: <name, or (none)>
Picture: <sha256 of the image bytes, or same, or none>
Time: <unix seconds, within 10 minutes of now>A name is 2 to 24 letters, digits, spaces, dots, dashes or underscores, and can't look like an address.
The live stream
GET /api/v1/stream is a stream of server-sent events. Open it once and every change arrives as it lands, so there is no need to ask again and again. A comment line keeps it open every 15 seconds.
| Event | Data |
|---|---|
trade | tx, idx, block, ts, token, trader, isBuy, zro, amount, price, venue |
launch | address, name, symbol, creator, ts. external and launchpad for tokens from elsewhere |
graduated | token, ts |
order | id of an order that was placed, filled, closed or moved |
vault | follower, kind, token, for anything in the copy vault |
dev | token, kind, when a creator transfers or burns |
profile | address, name, image, when a profile changes |
fee | token, fee_bps, when a creator lowers a token's fee |
partner | token, trader, partner, kind (1 call, 2 builder), amount, when the router pays a partner |
staking | who, kind (stake, unstake, claim, fund), for anything in staking |
call | id, caller, token, when a call is made |
clan | tag, action, when a clan changes |
const es = new EventSource('<Submarine API URL>/api/v1/stream');
es.addEventListener('trade', (e) => {
const t = JSON.parse(e.data);
console.log(t.token, t.isBuy ? 'buy' : 'sell', t.zro);
});Limits
| What | Limit |
|---|---|
| Routes under /api/v1/, at the front door | 30 requests a second per address, with bursts up to 120 |
| Every route, in the API | 1,200 requests a minute per address, with up to 600 at once. An IPv6 address counts by its /64 |
| Heavy reads | 300 a minute per address, with up to 150 at once: Pulse, the holder, trader and cluster analysis of a token, the leaderboard, trending, radar, stats, calls, clans, staking, buyback, status, a wallet's pages, search and quotes. Shared answers kept a few seconds don't count |
| /api/v1/quote and /api/v1/builder/ | 30 a minute per address without a key, 300 a minute per key |
| POST /api/v1/meta | 20 a minute per address, bursts of 6, and 10 MB or 24 new files an hour |
| The live stream | 12 open streams per address |
| Past a limit | HTTP 429 with retry-after. Wait and try again |
quoteBuy and quoteSell are what a trade will really get. See Launch and trade from code.Building an agent? The MCP server wraps the most useful routes and live quotes as tools.
Where this comes from
indexer/src/api.ts, traderRoutes.ts, extraRoutes.ts, leaderboard.ts, calls.ts, clans.ts, staking.ts, status.ts, builders.ts and profiles.ts. The limits per address are in guard.ts, and the front door's in deploy/server/setup.sh.