# 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](#rest-api-off-chain) or use `estimateSwap` on-chain.
2. **Approve the router** for `tokenIn`.
3. **Call `swap`** on the router.

```solidity
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](/liquidcore-integration/api-endpoints.md) reference.

### On-chain estimation

```solidity
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](/liquidcore-integration/referrals.md). 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`

```solidity
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](/liquidcore-integration/overview.md#supported-pairs).

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:

```solidity
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](/liquidcore-integration/referrals.md) 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

```solidity
error NoPoolForPair();
error TransferFailed();
```

### Pool errors

```solidity
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](/liquidcore-integration/api-endpoints.md) — endpoint details, parameters, response shapes
* [Contract Reference](/liquidcore-integration/api-reference.md) — complete router and pool Solidity interfaces


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.liqd.ag/liquidcore-integration/integration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.