> For the complete documentation index, see [llms.txt](https://docs.liqd.ag/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.liqd.ag/liquidcore-integration/integration-guide.md).

# Integration Guide

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

## Quick start

1. **Get a quote** — call the [REST API](#rest-api-off-chain) or use `estimateSwap` on-chain. Pass `chainId`.
2. **Approve the router** for `tokenIn` on that chain.
3. **Call `swap`** on the router (or send the API `calldata` to `routerAddress`).

```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.

## Supported chains

| Chain           | `chainId` | Router                                       |
| --------------- | --------- | -------------------------------------------- |
| HyperEVM        | `999`     | `0x625aC1D165c776121A52ff158e76e3544B4a0b8B` |
| Robinhood Chain | `4663`    | `0x322F277BfB7Ba9c196194ad18011377A0fF55Fb3` |

Always prefer the `routerAddress` from the quote response.

## Getting quotes

### REST API (off-chain)

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

| Endpoint                                 | Description                                                      |
| ---------------------------------------- | ---------------------------------------------------------------- |
| `GET /liquidcore/pools?chainId=`         | List pools with token pairs and metadata                         |
| `GET /liquidcore/quote?chainId=`         | Get swap quotes (single or batch via comma-separated `amountIn`) |
| `GET /liquidcore/pool/:address?chainId=` | 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. Pricing and fee formulas depend on live oracle data and 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)

Use the router for the chain you are trading on (see table above), or the `routerAddress` from the quote API.

```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`. Discover pool addresses via [`GET /liquidcore/pools?chainId=...`](/liquidcore-integration/api-endpoints.md#list-pools).

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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.