Quotes and liquidity API

The quote service reads the configured contracts and venue to produce transaction limits. It does not execute swaps or sign transactions. Each route below is a JSON POST unless stated otherwise; see the HTTP reference for transport and errors.

All 0x111…, 0x222…, and 0x333… addresses in these examples are synthetic placeholders, not deployed assets or contract recommendations. Replace them with verified addresses on the configured network. Responses depend on actual contract state and liquidity.

Shared quote rules

Raw quantities use decimal strings. quotedBlock and observedBlock are decimal block numbers. quotedAt and expiresAt are Unix milliseconds; liquidity deadline is a decimal string of Unix seconds equal to floor(expiresAt / 1000).

Quotes expire two minutes after quotedAt. The current implementation uses 50 basis points (0.5%) slippage and a maximum 500 basis points (5%) impact against fee-adjusted pool spot estimates. These are distinct constraints. Routing checks pool provenance and searches a bounded set of direct/two-hop V3 routes at fees 100, 500, 3000, and 10000; it does not promise globally optimal execution.

The shared quote read context allows at most 450 upstream calls, six concurrent reads, and a 14-second time budget. At most two native/liquidity read operations run concurrently per upstream transport. Coalesce duplicate previews in the client and back off on capacity errors rather than launching parallel retries.

Launch and proportional-trade snapshots use head minus 20 blocks on Robinhood networks. Liquidity queries prefer the current head and permit bounded fallback to head minus 5 or 20 only for a state-height RPC error. See freshness before treating a quote as current enough to submit.

ETH-route availability

POST /v1/launch/availability requires nativeLaunch configuration. Supply 1–10 distinct, nonzero token addresses:

{
  "tokens": [
    "0x1111111111111111111111111111111111111111",
    "0x2222222222222222222222222222222222222222"
  ]
}

Illustrative result shape:

{
  "chainId": 46630,
  "observedBlock": "123456",
  "tokens": [
    {"token":"0x1111111111111111111111111111111111111111","available":true,"reason":"available"},
    {"token":"0x2222222222222222222222222222222222222222","available":false,"reason":"no_active_route"}
  ]
}

The response preserves input order. The configured wrapped-native token passes without a swap. RPC failures fail the request rather than turning into available: false. An available structural route can still fail at the final amount, on token behavior, or because multiple basket legs would share a pool.

ETH-funded creation

POST /v1/launch/quote accepts exactly tokens, weightsBps, and amountIn:

{
  "tokens": [
    "0x1111111111111111111111111111111111111111",
    "0x2222222222222222222222222222222222222222"
  ],
  "weightsBps": [6000, 4000],
  "amountIn": "10000000000000000"
}

This example allocates 0.01 ETH at 60/40 spend weights. Supply 2–10 unique tokens, one positive integer weight per token, and an exact total of 10,000. The first allocations round down; the final token receives the remaining wei. Each allocation must be positive, and each supported output must meet the 1,000 raw-unit minimum.

Response fields	Meaning
chainId, factory, router	Chain, native launch factory, and DEX router binding
amountIn, weightsBps, tokens	Echoed funding and ordered allocation inputs
paths	Forward V3 byte paths, one per token; wrapped-native leg uses 0x
amountsOut, minimumAmounts	Ordered expected and minimum raw token outputs
priceImpactBps	Ordered per-leg impact
quotedBlock, quotedAt, expiresAt, slippageBps	Snapshot and validity

Allocation weights describe ETH spending at launch. They are not oracle-backed value weights. The response does not include a signed transaction or wallet address; the frontend binds it to the active account and draft before execution.

Proportional ETH buy and sell

POST /v1/trade/quote requires nativeTrading configuration and accepts exactly:

{
  "basket": "0x1111111111111111111111111111111111111111",
  "side": "buy",
  "amount": "10000000000000000"
}

For buy, amount is an ETH budget in wei. For sell, it is raw shares to burn. Do not add account to this HTTP body: the route rejects extra fields. The frontend request type carries account separately and binds it when validating the response.

Responses include every nativeTrading setting (chainId, router, registry, nativeRegistry, dexRouter, dexFactory, wrappedNative, quoter, intermediates) plus:

Fields	Meaning
basket, side, amount	Bound request
tokens, paths, componentAmounts	Ordered constituents, forward routes, exact proportional quantities
grossShares, feeShares, netShares	Backed issuance fee split; sell preview carries its corresponding zero-fee split
estimatedAmount	ETH cost for buy; ETH proceeds for sell
limitAmount	Maximum submitted ETH for buy; minimum ETH output for sell
quotedBlock, quotedAt, expiresAt, slippageBps, priceImpactBps	Snapshot, expiry, and per-leg execution bounds

For buys, the service verifies previewMint against active reserves and outstanding supply, then fits a bounded share quantity to the ETH budget. limitAmount is the estimated cost plus 0.5%, rounded up, and must fit within amount. Unsubmitted budget stays in the wallet; the router refunds unused submitted ETH. Gas is additional.

For sells, quantities match previewRedeem rounding and limitAmount is estimated proceeds less 0.5%, rounded down. Individual zero-output components use empty routes; aggregate output must remain positive. Trades require supported registered backing, executable constituent routes, and no shared pools across nonzero legs.

