Create and trade tokens on SURGE via API with server-managed wallets, one-time free funding, and auto-routed pre-DEX and post-DEX trading on EVM (Base) or So...
If isNew: false — wallet already existed, that's fine
The wallet is linked to the user's account
Tell the user:
I've created a server-managed wallet for you. No private keys to worry about — everything is handled securely on our side.
Step 2: Fund the Wallet (ONE TIME FREE)
Important rule: The platform funds each wallet exactly ONCE for free. This covers the gas + minimum buy for the first token launch. After that, the user pays for everything themselves.
text
POST /openclaw/wallet/{walletId}/fund
Header: X-API-Key: {key}
If successful (needsFunding: false):
Your wallet has been funded! You get one free token launch from SURGE — gas and fees are covered.
If already funded (second call):
This wallet was already funded. The free launch is a one-time gift. If you need more funds (for trading, etc.), send ETH/SOL directly to your wallet address: {address}
If funding fails (e.g. platform funder is low):
Automatic funding didn't go through right now. You can either:
Try again in a few minutes
Send funds manually to your wallet address: {address} on the Base network
The minimum balance needed is {minBalance} (from launch-info).
Step 3: Check Balance
text
GET /openclaw/wallet/{walletId}/balance
Header: X-API-Key: {key}
Response includes sufficient: true/false and minRequired per chain.
If sufficient: true — proceed to token creation.
If sufficient: false — tell the user:
Your wallet balance is {balance} but you need at least {minRequired}. Please send {minRequired - balance} to your wallet address: {address} on {chain}.
Step 4: Collect Token Information
Now collect what's needed to launch the token. Ask one group at a time. Don't dump everything at once.
4a. Name, Ticker, Description (REQUIRED)
Ask:
Let's create your token! I need three things to start:
Token name — the full name (e.g. "NeuralNet Token")
Ticker — short symbol, 3-5 letters (e.g. "NNET")
Description — one sentence about what the token is for (e.g. "Decentralized AI compute marketplace")
Rules:
If user gives only a ticker — ask for the full name
If user gives a paragraph as description — say: "Great, I'll use that as the detailed description. Can you give me a one-liner tagline too?"
Never make up names, tickers, or descriptions yourself
4b. Logo Image (REQUIRED)
Ask:
Now I need a logo for your token. Send me a direct link to an image file (PNG, JPG, or WEBP, max 5MB).
How to get a direct image link:
If the user has a file on their computer, tell them:
Upload your image to get a direct link. The easiest way:
BAD: https://drive.google.com/file/d/... (preview page, not direct)
4c. Chain (REQUIRED)
Build this question from launch-info data:
Which blockchain do you want to launch on?
Available:
Base (EVM) — fee: {fee} ETH
Solana — fee: {fee} SOL
Base is recommended for most projects. Solana is great for high-speed, low-cost trading.
Map the user's choice to the correct chainId from launch-info. The user should never see raw IDs.
This determines everything else:
EVM → use /launch, needs ethAmount
Solana → use /launch-solana, needs preBuyAmount
4d. Initial Buy Amount (REQUIRED)
If EVM chain:
Ask:
How much ETH do you want for the initial buy? This buys the very first tokens when your contract launches.
Minimum: slightly more than {fee} ETH (the contract fee)
Recommended: {fee × 2} ETH for a good start
This determines the starting price — bigger amount = higher starting price
User says
What to do
Less than or equal to fee
"The contract fee is {fee} ETH. Your amount must be higher. I'd recommend {fee × 2}."
Reasonable (0.01–1 ETH)
Accept
Very large (10+ ETH)
"That's {amount} ETH — are you sure?"
If Solana chain:
First ask which currency:
Which currency do you want for your token's fundraising pool?
SOL (default) — fundraising goal: 85 SOL. Your initial buy is in SOL.
USD1 (stablecoin) — fundraising goal: 12,500 USD1. Your initial buy is in USD1.
Most projects use SOL. USD1 is for stablecoin-based pools.
Then ask for the amount:
How much {SOL/USD1} for the initial buy? Even a small amount like 0.01 works.
Important about funding:
If user picks SOL — the one-time free funding covers platform fee + gas + min preBuy. They're ready to go.
If user picks USD1 — the free funding only covers SOL (for platform fee + gas). The user must have USD1 tokens in their wallet for the initial buy. Tell them:
Since you chose USD1, you'll need USD1 tokens in your Solana wallet for the initial buy. The platform covers SOL fees, but USD1 you provide yourself. Send USD1 to your wallet address: {address}
4e. Category (OPTIONAL — but suggest it)
Based on what the user already told you, suggest 2-3 matching categories:
Based on your description, this sounds like an AI project. Should I set the category to ai? Or is it more defi / infrastructure?
Your token is now trading on the Raydium launchpad!
Error Handling — What to Tell the User
When something goes wrong, don't show raw errors. Translate them:
Error contains
What to say
"image" or "download"
"I couldn't download your logo. Make sure it's a direct link to an image file, not a gallery page. Try uploading to file.io: curl -F 'file=@logo.png' https://file.io"
"explicit"
"Your image was flagged as inappropriate. Please use a different image."
"fee" or "ethAmount"
"The amount is too low. The current fee on {chain} is {fee} — your amount must be higher. Try {fee × 2}."
"not a Solana wallet"
"You're using an EVM wallet for Solana. Let me create a Solana wallet for you." → Call /wallet/create-solana
"Wallet not found"
"That wallet doesn't exist. Let me create a new one for you." → Call /wallet/create
"already funded"
"Your wallet was already funded with the free launch. For more funds, send to your wallet address: {address}"
"insufficient funds"
"Your wallet doesn't have enough balance. Send at least {minBalance} to {address} on {chain}."
"not on bonding curve"
"This token has graduated to the DEX. Don't worry — our API handles DEX trading automatically. Try your buy/sell again."
"arithmetic underflow"
"The sell amount is too large for the current pool. Try selling a smaller amount."
"Daily funding limit"
"Platform funding is temporarily unavailable. Send funds manually to {address}."
401
"Your API key is invalid or expired. Go to app.surgedevs.xyz → Settings → API Keys to generate a new one."
429
"Too many requests. Wait a moment and try again."
500
"Server error — not your fault. Let's try again in a minute."
Trading (After Token Launch)
After a token is launched, you can buy and sell. Trading requires the wallet to have funds — the free funding only covers the first launch.
Tell the user:
To trade, you'll need funds in your wallet. Send ETH/SOL to your wallet address: {address}
How Trading Works — Auto-Routing
You don't need to choose the trading method. The API automatically detects the token phase and routes your trade:
Pre-DEX (bonding curve / launchpad) — Trade directly on the SURGE bonding curve (EVM) or Raydium launchpad (Solana)
Post-DEX (Aerodrome / Raydium CPMM) — After graduation (100% bonding curve), the token migrates to a DEX. The API swaps automatically via Aerodrome (Base) or Raydium CPMM (Solana)
Same endpoints, same parameters, regardless of phase. Just call /buy or /sell.
EVM Trading — Check Token Phase (optional)
text
POST /openclaw/token-status
{ "chainId": "1", "tokenAddress": "0x..." }
Phase
Meaning
How /buy and /sell work
bonding_curve
Pre-DEX, active trading
Trades via BondingETHRouter (bonding curve)
migrated_to_dex
Graduated to Aerodrome DEX
Trades via Aerodrome Router (DEX swap with agentToken)
not_launched
Not active
Cannot trade — returns error
The response includes agentTokenAddress for post-DEX tokens. You don't need it — the API handles routing automatically.
