Testnet on Base Sepolia: 1 ZRO here is 0.0001 test ETH.
Docs · MCP server

Docs · For builders

MCP server

A Model Context Protocol server in mcp/ that gives an AI agent all of Submarine: market data, live quotes, buying and selling, launching, orders, copy trading, staking, claims, calls and builder quotes. Without a key it reads, and its write tools hand back unsigned transactions. With a key it signs locally and sends, inside a spending limit you set.

Amounts go in and out as decimal strings in whole units, such as "12.5" ZRO or "250000" tokens. Every answer is JSON as text.

Tools that read

ToolArgumentsWhat it does
statusnoneThe chain and block, the indexer's health, every contract, the router's venues, the launch fee, the order fees, the copy vault's fee and pause, the signing wallet, its ZRO and whether it is fee-free, and how much of the spend limit is left
get_market_statsrange: 24h, 7d, 30d or allThe whole market, and Submarine's own figures over the range
list_tokenssort, stage, launchpad, creator, limit, offsetTokens from every launchpad. sort: new, volume, progress, mcap, active. stage: curve, graduating, graduated, external
search_tokensqTokens by name, symbol or address, and wallets by address
get_tokenaddress, walletOne token with its price, market cap, progress, holders, changes, flow and what its fee has paid, and for Submarine coins the curve and max wallet read from the chain. With wallet, its balance and unclaimed holder rewards
get_token_tradesaddress, trader, limitRecent trades of a token, of a trader, or of the whole market
get_trendingwindow, sort, limitTokens moving most over 1m, 5m, 1h, 6h or 24h, with their risk flags
get_candlesaddress, interval, limit, beforePrice candles in ZRO per token
get_holdersaddress, limit, labelledHolders, biggest first, and with labelled who each is
get_dev_walletsaddressThe creator: every buy, sale and transfer, what they hold, where they sent coins, and their other launches
get_riskaddressCreator and top 10 shares, snipers, bundles, clusters, the all-time high, and what the chain says about owner, mint and LP
get_walletaddressHoldings with cost, recent trades, totals, closed positions, launches and open orders, and its ZRO and router rank
get_wallet_statsaddress, days: 7 or 30Its record as a trader
get_leaderboardwindow: 24h, 7d or all, limitTraders by profit, open positions marked to the current price
get_pointsaddress, limitOne wallet's points and place, or the leaders, with the rules
get_buybacksnoneThe treasury's buyback and burn of the Submarine token, round by round
get_stakingwalletStaking: the token, total staked, the ZRO streaming per day, an APR, the threshold and every funding. For a wallet, its stake, holding, ZRO to claim and whether it is fee-free
list_launchpadsnoneEvery launchpad Submarine lists, with tokens, graduations and 24 hour volume
list_ordersowner, token, open, idOrders from the indexer, or one order read from the chain with its fills
get_copy_vaultfollower, leaderA follower's balance, exits and positions from the chain, who they follow, the vault's fees and pause, and history. With leader, that follow's rules and its copy fee
quote_buyaddress, zro, slippage_bps, walletTokens out at the best venue, read from the router. For a Submarine coin on its curve, what a buy by wallet pays this moment, anti-snipe, rank and fee-free status included
quote_selladdress, tokens, slippage_bpsZRO out at the best venue

Trading and launching

ToolArgumentsWhat it does
buytoken, amount_zro, slippage_bps, partner, partner_kindBuys through the router at the best venue, with a fresh quote less the slippage as the minimum. Refuses up front a buy that would pass a coin's max wallet. With partner, it is buyPartner, and the partner gets 30% of Submarine's cut at no cost to the trader. partner_kind is 1 for a call, 2 for a builder, the default
selltoken, amount_tokens or percent, slippage_bps, partner, partner_kindSells through the router. Adds an approval first for a coin that needs one
launch_tokenname, symbol, description, image_url, website, twitter, telegram, discord, supply, creator_fee_pct, holders_share_pct, burn_share_pct, anti_snipe, first_buy_zro, max_wallet_pct, max_wallet_minutesSaves the details on the indexer and launches. anti_snipe is on unless you turn it off. A max wallet is 1 to 5% for 15 to 1,440 minutes, and the first buy must fit under it. Returns the token address
lower_creator_feetoken, creator_fee_pctLowers your own fee on a coin you launched. It must be below today's, and can never go back up

Claims and staking

