Docs · For builders
Builder program
/api/v1/quote for a trade. It answers with a transaction ready to sign that pays you 30% of Submarine's cut, while your user pays exactly what any trade costs.What you get
| Without a key | With a key | |
|---|---|---|
| /api/v1/quote and /api/v1/builder/ | 30 requests a minute per address | 300 requests a minute per key |
| Usage counts | None | Requests, quotes and transactions per key, per day, for 30 days |
| Your builder code | Pass your wallet address instead | A short name that pays your wallet |
Every other route of the public API stays open to everyone with no key. Keys are free. Manage them on the Developers page.
What you earn
A quote that names your code or address builds the router's buyPartner or sellPartner with you as the partner, kind 2. The router pays you 30% of Submarine's cut of that trade, straight to your wallet, in the same transaction. On Submarine's own curves and pools the cut is 0.4% of the trade, less the trader's rank. On another launchpad's venue it is the router fee there.
- 1,000 ZROBought through your app by wallets without a rank, on Submarine coins
- 4Submarine's 0.4%
- 1.2Yours, 30%
- 2.8The treasury, shared with a referrer when the trader has one
- A builder isn't paid for its own trades. A quote whose trader is the builder comes back as a plain trade and says why.
- A fee-free trader pays no Submarine cut, so their trades pay you nothing, though they still show in your counts.
- What you have earned is on your dashboard, from the router's
Partnerevents, and in/api/v1/partners/:address.
Getting started
- Open Developers and sign in with your wallet. Signing a short text is free and sends no transaction.
- Make an API key. It is shown once, so keep it on your server. A wallet can hold 5 keys at once; revoke one to make another.
- Claim a builder code: 3 to 24 lowercase letters, digits and dashes, not starting or ending with a dash. It pays the wallet that claimed it. Claiming another replaces it.
- Call
/api/v1/quotewith your key in thex-api-keyheader and your code asbuilder. Have your user sign the transaction it returns.
The quote
GET with a query, or POST with the same fields as JSON. It asks the router for the best venue, builds the trade, and checks it against the chain from the trader's address. It never signs or sends anything.
| Field | What it is |
|---|---|
token | The token to buy or sell. Required |
side | buy pays ZRO for the token, sell pays the token for ZRO. Required |
amount | What is paid, in whole units: ZRO for a buy, tokens for a sale, such as 25 or 0.5. Required |
slippageBps | How far below the quote the trade may fill: 10 to 5,000. 100, or 1%, if not given |
trader | The wallet that will sign. With it the answer carries the transaction; without it, a quote only. recipient works too |
builder | Your builder code or wallet address. ref works too |
curl -H "x-api-key: sbk_..." "<Submarine API URL>/api/v1/quote?token=0x...&side=buy&amount=25&trader=0x...&builder=yourcode"What it answers
{
"token": "0x…",
"symbol": "EXM",
"side": "buy",
"venue": { "index": 0, "address": "0x…", "name": "Submarine Launchpad", "routerFeeBps": 0 },
"amountIn": "25000000000000000000",
"amountOut": "…",
"minAmountOut": "…",
"amountInFormatted": "25",
"price": 0.0000021,
"slippageBps": 100,
"tokenFeeBps": 100,
"builder": { "address": "0x…", "kind": 2, "applied": true, "reason": null },
"deadline": 1795000000,
"approvals": [],
"transaction": { "from": "0x…", "to": "<router>", "data": "0x…", "value": "25000000000000000000", "chainId": 1337, "gas": "…" },
"note": null,
"chainId": 1337
}- Amounts are in wei as strings, and again in whole units as the Formatted fields.
- amountOut is the router's quote for a wallet without a rank. A ranked or fee-free trader gets a little more, so a minimum taken from it stays safe.
- tokenFeeBps is the token's whole fee, the 1% base included, for one of Submarine's coins, and null for any other.
- The deadline is 300 seconds after the chain's clock when the quote was made. Send the transaction before then.
- A sale of a token that needs approving first carries the approval in approvals. Send it first, then the sale, whose gas is then null because it couldn't be checked yet. Submarine's own coins need no approval for the router.
MaxWallet() or Slippage(), instead of a transaction that fails.Signing in from code
POST /api/v1/builder/noncewithaddress. It answers with a text to sign, good for five minutes.- Sign that text with
personal_signand sendaddressandsignaturetoPOST /api/v1/builder/login. It answers with a session, good for seven days. - Send the session as
Authorization: Bearer sbs_...to the routes below.
Submarine developers
Sign in as <address, lowercase>
Nonce: <nonce>
Signing costs nothing and sends no transaction.| Route | What it does |
|---|---|
GET /api/v1/builder/me | Your code, your keys with today's requests, the last 30 days of requests, quotes and transactions, and on-chain volume, earnings, trades and wallets |
POST /api/v1/builder/keys | A new key, with an optional label of up to 40 characters. The key is in this answer only |
POST /api/v1/builder/keys/:id/revoke | Revokes a key at once |
POST /api/v1/builder/code | Claims a code for your wallet, replacing any it had |
GET /api/v1/builder/code/:code | Public: which wallet a code pays, so anyone can check |
POST /api/v1/builder/logout | Ends the session |
The key
Send it as the x-api-key header, or ?key= when a header isn't possible. A key is stored only as its hash, so nobody can show it to you again. A key that is wrong or revoked gets a 401 on any route, so leave it off rather than send a bad one.
Limits
| What | Limit |
|---|---|
| /api/v1/quote and /api/v1/builder/ without a key | 30 requests a minute per address |
| Any route with a key | 300 requests a minute per key, under the limits per address on Public API |
| Sign-in texts | 10 requests a minute per address, and at most 4 open per wallet from one address |
| Keys | 5 live keys per wallet |
Every answer on these routes carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset, the Unix second the minute ends. Past the limit the answer is a 429.
Errors
These routes answer an error as { message, error: { code, message } }, so a program can branch on the code.
| Code | Status | Means |
|---|---|---|
bad_request | 400 | A field is missing or out of range, or no builder has that code |
bad_address | 400 | A token or wallet address isn't one |
not_found | 404 | The token isn't indexed |
no_route | 404 | No venue the router lists trades this token for that amount right now |
simulation_failed | 422 | The chain would refuse the trade. The message has the reason |
invalid_key | 401 | The key is wrong or revoked |
signed_out | 401 | No session, or it expired. Sign in again |
bad_signature | 401 | The signature doesn't match the wallet |
too_many_keys | 400 | The wallet already has 5 keys |
code_taken | 409 | Another builder has that code |
rate_limited | 429 | Past the limit. Wait for the minute to end |
not_deployed | 503 | Submarine isn't deployed on this chain |
Building an agent? The MCP server's builder_quote calls this route for you, with your key from INDEXER_API_KEY and your code from SUBMARINE_BUILDER, and with send it checks the transaction is the trade asked for before it signs. Its buy and sell take a partner too. Calling the router yourself works the same: see Trading through a partner.