Pool discovery

GET /v1/liquidity/pools?basket=<address> queries the configured factory directly rather than waiting for the basket index or token directory.

A configured response contains enabled, ready, chainId, basket, settings, quotedBlock, quoteTokens, and pools. Quote-token metadata includes address, symbol, and decimals. Each pool entry contains:

address (nullable), basket, quoteToken, fee, token0, token1,
status, executable, sqrtPriceX96, liquidity, sharesBalance, quoteBalance

status is missing, uninitialized, unfunded, or active. executable reports whether small bounded buy/sell probes passed; it is not a promise that any trade amount will succeed. The pool list can include missing fee-tier/token combinations.

Check an extra pool-funding budget

POST /v1/liquidity/funding/quote needs no existing basket or allowance:

{
  "quoteToken": "0x2222222222222222222222222222222222222222",
  "amountIn": "10000000000000000"
}

The token must appear in liquidity.quoteTokens. A wrapped-native quote is exact wrapping with path: "0x"; another configured quote token needs an executable ETH conversion route.

The response contains all liquidity settings, quoteToken, quoteTokenMetadata, amountIn, expectedOut, minOut, path, scalar priceImpactBps, quotedBlock, quotedAt, expiresAt, deadline, and slippageBps. It checks present feasibility. After creation, obtain a fresh full liquidity quote.

Add full-range liquidity

POST /v1/liquidity/quote combines existing caller-owned basket shares and an ETH budget:

{
  "basket": "0x1111111111111111111111111111111111111111",
  "account": "0x3333333333333333333333333333333333333333",
  "shares": "100000000000000000",
  "amountIn": "10000000000000000",
  "quoteToken": "0x2222222222222222222222222222222222222222",
  "fee": 3000
}

Account, shares, funding amount, supported quote token, and fee tier are required. The service checks wallet balances and registered basket backing, including balances covering active reserves plus pending claims. It does not submit an approval.

The response includes all liquidity settings and the following groups:

Fields	Meaning
basket, account, receiver, quoteToken, fee, amountIn	Request/receiver bindings
sharesDesired, sharesUsed, sharesMin, sharesRefund	Share-side funding and limits
quoteDesired, quoteUsed, quoteMin, quoteRefund	Quote-token funding and limits
minQuoteOut, quotePath	ETH conversion bound and route
minLiquidity, expectedLiquidity	LP liquidity bounds
sqrtPriceX96, minSqrtPriceX96, maxSqrtPriceX96	Initial/current price and permitted interval
pool, poolExists, token0, token1	Pool identity; address can be null before creation
tickLower, tickUpper, tickSpacing	Full-range position parameters
reference	kind: "underlying-redemption", shares, ethValue, quoteValue, and explanatory meaning
Quote timestamps, deadline, slippage, scalar priceImpactBps	Freshness and conversion execution limits

The price reference estimates redemption proceeds from actual backing and pre-funding pool prices. Existing pool prices more than 5% away are rejected. This is not an external oracle or guaranteed NAV; funding itself can move the reference. The helper sends the LP NFT to the receiver. Unused wrapped native is refunded as ETH; another unused quote token remains that token.

Trade existing shares through a pool

POST /v1/liquidity/trade/quote accepts { basket, side, amount, account? }. Buy amounts are raw ETH; sell amounts are existing basket shares. An optional account adds balance checks and response account/receiver bindings. The frontend requires an account before execution.

Responses include all liquidity settings, basket, side, optional account and receiver, amountIn, expectedOut, minOut, path, pool, quoteToken, fee, timestamps, deadline, slippage, and scalar priceImpactBps. Output is shares for a buy or ETH for a sell. Supported routes are direct wrapped-native/share swaps or two-hop routes through a configured quote token.

ERC-20 settlement

POST /v1/liquidity/token-trade/quote accepts:

{
  "basket": "0x1111111111111111111111111111111111111111",
  "side": "buy",
  "amount": "1000000",
  "settlementToken": "0x2222222222222222222222222222222222222222",
  "account": "0x3333333333333333333333333333333333333333"
}

account is optional for quoting. A buy amount uses the settlement token’s raw units; a sell amount uses raw basket shares. Amounts must be positive and below 2^255. The settlement token must be a configured non-wrapped quote token, and router02 must be true.

The response has the ETH pool-trade fields plus executor: "dex-router", settlementToken, and settlementTokenMetadata. It uses direct settlement-token/share pools or two-hop routes through wrapped native. The service verifies a deadline-enforcing Router02 multicall at the quote block.

Execution approves the actual input token to the DEX router and sends zero ETH value for the swap. ETH is still required for gas. The ETH liquidity helper is not the spender for this flow.

Validate before asking for a wallet transaction

Use the application’s quote validators as the integration reference. Check the request, chain, complete deployment settings, ordered tokens, route endpoints, amounts, fee split, recipient, and expiry. Recheck after approvals and immediately before submission. A quote that expires while an approval is confirming requires a new preview.

Confirm the receipt’s expected event and refresh balances/backing afterward. Preserve submitted transaction hashes for recovery; a timeout is not proof of transaction failure. See wallets and metadata and integration examples.