{"openapi":"3.1.0","info":{"title":"Helm Swap API","version":"0.1.0","summary":"Live: keyless quotes and unsigned swap transactions (free API key for Solana builds) on Solana, Base, Ethereum, BNB Chain, Robinhood Chain, Ink, HyperEVM (999), Elysium (99901) and Arc (5042) (Arbitrum and Polygon quote-only), with the fee disclosed on every quote. The user's wallet signs and sends; Helm never holds keys and the server never broadcasts.","description":"Swaps are LIVE on Solana, Base (8453), BNB Chain (56), Ethereum (1), Robinhood Chain (4663), Ink (57073), HyperEVM (999), Elysium (99901) and Arc (5042), free to call. Quotes and EVM builds are keyless; Solana transaction builds (POST /api/v1/build-tx with chain=solana, and Solana quotes with prebuild=true) require a free API key in the X-Helm-Key header, created at https://helmswap.com/developers or POST /api/v1/keys. Arbitrum (42161) and Polygon (137) are quote-only: build-tx returns HTTP 503 FEE_ROUTER_NOT_CONFIGURED. The API returns quotes and unsigned transactions that the user's own wallet signs and sends. Helm never holds keys; this server never signs and never broadcasts, so responses keep dryRun: true / broadcast: false / broadcastable: false (meaning \"the server will not broadcast\", not a simulation). Every quote discloses the HelmSwap fee before signing: 25 bps (0.25%) for majors (ETH, WETH, USDC, USDbC, DAI, cbBTC, USDT, EURC, USDS, wstETH, cbETH, weETH, rETH, WBTC, and the equivalent majors on each chain), 60 bps (0.60%) for other curated tokens, 72 bps (0.72%) for new or long-tail tokens; the pair pays the higher tier. Pool/LP fees are in the quoted price. No hidden spread, no forced routing. On EVM fee-router swaps, positive slippage above the honest (not padded) quoted net is split as disclosed in surplusShare; the user does not always receive at least the quoted net if the swap underperforms (floor is the signed minOut, never reduced to pay surplus). The optional referrer (alias ref) attributes a swap to a wallet; the trader pays the same fee, and any referral payout is shown in the quote's fee object and covered by the referral terms (https://helmswap.com/referrals, https://helmswap.com/terms). Perps and prediction markets are not part of this API. Tokenized stocks are refused (HTTP 451).","license":{"name":"MIT","identifier":"MIT"}},"servers":[{"url":"https://helmswap.com","description":"HelmSwap production API (swaps live; the server never broadcasts)."}],"tags":[{"name":"swap"},{"name":"tokens"},{"name":"meta"}],"paths":{"/api/v1/quote":{"get":{"tags":["swap"],"operationId":"getQuote","summary":"Best quoted route + disclosed fee","parameters":[{"name":"tokenIn","in":"query","required":true,"schema":{"type":"string","description":"EVM address on the selected chain, or ETH / BNB / POL / 0xEeee…EEeE for the native asset."}},{"name":"tokenOut","in":"query","required":true,"schema":{"type":"string","description":"EVM address on the selected chain, or ETH / BNB / POL / 0xEeee…EEeE for the native asset."}},{"name":"amountIn","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]+$","description":"Integer amount in token base units."}},{"name":"chainId","in":"query","description":"EVM chain (alias chain): 8453 Base (default), 56 BNB Chain, 1 Ethereum, 4663 Robinhood Chain, 57073 Ink, 999 HyperEVM, 99901 Elysium and 5042 Arc are swap-live; 42161 Arbitrum and 137 Polygon are quote-only (build-tx returns 503). Aliases base/bnb/eth/robinhood/ink/hyperevm/elysium/arc/arbitrum/polygon accepted. chain=solana uses the Solana path (inputMint / outputMint / amount, base58 mints).","schema":{"type":"integer","enum":[8453,56,1,4663,57073,999,99901,5042,42161,137],"default":8453}},{"name":"slippageBps","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000,"default":50}},{"name":"referrer","in":"query","description":"Optional wallet to attribute the swap to (alias ref). The trader pays the same fee; see the referral terms.","schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"referrerShareBps","in":"query","description":"Optional. Omit it: keyless callers get the standard referral terms (the applied value is echoed in fee.referrerShareBps).","schema":{"type":"integer","minimum":0,"maximum":5000}},{"name":"x-api-key","in":"header","required":false,"description":"Not needed. API keys are not being issued; omit this header (standard keyless tier).","schema":{"type":"string"}},{"name":"prebuild","in":"query","required":false,"description":"Solana only: true returns the unsigned tx with the quote (needs X-Helm-Key).","schema":{"type":"boolean"}},{"name":"X-Helm-Key","in":"header","required":false,"description":"Free API key. Required for chain=solana builds (and Solana quotes with prebuild=true; without it the quote omits the unsigned tx). Not needed for EVM.","schema":{"type":"string","pattern":"^hsk_[A-Za-z0-9_-]{32}$"}}],"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Solana builds: API key missing (API_KEY_REQUIRED) or unknown (API_KEY_INVALID). Otherwise an unknown or disabled x-api-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"Refused: a tokenized stock / tokenized ETF / pre-IPO token is on one side (code TOKENIZED_EQUITY_BLOCKED). No override.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquityBlocked"}}}},"502":{"description":"Upstream RPC / quote failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/build-tx":{"post":{"tags":["swap"],"operationId":"buildTx","summary":"Unsigned fee-router transaction for the user's wallet to sign and send (the server never broadcasts). 503 on 42161/137.","description":"chain=solana builds require a free API key in the X-Helm-Key header (401 API_KEY_REQUIRED without one; 403 if the key is suspended or revoked). EVM builds are keyless.","security":[{},{"helmKey":[]}],"parameters":[{"name":"x-api-key","in":"header","required":false,"description":"Not needed. API keys are not being issued; omit this header (standard keyless tier).","schema":{"type":"string"}},{"name":"X-Helm-Key","in":"header","required":false,"description":"Free API key. Required when chain=solana. Not needed for EVM.","schema":{"type":"string","pattern":"^hsk_[A-Za-z0-9_-]{32}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tokenIn","tokenOut","amountIn","recipient"],"properties":{"tokenIn":{"type":"string","description":"EVM address on the selected chain, or ETH / BNB / POL / 0xEeee…EEeE for the native asset."},"tokenOut":{"type":"string","description":"EVM address on the selected chain, or ETH / BNB / POL / 0xEeee…EEeE for the native asset."},"amountIn":{"type":"string","pattern":"^[0-9]+$","description":"Integer amount in token base units."},"recipient":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Taker / recipient address. Never a private key."},"chainId":{"type":"integer","enum":[8453,56,1,4663,57073,999,99901,5042,42161,137],"default":8453,"description":"EVM chain. 8453, 56, 1, 4663, 57073, 999, 99901, 5042 build; 42161 and 137 return 503 FEE_ROUTER_NOT_CONFIGURED. Solana uses the separate chain=solana path."},"quoteTicket":{"type":"object","description":"Signed ticket from GET /api/v1/quote. Required; the server reads quotedOutNet and surplusShareBps from it."},"referrer":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"referrerShareBps":{"type":"integer","minimum":0,"maximum":5000,"description":"Optional. Omit it: keyless callers get the standard referral terms."},"slippageBps":{"type":"integer","minimum":0,"maximum":1000},"usePermit2":{"type":"boolean"},"allowHighPriceImpact":{"type":"boolean","default":false,"description":"Explicit opt-in to build when price impact is at/above the hard cap (default 15%) or could not be measured. Never lifts the exhausted-liquidity refusal (HTTP 422 PRICE_IMPACT_TOO_HIGH)."}}}}}},"responses":{"200":{"description":"Unsigned tx + approvals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildTxResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Solana builds: API key missing (API_KEY_REQUIRED) or unknown (API_KEY_INVALID). Otherwise an unknown or disabled x-api-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"Refused: a tokenized stock / tokenized ETF / pre-IPO token is on one side (code TOKENIZED_EQUITY_BLOCKED). No override.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquityBlocked"}}}},"502":{"description":"Upstream RPC / quote failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/link":{"get":{"tags":["meta"],"operationId":"getTradeLink","summary":"Build a canonical Open on HelmSwap deep link","description":"Returns https://helmswap.com/t/{chain}/{token}?ref={wallet} plus a copyable 'Open on HelmSwap: <link>' template. Invalid or missing ref is omitted (not an error). The trader pays the same disclosed fee; see the referral terms.","parameters":[{"name":"chain","in":"query","required":true,"description":"solana, base, bnb (alias bsc), ethereum, robinhood, ink, hyperevm, elysium, or arc. chainId is also accepted.","schema":{"type":"string"}},{"name":"token","in":"query","required":true,"description":"Token mint (Solana, including pump.fun) or contract address. Alias: tokenOut.","schema":{"type":"string"}},{"name":"ref","in":"query","required":false,"description":"Referrer wallet (alias referrer). Invalid values are omitted.","schema":{"type":"string"}}],"responses":{"200":{"description":"Canonical link","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"template":{"type":"string"},"path":{"type":"string"},"chain":{"type":"string"},"token":{"type":"string"},"ref":{"type":["string","null"]}},"required":["url","template","path","chain","token"]}}}},"400":{"description":"Invalid chain or token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tokens/search":{"get":{"tags":["tokens"],"operationId":"searchTokens","summary":"Search tokens by name, symbol or address (featured list when q is empty)","parameters":[{"name":"q","in":"query","required":false,"description":"Name, symbol, contract address or mint. Empty returns featured tokens.","schema":{"type":"string"}},{"name":"chain","in":"query","required":false,"description":"solana, base (default), bnb, ethereum, robinhood, ink, hyperevm, elysium or arc. chainId (8453, 56, 1, 4663, 57073, 999, 99901, 5042) is also accepted.","schema":{"type":"string"}}],"responses":{"200":{"description":"{ tokens: [{ id, name, symbol, decimals, usdPrice, chain, icon, ... }] }. Tokenized stocks are excluded."},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Solana builds: API key missing (API_KEY_REQUIRED) or unknown (API_KEY_INVALID). Otherwise an unknown or disabled x-api-key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"Refused: a tokenized stock / tokenized ETF / pre-IPO token is on one side (code TOKENIZED_EQUITY_BLOCKED). No override.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquityBlocked"}}}},"502":{"description":"Upstream RPC / quote failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/keys":{"post":{"tags":["meta"],"operationId":"createApiKey","summary":"Create a free API key (needed for Solana transaction builds). Shown once; only a hash is stored.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["label"],"properties":{"label":{"type":"string","minLength":2,"maxLength":60,"description":"Your app or bot name."},"email":{"type":"string","format":"email","description":"Optional. Only used to cap keys per person."}}}}}},"responses":{"201":{"description":"Key created","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"createdAt":{"type":"string"},"header":{"const":"X-Helm-Key"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["meta"],"operationId":"getApiKey","summary":"Status of the key in X-Helm-Key (active, suspended or revoked) and its fee-check counts.","security":[{"helmKey":[]}],"responses":{"200":{"description":"Key status"},"404":{"description":"Unknown key"}}},"delete":{"tags":["meta"],"operationId":"revokeApiKey","summary":"Permanently revoke the key in X-Helm-Key.","security":[{"helmKey":[]}],"responses":{"200":{"description":"Revoked"},"404":{"description":"Unknown key"}}}},"/api/v1/openapi.json":{"get":{"tags":["meta"],"operationId":"getOpenApi","summary":"This document (also served at /openapi.json)","responses":{"200":{"description":"OpenAPI 3.1 JSON"}}}}},"components":{"securitySchemes":{"helmKey":{"type":"apiKey","in":"header","name":"X-Helm-Key","description":"Free API key from https://helmswap.com/developers. Required for Solana transaction builds; rate-limited per key; revocable. Keys whose landed swaps skip the disclosed fee are suspended."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"retryAfterSec":{"type":"integer"}},"required":["error"]},"EquityBlocked":{"type":"object","description":"Tokenized stocks, tokenized ETFs, and pre-IPO tokens are blocked on either side of a swap (HTTP 451, code TOKENIZED_EQUITY_BLOCKED). There is no override.","properties":{"error":{"type":"string"},"code":{"const":"TOKENIZED_EQUITY_BLOCKED"},"side":{"type":"string","description":"Which input held the stock: tokenIn, tokenOut, destinationToken, targetToken, sourceToken."},"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"symbol":{"type":"string"},"name":{"type":"string"},"issuer":{"type":"string","enum":["coinbase","dinari","backed","unverified-claim","unknown"]},"detection":{"type":"string","enum":["maintained-list","issuer-contract","name-heuristic"]},"rule":{"type":"string"},"listVersion":{"type":"string"}},"required":["error","code","side","token"]},"Fee":{"type":"object","description":"Swaps are LIVE on Solana, Base (8453), BNB Chain (56), Ethereum (1), Robinhood Chain (4663), Ink (57073), HyperEVM (999), Elysium (99901) and Arc (5042), free to call. Quotes and EVM builds are keyless; Solana transaction builds (POST /api/v1/build-tx with chain=solana, and Solana quotes with prebuild=true) require a free API key in the X-Helm-Key header, created at https://helmswap.com/developers or POST /api/v1/keys. Arbitrum (42161) and Polygon (137) are quote-only: build-tx returns HTTP 503 FEE_ROUTER_NOT_CONFIGURED. The API returns quotes and unsigned transactions that the user's own wallet signs and sends. Helm never holds keys; this server never signs and never broadcasts, so responses keep dryRun: true / broadcast: false / broadcastable: false (meaning \"the server will not broadcast\", not a simulation). Every quote discloses the HelmSwap fee before signing: 25 bps (0.25%) for majors (ETH, WETH, USDC, USDbC, DAI, cbBTC, USDT, EURC, USDS, wstETH, cbETH, weETH, rETH, WBTC, and the equivalent majors on each chain), 60 bps (0.60%) for other curated tokens, 72 bps (0.72%) for new or long-tail tokens; the pair pays the higher tier. Pool/LP fees are in the quoted price. No hidden spread, no forced routing. On EVM fee-router swaps, positive slippage above the honest (not padded) quoted net is split as disclosed in surplusShare; the user does not always receive at least the quoted net if the swap underperforms (floor is the signed minOut, never reduced to pay surplus). The optional referrer (alias ref) attributes a swap to a wallet; the trader pays the same fee, and any referral payout is shown in the quote's fee object and covered by the referral terms (https://helmswap.com/referrals, https://helmswap.com/terms). Perps and prediction markets are not part of this API. Tokenized stocks are refused (HTTP 451).","properties":{"disclosed":{"const":true},"feeBps":{"type":"integer","minimum":1,"maximum":100,"description":"Standard 25 majors / 60 listed / 72 long-tail; volume tiers pro 19/48/57, scale 13/36/46."},"feePercent":{"type":"string"},"feeFrom":{"type":"string","enum":["output","input"]},"feeAmount":{"type":"string","pattern":"^[0-9]+$","description":"Integer amount in token base units."},"grossOutAmount":{"type":"string","pattern":"^[0-9]+$","description":"Integer amount in token base units."},"netOutAmount":{"type":"string","pattern":"^[0-9]+$","description":"Integer amount in token base units."},"referrer":{"type":["string","null"]},"referrerShareBps":{"type":"integer"},"referrerAmount":{"type":"string","pattern":"^[0-9]+$","description":"Integer amount in token base units."},"treasuryAmount":{"type":"string","pattern":"^[0-9]+$","description":"Integer amount in token base units."},"description":{"type":"string"},"surplusShare":{"$ref":"#/components/schemas/SurplusShare"}},"required":["disclosed","feeBps","feeAmount","netOutAmount"]},"SurplusShare":{"type":"object","description":"Disclosed positive-slippage share. If the swap clears above quotedOutNet (honest net after the swap fee), the extra is split userShareBps/operatorShareBps (default 50/50, operator cap 50%). The signed minimum is never reduced. Off (0) on Solana and keeper fills. Not a hidden spread; quotes are not padded.","properties":{"disclosed":{"const":true},"enabled":{"type":"boolean"},"operatorShareBps":{"type":"integer","minimum":0,"maximum":5000},"userShareBps":{"type":"integer"},"quotedOutNet":{"type":"string","pattern":"^[0-9]+$","description":"Integer amount in token base units."},"description":{"type":"string"},"scope":{"type":"string","enum":["evm-fee-router","solana-unsupported","keeper-fill-off","not-via-fee-router","fee-router-undeployed"]}},"required":["disclosed","enabled","operatorShareBps","quotedOutNet"]},"Pricing":{"type":"object","description":"Pricing tier applied to this request. feeBpsEncoded (build-tx) is the exact feeBps in the router calldata.","properties":{"tier":{"type":"string","enum":["standard","pro","scale"]},"volumeUsd30d":{"type":"number"},"nextTier":{"type":["object","null"]},"feeBpsApplied":{"type":"integer"},"feeBpsEncoded":{"type":"integer"},"standardFeeBps":{"type":"integer"},"discountBps":{"type":"integer"},"referrer":{"type":["string","null"]},"referrerShareBps":{"type":"integer"},"shareSource":{"type":"string"},"trackedNotionalUsd":{"type":["number","null"]},"disclosure":{"type":"string"}}},"UnsignedTx":{"type":"object","properties":{"to":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"data":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"integer"},"description":{"type":"string"}},"required":["to","data","value","chainId"]},"QuoteResponse":{"type":"object","properties":{"fee":{"$ref":"#/components/schemas/Fee"},"pricing":{"$ref":"#/components/schemas/Pricing"},"quote":{"type":"object"},"quoteTicket":{"type":"object"},"quotedOutNet":{"type":"string","pattern":"^[0-9]+$","description":"Integer amount in token base units."},"surplusShareBps":{"type":"integer","minimum":0,"maximum":5000},"surplusShare":{"$ref":"#/components/schemas/SurplusShare"},"priceImpactPct":{"type":["number","null"],"description":"Price impact of the executable path vs a 1% reference quote on the same path, in percent. null if not measured in time."},"priceImpact":{"$ref":"#/components/schemas/PriceImpact"},"warnings":{"type":"array","items":{"type":"string"}},"timing":{"type":"object","description":"Route-search budget. partial=true means the best quote found before the deadline (some venues did not answer)."},"config":{"type":"object"},"note":{"type":"string"}}},"PriceImpact":{"type":"object","description":"Impact guard. level warn at/above warnPct (default 1%); blocked at/above maxPct (default 15%), when unmeasured, or when liquidity is exhausted (output stops growing with input). build-tx refuses when buildable=false unless allowHighPriceImpact is set and overridable=true.","properties":{"level":{"type":"string","enum":["ok","warn","blocked","unknown"]},"priceImpactPct":{"type":["number","null"]},"liquidityExhausted":{"type":"boolean"},"buildable":{"type":"boolean"},"overridable":{"type":"boolean"},"warnPct":{"type":"number"},"maxPct":{"type":"number"},"warning":{"type":["string","null"]}}},"BuildTxResponse":{"type":"object","properties":{"dryRun":{"const":true,"description":"Always true: this server never broadcasts. The tx is real; the user's wallet sends it."},"broadcastable":{"const":false,"description":"Always false: the server will not broadcast. Not a simulation flag."},"pricing":{"$ref":"#/components/schemas/Pricing"},"fee":{"$ref":"#/components/schemas/Fee"},"tx":{"$ref":"#/components/schemas/UnsignedTx"},"feeParams":{"type":"object","description":"FeeParams encoded in tx.data, including quotedOutNet and surplusShareBps from the signed quoteTicket."},"quotedOutNet":{"type":"string","pattern":"^[0-9]+$","description":"Integer amount in token base units."},"surplusShareBps":{"type":"integer","minimum":0,"maximum":5000},"surplusShare":{"$ref":"#/components/schemas/SurplusShare"},"priceImpactPct":{"type":["number","null"]},"priceImpact":{"$ref":"#/components/schemas/PriceImpact"},"approvals":{"type":"array","items":{"$ref":"#/components/schemas/UnsignedTx"}},"note":{"type":"string"}}},"DryRunEnvelope":{"type":"object","description":"Unsigned plan envelope. dryRun: true / broadcast: false / broadcastable: false mean this server never broadcasts; the user's wallet signs and sends.","properties":{"ok":{"type":"boolean"},"dryRun":{"const":true},"broadcast":{"const":false},"broadcastable":{"const":false}},"additionalProperties":true}}},"x-fee-router":{"1":"0xA93991fb66f3847Beab3B5e79B5da4F5c2184e52","56":"0xA93991fb66f3847Beab3B5e79B5da4F5c2184e52","999":"0x2384EFffE80523aAe945d996257810282D4E25eB","4663":"0xA93991fb66f3847Beab3B5e79B5da4F5c2184e52","5042":"0x917c533F38283898C6E6C0EEDA238AE6B7b90FD2","8453":"0xB8da0dc565232632281738Bc0237409673D91487","57073":"0xa6097c11a2A57bAEc02ebd180be567CA1cda288C","99901":"0xa6097c11a2A57bAEc02ebd180be567CA1cda288C"},"x-swaps-live":true,"x-swap-live-chains":["solana",8453,56,1,4663,57073,999,99901,5042],"x-not-live":["perps","predictions"],"x-dry-run":false,"x-broadcast":false}