ToolArgumentsWhat it does
claim_creator_feesnoneYour creator share from every coin you launched, curve and pool alike
claim_holder_rewardstokenThe ZRO a holder token owes you. Works after selling too
claim_referral_earningsnoneWhat referrals earned you, and your own cashback
stakeamount_tokens or percentStakes the Submarine token, with an approval first when needed
unstakeamount_tokens or percentTakes stake out. Any amount, any time
claim_staking_rewardsnoneThe ZRO your stake has earned

Calls, clans and partners

ToolArgumentsWhat it does
get_callstab, window, caller, token, id, limitPublic calls with their figures. tab: latest, bought, mine (one caller, the signer by default) or top, the callers' board. window: 1d, 7d (the default), 30d or all. With id, one call. See Calls and clans
get_clanstag, address, window, sort, search, limitClans ranked by profit, volume, 24 hour volume, holdings or members; one clan by tag with its members and requests; or the clan of one wallet
get_partner_earningsaddress, kind, limitWhat the router has paid a wallet as a caller and as a builder, with recent payments. Without address, everyone paid as a partner, most first, optionally only call or builder
post_calltoken, noteCalls a coin in public. The server signs the call's text with personal_sign, which is free and off chain, and posts it, and answers with the share link. Without a key for from, it returns the exact text to sign and the body to post. dry_run signs without posting

The builder quote

ToolArgumentsWhat it does
builder_quotetoken, side, amount, trader, builder, slippage_bps, sendAsks the API's /api/v1/quote for the best venue, the minimum out and a ready-to-sign trade for trader, the signer by default, paying the builder 30% of Submarine's cut. amount is ZRO for a buy and tokens for a sale. builder is a code or an address, SUBMARINE_BUILDER by default. Without send it returns the quote only

With send: true and a key, the server doesn't simply sign what the API handed back. It decodes every transaction first and sends nothing unless each one is what was asked for:

  • An approval must be the token's approve, for the router from the deployment, for exactly the amount being sold, with no ZRO attached.
  • The trade must go to the router, from the trader, and be buy or buyPartner for a buy, sell or sellPartner for a sale.
  • It must trade this token, for this trader, and a buy must send exactly the amount of ZRO asked for; a sale must sell exactly the amount and send no ZRO.

Anything else is refused with nothing sent. What passes is then simulated, signed and sent like buy and sell, counted against SUBMARINE_MAX_SPEND, and the answer says what arrived and what the builder was paid. See Builder program.

Orders and copy trading

ToolArgumentsWhat it does
place_limittoken, side, amount, price_zro or market_cap_zro or move_pct, kind, expiry_hoursA limit order on the chain. kind on_graduation buys a Submarine coin when it moves to its pool. Expires after 720 hours unless you say otherwise; 0 never
place_exittoken, kind, its level, amount_tokens or percent, more_legs, expiry_hoursTake profit, stop loss, trailing stop, sell on graduation or sell when the creator sells, with up to four more legs on the same tokens
place_dcatoken, total_zro, slices, interval_minutes, max_price_zro or max_market_cap_zro, expiry_hoursA buy split into 2 to 100 slices, never above the price cap: three times today's price unless you set one
cancel_orderidCancels an order and returns its escrow. One leg cancels its whole group
copy_deposit / copy_withdrawamount_zro, or allZRO into or out of the copy vault
copy_followleader, per_trade_zro, per_token_zro, per_day_zro, size_pct, slippage_pct, chase_pct, min_sell_pct, copy_sells, buy_once, max_age_secondsCopies a leader on these rules. Defaults: 10, 50 and 100 ZRO, 100% size, 10% slippage, 15% chase, 50% least sale. Fixes the copy fee for this follow as it stands
copy_unfollowleaderStops copying. Positions stay
copy_set_exittake_profit_pct, stop_loss_pct, slippage_pctTake profit and stop loss over every position in the vault

Each order pays whoever fills it a run fee, 0.04 ZRO per whole order unless the order contract says otherwise, and a buy order must be more than twice that. Each copy, copied sale or exit pays its runner 1% of it, 0.01 to 0.1 ZRO, and a copy under 0.1 ZRO doesn't run. See Limit orders and Copy trading.

Agent vault tools

With AGENT_VAULT and AGENT_KEY set, three more tools trade only inside that agent vault, under its owner's limits:

