Testnet on Base Sepolia: 1 ZRO here is 0.0001 test ETH.
Docs · Builder program

Docs · For builders

Builder program

Build a bot, an app or an agent on Submarine and get paid for the trades it brings. Sign in with a wallet, take an API key and a builder code, and ask /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 keyWith a key
/api/v1/quote and /api/v1/builder/30 requests a minute per address300 requests a minute per key
Usage countsNoneRequests, quotes and transactions per key, per day, for 30 days
Your builder codePass your wallet address insteadA 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
Figure 1. The creator, holders and burn get the same as on any trade. The trader pays the same too.
  • 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 Partner events, and in /api/v1/partners/:address.

Getting started

  1. Open Developers and sign in with your wallet. Signing a short text is free and sends no transaction.
  2. 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.
  3. 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.
  4. Call /api/v1/quote with your key in the x-api-key header and your code as builder. 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.

FieldWhat it is
tokenThe token to buy or sell. Required
sidebuy pays ZRO for the token, sell pays the token for ZRO. Required
amountWhat is paid, in whole units: ZRO for a buy, tokens for a sale, such as 25 or 0.5. Required
slippageBpsHow far below the quote the trade may fill: 10 to 5,000. 100, or 1%, if not given
traderThe wallet that will sign. With it the answer carries the transaction; without it, a quote only. recipient works too
builderYour builder code or wallet address. ref works too
bash
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

A buy, trimmed
{
  "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.
The quote is checked against the chain. With a trader given, the trade is simulated before it comes back. If the chain would refuse it, you get a 422 with the reason, such as MaxWallet() or Slippage(), instead of a transaction that fails.

Signing in from code

  1. POST /api/v1/builder/nonce with address. It answers with a text to sign, good for five minutes.
  2. Sign that text with personal_sign and send address and signature to POST /api/v1/builder/login. It answers with a session, good for seven days.
  3. Send the session as Authorization: Bearer sbs_... to the routes below.
The text a wallet signs to sign in
Submarine developers
Sign in as <address, lowercase>
Nonce: <nonce>
Signing costs nothing and sends no transaction.
RouteWhat it does
GET /api/v1/builder/meYour 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/keysA new key, with an optional label of up to 40 characters. The key is in this answer only
POST /api/v1/builder/keys/:id/revokeRevokes a key at once
POST /api/v1/builder/codeClaims a code for your wallet, replacing any it had
GET /api/v1/builder/code/:codePublic: which wallet a code pays, so anyone can check
POST /api/v1/builder/logoutEnds 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

WhatLimit
/api/v1/quote and /api/v1/builder/ without a key30 requests a minute per address
Any route with a key300 requests a minute per key, under the limits per address on Public API
Sign-in texts10 requests a minute per address, and at most 4 open per wallet from one address
Keys5 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.

CodeStatusMeans
bad_request400A field is missing or out of range, or no builder has that code
bad_address400A token or wallet address isn't one
not_found404The token isn't indexed
no_route404No venue the router lists trades this token for that amount right now
simulation_failed422The chain would refuse the trade. The message has the reason
invalid_key401The key is wrong or revoked
signed_out401No session, or it expired. Sign in again
bad_signature401The signature doesn't match the wallet
too_many_keys400The wallet already has 5 keys
code_taken409Another builder has that code
rate_limited429Past the limit. Wait for the minute to end
not_deployed503Submarine 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.