API Reference

API reference

Base URL: https://<host>/v1. Machine-readable: openapi.yaml (served at GET /v1/openapi.yaml). Conventions (amounts, native HYPE, errors, request ids): API at a glance. Auth and limits: Access.

Swap: GET /quote
Tokens and prices: GET /price, GET /tokens, GET /tokens/{address}, WS /ws/prices
Orders: GET /orders, GET /orders/create, GET /orders/cancel
Account: GET /portfolio, GET /history
System: GET /health, GET /config, GET /openapi.yaml

Swap

`GET /quote`

Best route, exact quote, and a simulated transaction for an exact-input swap.

Query parameters

Name	Type	Required	Default	Description
`in`	token id	✅		ERC20 address, or `HYPE` for native
`out`	token id	✅		Must differ from `in`
`amount`	uint string	✅		Input in base units, > 0
`recipient`	address	✅		Receives the output
`sender`	address		`recipient`	Signs the tx; used for balance, allowance and gas simulation
`slippageBps`	integer		`50`	0–5000. `minOut = amountOut × (10000 − slippageBps) / 10000`
`permit2`	`"true"`			ERC20 input: use Permit2 instead of an approve to the Executor. Flow
`signature`	hex (65 bytes)			Permit2 signature (2nd call)
`permit2Nonce`	uint string		random	Nonce of the signed permit (2nd call)
`permit2Deadline`	uint string		tx deadline	Deadline of the signed permit (2nd call)

Response 200

Field	Type	Description
`amountIn`	uint string	Echo of `amount`
`amountOut`	uint string	Expected output to the recipient, net of the router fee and measured token taxes
`minOut`	uint string	Floor written into the tx
`feeBps`	integer	Router fee (0 on the launchpad path)
`priceImpactBps`	integer \| null	Output vs. the no-impact spot output of the same route
`taxBps`	integer	Measured sell tax of `in` + buy tax of `out`, already deducted from `amountOut`
`routerAmountOut`	uint string	Output before token taxes
`venue`	`"launchpad"`	Only present when the bonding curve beat the aggregator
`warnings`	string[]	Token warnings prefixed `in:` / `out:`, launchpad notice
`gas.estimate`	uint string	Gas units of the route (model)
`gas.costInTokenOut`	uint string	That gas, priced in `tokenOut` (used to rank routes)
`splits[]`	array	Legs of the route
`splits[].amountIn`	uint string	Part of `amountIn` sent down this leg
`splits[].route[]`	array	Hops of the leg, in order
`…route[].protocol`	string	`v2`, `v3`, `v4`, `wrap`, `launchpad` `solidly`
`…route[].pool`	address \| bytes32	Pool address; for `v4`, the 32-byte pool id
`…route[].factory`	address \| null	Factory, or the PoolManager for `v4` (null for `wrap`)
`…route[].tokenIn` / `tokenOut`	address	Tokens of this hop (WHYPE stands for native)
`…route[].fee`	integer	LP fee, hundredths of a bp (`3000` = 0.3%)
`wrappedNative`	address \| null	WHYPE used for native in/out; null when neither side is native
`tx`	object	`{ from, to, data, value, chainId }`; adds `warning` when the simulation failed
`approval`	object \| null	`{ to, data }` approve to send first
`permit2`	object \| null	`{ typedData }` to sign (Permit2 path)
`simulation`	object	`{ ok, gas? , error? }`
`block`	uint string	Indexer block the quote is based on

Errors: 400 bad input · 404 no route · 422 honeypot output · 429 · 503 backfilling / not configured.

Example

curl "$API/quote?in=HYPE&out=0x7D29d8047B905000459c0E80c34a26CeedcB47b2&amount=1000000000000000000&recipient=0xYou&slippageBps=50"

Tokens and prices

`GET /price`

Name	Type	Required	Description
`ids`	string	✅	Comma-separated token ids, max 100

{ "quote": "USDC", "data": { "HYPE": 24.81, "0x7D29…": 1, "0xdead…": null } }

