Docs · For builders
MCP server
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
| Tool | Arguments | What it does |
|---|---|---|
status | none | The 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_stats | range: 24h, 7d, 30d or all | The whole market, and Submarine's own figures over the range |
list_tokens | sort, stage, launchpad, creator, limit, offset | Tokens from every launchpad. sort: new, volume, progress, mcap, active. stage: curve, graduating, graduated, external |
search_tokens | q | Tokens by name, symbol or address, and wallets by address |
get_token | address, wallet | One 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_trades | address, trader, limit | Recent trades of a token, of a trader, or of the whole market |
get_trending | window, sort, limit | Tokens moving most over 1m, 5m, 1h, 6h or 24h, with their risk flags |
get_candles | address, interval, limit, before | Price candles in ZRO per token |
get_holders | address, limit, labelled | Holders, biggest first, and with labelled who each is |
get_dev_wallets | address | The creator: every buy, sale and transfer, what they hold, where they sent coins, and their other launches |
get_risk | address | Creator and top 10 shares, snipers, bundles, clusters, the all-time high, and what the chain says about owner, mint and LP |
get_wallet | address | Holdings with cost, recent trades, totals, closed positions, launches and open orders, and its ZRO and router rank |
get_wallet_stats | address, days: 7 or 30 | Its record as a trader |
get_leaderboard | window: 24h, 7d or all, limit | Traders by profit, open positions marked to the current price |
get_points | address, limit | One wallet's points and place, or the leaders, with the rules |
get_buybacks | none | The treasury's buyback and burn of the Submarine token, round by round |
get_staking | wallet | Staking: 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_launchpads | none | Every launchpad Submarine lists, with tokens, graduations and 24 hour volume |
list_orders | owner, token, open, id | Orders from the indexer, or one order read from the chain with its fills |
get_copy_vault | follower, leader | A 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_buy | address, zro, slippage_bps, wallet | Tokens 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_sell | address, tokens, slippage_bps | ZRO out at the best venue |
Trading and launching
| Tool | Arguments | What it does |
|---|---|---|
buy | token, amount_zro, slippage_bps, partner, partner_kind | Buys 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 |
sell | token, amount_tokens or percent, slippage_bps, partner, partner_kind | Sells through the router. Adds an approval first for a coin that needs one |
launch_token | name, 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_minutes | Saves 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_fee | token, creator_fee_pct | Lowers your own fee on a coin you launched. It must be below today's, and can never go back up |
Claims and staking
| Tool | Arguments | What it does |
|---|---|---|
claim_creator_fees | none | Your creator share from every coin you launched, curve and pool alike |
claim_holder_rewards | token | The ZRO a holder token owes you. Works after selling too |
claim_referral_earnings | none | What referrals earned you, and your own cashback |
stake | amount_tokens or percent | Stakes the Submarine token, with an approval first when needed |
unstake | amount_tokens or percent | Takes stake out. Any amount, any time |
claim_staking_rewards | none | The ZRO your stake has earned |
Calls, clans and partners
| Tool | Arguments | What it does |
|---|---|---|
get_calls | tab, window, caller, token, id, limit | Public 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_clans | tag, address, window, sort, search, limit | Clans 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_earnings | address, kind, limit | What 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_call | token, note | Calls 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
| Tool | Arguments | What it does |
|---|---|---|
builder_quote | token, side, amount, trader, builder, slippage_bps, send | Asks 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
| Tool | Arguments | What it does |
|---|---|---|
place_limit | token, side, amount, price_zro or market_cap_zro or move_pct, kind, expiry_hours | A 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_exit | token, kind, its level, amount_tokens or percent, more_legs, expiry_hours | Take 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_dca | token, total_zro, slices, interval_minutes, max_price_zro or max_market_cap_zro, expiry_hours | A buy split into 2 to 100 slices, never above the price cap: three times today's price unless you set one |
cancel_order | id | Cancels an order and returns its escrow. One leg cancels its whole group |
copy_deposit / copy_withdraw | amount_zro, or all | ZRO into or out of the copy vault |
copy_follow | leader, per_trade_zro, per_token_zro, per_day_zro, size_pct, slippage_pct, chase_pct, min_sell_pct, copy_sells, buy_once, max_age_seconds | Copies 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_unfollow | leader | Stops copying. Positions stay |
copy_set_exit | take_profit_pct, stop_loss_pct, slippage_pct | Take 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:
| Tool | Arguments | What it does |
|---|---|---|
vault_status | none | The vault's ZRO, the owner's limits, what is left to spend today, and its holdings |
vault_buy | address, zro, slippage (percent) | Buys with the vault's ZRO, minimum from a fresh quote. By default half the vault's slippage limit |
vault_sell | address, tokens or "all", slippage | Sells the vault's tokens. The ZRO goes back to the vault |
Install and settings
npm.cmd install
npm.cmd run build --workspace=mcpnpm install
npm run build --workspace=mcp| Variable | Default | What |
|---|---|---|
INDEXER_URL | http://localhost:3011 | The API to read from. Set it to the public one below to skip running an indexer. TERMINAL_API, its old name, still works |
RPC_URL | http://127.0.0.1:8546 | The node quotes are read from and trades sent to. Set it to Zero's, https://testnet.zero.layerzero.network |
SUBMARINE_KEY | none | A private key to sign with. It stays in this process. Without it, write tools need from and return unsigned transactions |
SUBMARINE_MAX_SPEND | 100 | The most ZRO this server may commit, in total, for as long as it runs |
SUBMARINE_SLIPPAGE_BPS | 100 | Slippage for trades that don't set their own, 0 to 5,000 |
SUBMARINE_DEPLOYMENT | none | A deployment file to read instead of the repository's contracts/deployments/<chain id>.json |
EXPLORER_URL | none | An explorer, for a link to each transaction sent |
AGENT_VAULT, AGENT_KEY | none | An agent vault and its agent key, which turn on the three vault tools |
INDEXER_API_KEY | none | A 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_BUILDER | none | Your 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:
{
"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
| Guard | What it does |
|---|---|
| Simulation first | Every write is simulated before it is signed. A trade the chain would refuse comes back as an error, with the contract's reason |
| dry_run | Every write tool takes it: the transactions come back, nothing is sent |
| No key | Write tools return unsigned transactions (to, data, value) for the from address, for your own wallet to sign |
| Spend limit | Every ZRO a buy, launch, order, deposit or fee commits counts against SUBMARINE_MAX_SPEND. Past it, the tool refuses. A restart resets it |
| Checked quotes | builder_quote decodes the API's transactions and refuses any that isn't the router trade or the approval asked for |
| Agent vault | The vault tools can only trade inside the vault, within its owner's limits, and only the owner can take anything out |
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
| Ask | Tools 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.