🔌Integration Guide

How to integrate LiquidCore swaps into your product. LiquidCore supports aggregators, wallets, trading UIs, and other DeFi products on Hyperliquid.

Quick start

1. Get a quote — call the REST API or use estimateSwap on-chain.

2. Approve the router for tokenIn.

3. Call swap on the router.

swap(tokenIn, tokenOut, amountIn, minAmountOut)

That's it. The router discovers the correct pool automatically — no need to track pool addresses or update code when new pools are added.

Getting quotes

REST API (off-chain)

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

Endpoint	Description
GET /liquidcore/pools	List all pools with token pairs and metadata
GET /liquidcore/quote	Get swap quotes (single or batch via comma-separated amountIn)
GET /liquidcore/pool/:address	Pool stats (reserves, volume, fees, APR)

The quote endpoint can return ready-to-broadcast calldata when includeCalldata=true is set. Full request/response details in the REST API reference.

On-chain estimation

function estimateSwap(
    address tokenIn,
    address tokenOut,
    uint256 amountIn
) external view returns (uint256 amountOut)

Available on both the router and individual pool contracts. Use this for on-chain previews; use the REST API for off-chain routing.

Do not replicate pricing locally

LiquidCore is a proprietary AMM design that is still in active development. The pricing and fee formulas depend on Hyperliquid oracle data that updates every block and on current pool state — there is no static formula you can snapshot and reuse.

Because the contracts are upgraded frequently as the product evolves, any attempt to replicate the math in your own adapter will drift out of sync and produce incorrect quotes. Always use the quote API or on-chain estimate functions as your source of truth. They execute against the live contract with the latest oracle state and are the only way to get accurate pricing.

If your architecture strictly requires local price replication, reach out to the team — this can be discussed on a case-by-case basis with approved partners.

Integrators who route volume through LiquidCore can earn revenue via the referral program. Pass your allowlisted refCode in swaps and claim accrued fees on-chain — no additional integration work beyond adding the 5th parameter.

Executing swaps

Via the router (recommended)

Router address: 0x625aC1D165c776121A52ff158e76e3544B4a0b8B

function swap(
    address tokenIn,
    address tokenOut,
    uint256 amountIn,
    uint256 minAmountOut
) external returns (uint256 amountOut)

Parameter	Type	Description
tokenIn	address	Token being sold
tokenOut	address	Token being bought
amountIn	uint256	Amount of tokenIn to swap
minAmountOut	uint256	Minimum acceptable output (slippage protection)

Returns: actual amount of tokenOut received.

The quote API returns this router as routerAddress and can include the calldata for the swap directly.

Via direct pool calls (alternative)

If you already know the pool address, you can call swap on the pool contract directly. Same parameters as above — approve the pool (not the router) for tokenIn. Pool addresses are listed in the Overview.

This works but requires updating your code when new pools are added; the router avoids that.

Referral-aware swaps

Both the router and pool contracts support a referral overload:

swap(tokenIn, tokenOut, amountIn, minAmountOut, refCode)

Pass an allowlisted refCode as the 5th parameter. Invalid codes don't block the swap — they just don't accrue referral allocation. See Referrals for how to get a code, the bytes32 format, and how to claim fees.

Indexing router-mediated swaps

Pools emit Swap / SwapWithRef events with a user field set to msg.sender. For router-mediated swaps, user will be the router address, not the end trader.

To attribute a router-mediated swap to the real trader, resolve it from the transaction's from field (tx.origin) rather than from the event's user field. Direct pool swaps still have user = trader as expected.

Error handling

Router errors

error NoPoolForPair();
error TransferFailed();

Pool errors

error InvalidToken();
error ZeroAmount();
error SlippageExceeded();
error InsufficientReserve();
error TransferFailed();
error InvalidRefCode();
error UnauthorizedRefCodeClaim();
error RefCodeClaimLocked();

Common fixes:

• SlippageExceeded — increase slippage tolerance or reduce trade size

• InsufficientReserve — try a smaller amount

• InvalidToken — verify you're using the correct token addresses for the pool

• InvalidRefCode — the referral code is not registered on-chain

Full references

• REST API — endpoint details, parameters, response shapes

• Contract Reference — complete router and pool Solidity interfaces