Spot price of one whole token in USDC (net of LP fees, no size impact), computed in memory. null = no route to USDC.

`GET /tokens`

Name	Type	Default	Description
`q`	string		Substring of symbol or name, or an exact address
`limit`	integer	50	Max 500
`strict`	`"true"`		Verified tokens only

Returns { tokens: Token[] }: native HYPE first (when it matches q), then verified tokens, then by live pool count. Only tokens with at least one live pool are listed.

Token

Field	Type	Description
`address`	string	Checksummed address, or `HYPE`
`symbol`, `name`	string	From the contract
`decimals`	integer
`pools`	integer	Live pools containing it
`verified`	boolean	On the curated list
`logoURI`	string \| null	Verified tokens only
`tags`	string[]	Verified tokens only
`warnings`	string[]	See Token safety
`check`	object \| null	Probe result: `status` (`ok`/`taxed`/`honeypot`/`unknown`), `buyTaxBps`, `sellTaxBps`, `transferTaxBps`, `transferBlocked`, `checkedAt`

`GET /tokens/{address}`

One token, as above plus price (USDC). Runs the probe now if this token was never checked (the call can then take a second or two). 404 if the token isn't in any indexed pool.

`WS /ws/prices`

Send {"subscribe": [ids…]} (max 100). Receive {"prices": {id: price}} at once, then only changed prices after each block. See Live prices.

Orders

All three return 503 if the server has no ORDERBOOK_ADDRESS.

`GET /orders`

Name	Type	Description
`owner`	address	Optional filter

{ "orders": [ { "id": "3", "owner": "0x…", "tokenIn": "HYPE", "tokenOut": "0x7D29…", "remaining": "500000000000000000",
                "perSlice": "250000000000000000", "minOutPerSlice": "5600000", "interval": "86400",
                "nextFillAt": "1762500000", "expiry": "1762900000" } ] }

`GET /orders/create`

Name	Type	Required	Default	Description
`in`, `out`	token id	✅
`amount`	uint string	✅		Total input
`owner`	address	✅		Signs, receives output and refunds
`minOut`	uint string	✅		> 0, for the whole amount; pro rata per slice
`slices`	integer		1	1–1000, ≤ amount
`interval`	integer (s)	if slices > 1	0
`expiresIn`	integer (s)		604800

Response: { order: { perSlice, minOutPerSlice, slices, interval, expiry }, tx, approval, simulation }. The approval spender is the OrderBook.

`GET /orders/cancel`

Name	Type	Required
`id`	uint string	✅

Response: { tx: { to, data, value: "0", chainId } }. The owner can send it any time; anyone after expiry.

Account

`GET /portfolio`

owner (address, required). Returns { owner, totalUsd, tokens: [{ address, symbol, name, decimals, balance, price, usd }] }. Non-zero balances only. Details.

`GET /history`

owner (address, required), limit (default 50, max 200). Returns { owner, items: [...] }, newest first; item type is Swapped, OrderCreated, OrderFilled or OrderCancelled. Details.

System

`GET /health`

Not rate limited.

{ "ready": true, "lastBlock": "24263641", "pools": { "v3": 2263, "v2": 1456, "v4": 767 },
  "executor": "0x…", "orderBook": "0x…", "keeper": true }

ready turns true once the initial backfill or snapshot replay is done; /quote returns 503 until then.

`GET /config`

{ "name": "Elysium Testnet", "chainId": 99801, "rpcUrl": "https://testnet-rpc.elysium.kinetiq.xyz", "explorer": "https://testnet.elysium.kinetiq.xyz" }

The public RPC from the network file (never the server's private RPC_URL). Used by wallets to add or switch the chain.

`GET /openapi.yaml`

The OpenAPI 3.1 spec of this API.

Changelog

Version	Change
v1	Versioned paths (`/v1/...`), partner API keys, `x-request-id`, `requestId` in errors, OpenAPI spec