HelmSwap swap API
A free HTTP API for bots, wallets and apps. It returns a quote and an unsigned swap transaction for Solana, Base, Ethereum, BNB Chain, Robinhood Chain, Ink, HyperEVM, Elysium and Arc. Your user signs and sends it from their own wallet. Helm never holds keys, and the server never signs or broadcasts anything.
Quotes and EVM builds need no sign-up. Solana transaction builds need a free API key (see API keys). Base URL: https://helmswap.com. Machine-readable spec: /openapi.json (OpenAPI 3.1).
Quickstart
1. Get a quote (0.01 ETH to USDC on Base):
curl "https://helmswap.com/api/v1/quote?chainId=8453&tokenIn=ETH&tokenOut=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&amountIn=10000000000000000"2. Build the unsigned transaction. Pass the quoteTicket from the quote within about 45 seconds (this example uses jq):
Q=$(curl -s "https://helmswap.com/api/v1/quote?chainId=8453&tokenIn=ETH&tokenOut=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&amountIn=10000000000000000")
curl -s -X POST "https://helmswap.com/api/v1/build-tx" \
-H "content-type: application/json" \
-d "$(echo "$Q" | jq '{chainId: 8453, tokenIn: "ETH", tokenOut: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
amountIn: "10000000000000000", recipient: "0xYOUR_WALLET", quoteTicket: .quoteTicket}')"The same flow from JavaScript (browser or Node 18+; walletClient is your user's wallet, for example viem):
const API = "https://helmswap.com/api/v1";
const req = {
chainId: 8453,
tokenIn: "ETH",
tokenOut: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
amountIn: "10000000000000000", // 0.01 ETH in wei
};
// 1. Quote (expires in ~45 s). The fee is in q.fee before anything is signed.
const q = await (await fetch(`${API}/quote?${new URLSearchParams(req)}`)).json();
if (!q.ok) throw new Error(q.error);
console.log(q.fee.feePercent, q.quote.netOutAmount, q.quote.minOutNet);
// 2. Unsigned transaction for the user's own wallet.
const built = await (await fetch(`${API}/build-tx`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ ...req, recipient: userAddress, quoteTicket: q.quoteTicket }),
})).json();
if (!built.ok) throw new Error(built.error);
// 3. The user signs and sends from their wallet (approvals first, if any).
for (const a of built.approvals) await walletClient.sendTransaction({ to: a.to, data: a.data, value: BigInt(a.value) });
await walletClient.sendTransaction({ to: built.tx.to, data: built.tx.data, value: BigInt(built.tx.value) });Endpoints
GET /api/v1/quote
EVM query params: tokenIn, tokenOut (contract address, or ETH / BNB for the native coin, including HYPE on HyperEVM and Elysium; Arc has no native leg), amountIn (integer base units), chainId (default 8453), optional slippageBps (default 50) and optional ref.
Returns quote (grossOutAmount, netOutAmount, minOutNet, slippageBps), fee (feeBps, feePercent, feeAmount, feeFrom), priceImpact, surplusShare and a signed quoteTicket.
Solana: chain=solana with inputMint, outputMint and amount (base units). The fee is in quote.fee.
curl "https://helmswap.com/api/v1/quote?chain=solana&inputMint=So11111111111111111111111111111111111111112&outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=10000000"POST /api/v1/build-tx
JSON body: the same token, amount and chain fields as the quote, plus recipient (the user's address; for Solana use user) and the quoteTicket from the quote.
EVM response: tx (to, data, value, chainId) for the chain's router (see the router table below), plus approvals (an exact-amount ERC-20 approve when the input is a token; empty for native coins) and the same fee object. Solana response: tx.transactionBase64 (v0) and a read-only simulation.
Solana builds require a free API key in the X-Helm-Key header; without one the build returns 401 API_KEY_REQUIRED. The same applies to a Solana quote with prebuild=true: without a key the quote is still returned, but without the unsigned transaction. EVM builds need no key.
curl -s -X POST "https://helmswap.com/api/v1/build-tx" \
-H "content-type: application/json" \
-H "X-Helm-Key: hsk_YOUR_KEY" \
-d '{"chain":"solana","inputMint":"So11111111111111111111111111111111111111112",
"outputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"10000000",
"user":"YOUR_SOLANA_WALLET","quoteTicket":"<quoteTicket from the quote>"}'The build re-checks the price. It refuses with 409 if the ticket expired or the output moved, and with 422 if the price impact is too high.
GET /api/tokens/search
Params: q (name, symbol or address; empty returns featured tokens) and chain (solana, base, ethereum, bnb, robinhood, ink, hyperevm, elysium or arc). Returns tokens with id, symbol, decimals, usdPrice and icon.
curl "https://helmswap.com/api/tokens/search?q=usdc&chain=base"GET /api/v1/link
Params: chain, token and optional ref. Returns a shareable https://helmswap.com/t/{chain}/{token} trade link.
Chains
| Chain | Parameter | Routing |
|---|---|---|
| Solana | chain=solana | Orca Whirlpools, PumpSwap and pump.fun curves. Mints in base58; build-tx returns a base64 v0 transaction. |
| Base | chainId=8453 (default) | Fee router |
| Ethereum | chainId=1 | Fee router |
| BNB Chain | chainId=56 | Fee router |
| Robinhood Chain | chainId=4663 | Fee router |
| Ink | chainId=57073 | Fee router |
| HyperEVM | chainId=999 | Fee router. Native coin is HYPE (pass ETH as the native symbol). |
| Elysium | chainId=99901 | Fee router. Native coin is HYPE (pass ETH as the native symbol). |
| Arc | chainId=5042 | USDC fee router (1.4). USDC is the gas token and has no native leg: use the USDC address 0x3600…0000. |
The EVM router address is per chain (Arc runs the USDC-only build). Use tx.to from build-tx or feeRouters in /api/config. Sources are verified on Sourcify and on Basescan, BscScan and Etherscan.
| Chains | Chain IDs | Router |
|---|---|---|
| Base | 8453 | 0xB8da0dc565232632281738Bc0237409673D91487 |
| Ink and Elysium | 57073, 99901 | 0xa6097c11a2A57bAEc02ebd180be567CA1cda288C |
| Ethereum, BNB Chain and Robinhood Chain | 1, 56, 4663 | 0xA93991fb66f3847Beab3B5e79B5da4F5c2184e52 |
| Arc (USDC fee router 1.5) | 5042 | 0x917c533F38283898C6E6C0EEDA238AE6B7b90FD2 |
| HyperEVM (v1.3) | 999 | 0x2384EFffE80523aAe945d996257810282D4E25eB |
Fees
Every quote shows the HelmSwap fee before anything is signed: 0.25% on majors (ETH, USDC, USDT, SOL, BNB and similar), 0.60% on other curated tokens, and 0.72% on new or long-tail tokens. A pair pays the higher of its two tiers. Pool fees are already in the quoted price, and there is no hidden spread. On EVM swaps, any positive slippage above the quoted output is split as shown in surplusShare.
API keys (Solana builds)
Keys are free. Create one below and send it as X-Helm-Key on Solana build-tx calls (and on Solana quotes with prebuild=true). The key is shown once; we store only a hash of it. Each key has its own rate limit (about 120 builds per minute).
The disclosed fee transfer is part of every Solana transaction we build. We check that swaps built with a key pay it. A key whose landed swaps remove or reduce the fee is flagged, and is suspended after 3 such swaps within 7 days.
Check a key with GET /api/v1/keys and revoke it with DELETE /api/v1/keys, both with the X-Helm-Key header. Revoking is permanent.
Attribution (ref)
Optional. Add ref=0xYOUR_WALLET (or a Solana wallet on Solana) to a quote or build to attribute swaps to your wallet. Your user pays the same fee either way. See the referral terms.
Rate limits
About 60 requests per minute per IP on each endpoint, plus about 120 Solana builds per minute per API key. New keys are limited to a few per hour per IP. Over the limit you get 429 with a Retry-After header. CORS is open, so the endpoints work straight from the browser.
Not in this API
Tokenized stocks are refused with 451. Perps and prediction markets are not available. The server never submits transactions for you.
Terms and contact
Use of the API is covered by the Terms of Service. Questions or a broken route: message @HelmSwap on X.