Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🌐REST API

REST API for LiquidCore: list pools, get swap quotes, and fetch pool stats.

Base URL: https://api.liqd.ag/liquidcore

All endpoints take chainId (999 = HyperEVM, 4663 = Robinhood Chain).

List pools

GET /liquidcore/pools

Returns all LiquidCore pools on a chain with token pairs, reserves, fees, volume, and pricing data.

Query parameters

Name
Type
Required
Description

chainId

number

yes

999 (HyperEVM) or 4663 (Robinhood Chain)

Examples

GET https://api.liqd.ag/liquidcore/pools?chainId=999
GET https://api.liqd.ag/liquidcore/pools?chainId=4663
Field
Description

chainId

Chain that was queried

poolAddress

Pool contract address

isPublic

Whether the pool is publicly listed

token0, token1

Token metadata: address, symbol, name, decimals

poolFees

Current dynamic fee rates per direction (decimal, e.g. 0.0100 = 1%)

exchangeRates

Spot exchange rates between the two tokens

usdPrices

USD price per token

reserves / reservesUSD

Pool reserves in token units and USD

tvlUSD

Total value locked in the pool

fees24h

Fees collected in the last 24h (token0, token1, USD)

volume24h

Trading volume in the last 24h (token0, token1, USD)

apr

Annualized fee yield as a percentage

totalTVL

Sum of TVL across all pools

totals24h

Aggregate 24h fees and volume across all pools

Get quote

Get on-chain swap quotes from LiquidCore pools, with optional ready-to-broadcast calldata.

Endpoint

GET /liquidcore/quote

Query parameters

Name
Type
Required
Description

chainId

number

yes

999 (HyperEVM) or 4663 (Robinhood Chain)

tokenIn

address (0x…)

yes

Input token address.

tokenOut

address (0x…)

yes

Output token address.

amountIn

uint256 or CSV of uint256

yes

Input amount(s) in base units (raw uint256, no decimals). Pass a comma-separated list for batch quoting (e.g. 1000000,5000000,10000000).

includeCalldata

bool

no

If truthy (anything except false/0/empty), each quote includes minAmountOut and calldata ready to send to the router.

slippageBps

int [0, 10000)

no

Slippage tolerance in basis points used to compute minAmountOut when includeCalldata is set. Default 100 (1%).

refCode

string or bytes32

no

Referral code. If a 32-byte hex string it's used directly; otherwise it's hashed via keccak256 (ethers.utils.id). When present, the calldata uses the 5-arg swap overload.

The endpoint resolves the pool for (tokenIn, tokenOut) on the router and returns a quote per amountIn. If no LiquidCore pool exists for the pair, the endpoint returns 404.

Field notes

  • routerAddress: Contract to send the transaction to for this chainId.

  • chainId: Echoed chain used for the quote.

  • reserveOut: Reserve of the tokenOut side of the pool (base units), useful for price-impact checks.

  • blockNumber / blockTimestamp: Block at which the quote was computed.

  • functionSignature: swap(address,address,uint256,uint256), or the 5-arg overload with bytes32 when refCode is provided.

  • refCode / slippageBps: Echoed in the response only when supplied / applicable. refCode is normalized to a bytes32 hex.

  • quotes[].amountIn, quotes[].amountOut: always returned as base-unit strings.

  • quotes[].minAmountOut, quotes[].calldata: only present when includeCalldata is set. minAmountOut = amountOut * (10000 - slippageBps) / 10000.

Error responses

Status

error

When

400

Missing required parameters: tokenIn, tokenOut, amountIn

A required param is missing.

400

Invalid slippageBps: must be an integer in [0, 10000)

Bad slippageBps when includeCalldata is set.

400

Invalid amountIn: must be a raw uint256 (base units) or comma-separated list

Non-integer or unparseable amounts.

400

Invalid address: <param>

tokenIn or tokenOut is not a valid address.

404

No LiquidCore pool found for this token pair

Router returns zero address or reverts.

500

Failed to fetch quote (or error message)

Unexpected server error.

All errors share the shape { success: false, error: "<message>" }.

Examples

HyperEVM quote:

Robinhood Chain quote:

Batch quote:

Quote with calldata (2% slippage) and referral code:

Executing the swap

Send the returned calldata as transaction data to routerAddress. The router swap functions (see Contract Reference):

The caller must first approve the router to spend amountIn of tokenIn.

Get pool data

GET /liquidcore/pool/:address

Path:

Parameter
Description

address

Pool contract address

Query parameters

Name
Type
Required
Description

chainId

number

yes

999 (HyperEVM) or 4663 (Robinhood Chain)

Example

Use a poolAddress from GET /liquidcore/pools?chainId=....

Field
Description

chainId

Chain that was queried

poolAddress

Pool contract address

isPublic

Whether the pool is publicly listed

reserves

Per-token reserves with address, symbol, decimals, amount, usd, and totalUSD

volumeToday / feesToday

Rolling 24h volume and fees (token0, token1, USD)

poolFees

Current dynamic fee rates per direction (decimal)

price

Exchange rates and USD prices for both tokens

apr

Annualized fee yield as a percentage

swapsToday / totalSwaps

Swap counts (rolling 24h and all-time)

lastUpdated

Unix timestamp of last data refresh

PreviousIntegration Guide
NextContract Reference

Last updated