ToolArgumentsWhat it does
vault_statusnoneThe vault's ZRO, the owner's limits, what is left to spend today, and its holdings
vault_buyaddress, zro, slippage (percent)Buys with the vault's ZRO, minimum from a fresh quote. By default half the vault's slippage limit
vault_selladdress, tokens or "all", slippageSells the vault's tokens. The ZRO goes back to the vault

Install and settings

Windows PowerShell, from the repository
npm.cmd install
npm.cmd run build --workspace=mcp
macOS or Linux
npm install
npm run build --workspace=mcp
VariableDefaultWhat
INDEXER_URLhttp://localhost:3011The API to read from. Set it to the public one below to skip running an indexer. TERMINAL_API, its old name, still works
RPC_URLhttp://127.0.0.1:8546The node quotes are read from and trades sent to. Set it to Zero's, https://testnet.zero.layerzero.network
SUBMARINE_KEYnoneA private key to sign with. It stays in this process. Without it, write tools need from and return unsigned transactions
SUBMARINE_MAX_SPEND100The most ZRO this server may commit, in total, for as long as it runs
SUBMARINE_SLIPPAGE_BPS100Slippage for trades that don't set their own, 0 to 5,000
SUBMARINE_DEPLOYMENTnoneA deployment file to read instead of the repository's contracts/deployments/<chain id>.json
EXPLORER_URLnoneAn explorer, for a link to each transaction sent
AGENT_VAULT, AGENT_KEYnoneAn agent vault and its agent key, which turn on the three vault tools
INDEXER_API_KEYnoneA builder API key, sent as x-api-key on every request to the API: 300 requests a minute on the quote instead of 30, and its counts on your dashboard
SUBMARINE_BUILDERnoneYour builder code or address, which builder_quote uses unless a call gives its own

The server finds Submarine's contracts in the deployment file for the RPC's chain, or else from the indexer's /health, and reads them again on every call, so it follows a redeploy without a restart. The public API is at <Submarine API URL>. That address and Zero's RPC are filled in at launch.

Connect a client

It talks over standard input and output. In a client that takes a JSON config, such as Claude Desktop:

json
{
  "mcpServers": {
    "submarine": {
      "command": "node",
      "args": ["/path/to/submarine/mcp/dist/index.js"],
      "env": {
        "INDEXER_URL": "<Submarine API URL>",
        "RPC_URL": "https://testnet.zero.layerzero.network",
        "SUBMARINE_MAX_SPEND": "50"
      }
    }
  }
}

Add SUBMARINE_KEY only when you want it to send. On Windows, write the path with forward slashes or doubled backslashes, for example D:/submarine/mcp/dist/index.js.

How writes stay safe

GuardWhat it does
Simulation firstEvery write is simulated before it is signed. A trade the chain would refuse comes back as an error, with the contract's reason
dry_runEvery write tool takes it: the transactions come back, nothing is sent
No keyWrite tools return unsigned transactions (to, data, value) for the from address, for your own wallet to sign
Spend limitEvery ZRO a buy, launch, order, deposit or fee commits counts against SUBMARINE_MAX_SPEND. Past it, the tool refuses. A restart resets it
Checked quotesbuilder_quote decodes the API's transactions and refuses any that isn't the router trade or the approval asked for
Agent vaultThe vault tools can only trade inside the vault, within its owner's limits, and only the owner can take anything out
A key in the server can spend up to its limit. Keep SUBMARINE_MAX_SPEND to what you would let an agent lose, or give it an agent vault instead of a key with your money behind it.

What to ask

AskTools it uses
Which tokens are closest to moving to a pool?list_tokens with sort progress and stage curve
Is this token safe to buy, and what would 50 ZRO get me?get_risk, get_dev_wallets, quote_buy
Buy 20 ZRO of it and set a stop loss at 30% down.buy, then place_exit with kind stop_loss
Copy this wallet with at most 10 ZRO a trade.copy_deposit, copy_follow
Launch a coin called Cat with a 1% max wallet for an hour.launch_token
Am I fee-free, and what has my stake earned?get_staking, then claim_staking_rewards
Call this coin, and show me the best callers this month.post_call, then get_calls with tab top and window 30d
Buy 10 ZRO of it through my builder code.builder_quote with send true

Building on it

The public API has far more routes than these tools, and an agent can call them over HTTP. To be paid for the trades your agent brings, set SUBMARINE_BUILDER and use builder_quote, or pass your wallet as partner on buy and sell. Source: mcp/src/index.ts and mcp/src/config.ts.