# Welcome to Liquid Labs

### DeFi Infrastructure

Liquid Labs builds core DeFi infrastructure — an oracle-validated AMM, a multichain swap aggregator, and a token launch platform. Everything is open: no API keys, no rate limits, and no forced fees. These docs cover integration for all three products.

## Our Products

### LiquidCore — Oracle-Based AMM

LiquidCore is an oracle-validated AMM live on HyperEVM and Robinhood Chain, delivering predictable execution with tight spreads. It's one of the most modern AMM designs on any EVM.

Integrate through a single **Router** contract per chain (automatic pool discovery — your code doesn't change when new pools are added) and a **REST API** for quotes, pool data, and ready-to-broadcast calldata. Pass `chainId` on all API requests (`999` = HyperEVM, `4663` = Robinhood Chain).

**Routers:** HyperEVM `0x625aC1D165c776121A52ff158e76e3544B4a0b8B` · Robinhood Chain `0x322F277BfB7Ba9c196194ad18011377A0fF55Fb3`

List pools via [`GET /liquidcore/pools?chainId=...`](/liquidcore-integration/api-endpoints#list-pools).

### LiquidSwap — Multichain Aggregator

LiquidSwap finds the best swap route across liquidity on supported chains. It supports multi-hop routing through intermediate tokens, exact-input and exact-output swaps, native token unwrapping, and optional revenue sharing — all through a single API call. Pass `chainId` on route, tokens, balances, pools, and liquidity-source requests (`999` = HyperEVM, `4663` = Robinhood Chain).

**Routers:** HyperEVM `0x744489ee3d540777a66f2cf297479745e0852f7a` · Robinhood Chain `0xfc020bBCe0365f56bbBb78Ce504cE2a2b24E0ae6`

Prefer the `execution.to` address from the route response when executing.

### LiquidLaunch — Token Launchpad

LiquidLaunch lets anyone create and launch an ERC20 token with automated bonding curve trading. Tokens trade on an x × y = k curve with virtual liquidity — no seed capital required. Built-in anti-sniper protection gives creators first access, and all launched tokens are immediately routable through LiquidSwap so users can buy and sell with any supported token, not just HYPE.

***

## Get started

* [LiquidCore](/liquidcore-integration/overview) — oracle-based AMM: router integration, REST API, and contract reference
* [LiquidSwap](/liquidswap-integration/overview) — multichain aggregator: route finding, execution, and pool discovery
* [LiquidLaunch](/liquidlaunch-integration/overview) — token launchpad: token creation, bonding curve trading, and contract reference


# Overview

LiquidCore is an oracle-validated AMM live on HyperEVM and Robinhood Chain. It provides deep, liquid markets with predictable execution and tight spreads.

Ready to integrate? Start with the [Integration Guide](/liquidcore-integration/integration-guide).

## Supported chains

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

On HyperEVM, pricing uses Hyperliquid precompiles. Prefer the `routerAddress` returned by the [quote API](/liquidcore-integration/api-endpoints#get-quote) when executing.

## Pools

Do not hardcode pool addresses — they differ by chain and change over time. List pools from the API:

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

Each entry includes `poolAddress`, token metadata, reserves, fees, volume, and APR. Full response shape is in the [REST API](/liquidcore-integration/api-endpoints#list-pools) reference.

For swaps, use the **router** — it discovers the correct pool automatically, so your integration does not need to track pool addresses.


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


# 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:

```
GET https://api.liqd.ag/liquidcore/quote
  ?chainId=999
  &tokenIn=0xb88339CB7199b77E23DB6E890353E22632Ba630f
  &tokenOut=0x5555555555555555555555555555555555555555
  &amountIn=1000000
```

Robinhood Chain quote:

```
GET https://api.liqd.ag/liquidcore/quote
  ?chainId=4663
  &tokenIn=0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73
  &tokenOut=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168
  &amountIn=1000000000000000
```

Batch quote:

```
GET https://api.liqd.ag/liquidcore/quote?chainId=999&tokenIn=0x...&tokenOut=0x...&amountIn=1000000,5000000,10000000
```

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

```
GET https://api.liqd.ag/liquidcore/quote
  ?chainId=999
  &tokenIn=0x...
  &tokenOut=0x...
  &amountIn=1000000000000000000
  &includeCalldata=true
  &slippageBps=200
  &refCode=myapp
```

**Executing the swap**

Send the returned `calldata` as transaction data to `routerAddress`. The router swap functions (see [Contract Reference](/liquidcore-integration/api-reference#router)):

```solidity
function swap(address tokenIn, address tokenOut, uint256 amountIn, uint256 minAmountOut) external returns (uint256);
function swap(address tokenIn, address tokenOut, uint256 amountIn, uint256 minAmountOut, bytes32 refCode) external returns (uint256);
```

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**

```
GET https://api.liqd.ag/liquidcore/pool/0x...?chainId=999
```

Use a `poolAddress` from [`GET /liquidcore/pools?chainId=...`](#list-pools).

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


# Contract Reference

Solidity interfaces for the LiquidCore Router and pool contracts.

Use the **Router** for execution. Direct pool calls are optional when you already know the pool address.

## Router

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

Prefer the `routerAddress` returned by the [quote API](/liquidcore-integration/api-endpoints#get-quote).

### Discovery functions

```solidity
function getPools() external pure returns (address[] memory pools)
function getPoolForPair(address tokenA, address tokenB) public view returns (address)
```

Off-chain, list pools with [`GET /liquidcore/pools?chainId=...`](/liquidcore-integration/api-endpoints#list-pools).

### Execution functions

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

```solidity
function swap(
    address tokenIn,
    address tokenOut,
    uint256 amountIn,
    uint256 minAmountOut,
    bytes32 refCode
) external returns (uint256 amountOut)
```

`refCode` is checked against an on-chain allowlist (`RefCodeRegistry`). Invalid codes do not accrue referral allocation and do not block the swap.

### Quote functions

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

function estimateSwapBatch(
    address tokenIn,
    address tokenOut,
    uint256[] calldata amountsIn
) external view returns (uint256[] memory amountsOut)

function getReserves(address tokenA, address tokenB)
    external view returns (uint256 reserve0, uint256 reserve1)
```

`estimateSwapBatch` is used by the [REST API quote endpoint](/liquidcore-integration/api-endpoints#get-quote) for CSV `amountIn` inputs. `getReserves` reverts with `NoPoolForPair` if no pool exists.

### Referral functions

```solidity
function getRefClaimable(address tokenA, address tokenB, bytes32 refCode)
    external view returns (uint256 amount0, uint256 amount1)

function claimRefFees(address tokenA, address tokenB, bytes32 refCode)
    external returns (uint256 amount0, uint256 amount1)

function distributeRefFees() external
```

See [Referrals](/liquidcore-integration/referrals) for usage details.

### Router errors

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

***

## Direct pool interface

Discover pool addresses via [`GET /liquidcore/pools?chainId=...`](/liquidcore-integration/api-endpoints#list-pools). Do not hardcode them — they differ by chain and change over time.

```solidity
function getTokens() external view returns (address token0, address token1)
function getReserves() external view returns (uint256 reserve0, uint256 reserve1)
function swap(address tokenIn, address tokenOut, uint256 amountIn, uint256 minAmountOut) external returns (uint256 amountOut)
function swap(address tokenIn, address tokenOut, uint256 amountIn, uint256 minAmountOut, bytes32 refCode) external returns (uint256 amountOut)
function estimateSwap(address tokenIn, address tokenOut, uint256 amountIn) external view returns (uint256 amountOut)
function estimateSwapBatch(address tokenIn, address tokenOut, uint256[] calldata amountsIn) external view returns (uint256[] memory amountsOut)
function getRefClaimable(bytes32 refCode) external view returns (uint256 amount0, uint256 amount1)
function claimRefFees(bytes32 refCode) external returns (uint256 amount0, uint256 amount1)
```

### Common direct-pool errors

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

Referral usage details are documented in [Referrals](/liquidcore-integration/referrals).


# Referrals

Integrator guide for using a referral code and checking/claiming referral fees.

LiquidCore is live on HyperEVM (`999`) and Robinhood Chain (`4663`). Use the router for the chain you are trading on — see the [router table](/liquidcore-integration/overview#supported-chains), or the `routerAddress` from the [quote API](/liquidcore-integration/api-endpoints#get-quote). Claims must be made on the same chain where the fees accrued.

## Get a code

Referral codes are issued by Liquid Labs. Request your code from the team on Discord.

## Ref code format

`refCode` is a `bytes32` hash, not a plain text string.

It should be the keccak256 hash of your issued code text (for example, hash `"mycode"` and pass that `bytes32` value on-chain).

Example in ethers:

```typescript
import { keccak256, toUtf8Bytes } from "ethers";

const refCode = keccak256(toUtf8Bytes("your-issued-code"));
```

## Use your code in swaps

Router and pool both support the referral swap overload:

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

* Keep your normal execution flow the same (`minAmountOut`, approvals, quote/estimate checks).
* Use your issued `refCode` as the 5th parameter.

## Check and claim referral fees

The core referral functions are available on the **router** — pass the token pair and the router resolves the pool automatically.

### Via the router (recommended)

```solidity
function getRefClaimable(address tokenA, address tokenB, bytes32 refCode)
    external view returns (uint256 amount0, uint256 amount1)

function claimRefFees(address tokenA, address tokenB, bytes32 refCode)
    external returns (uint256 amount0, uint256 amount1)

function distributeRefFees() external
```

* `getRefClaimable` — check currently claimable amounts per pool token.
* `claimRefFees` — claim accrued fees for a specific ref code. Must be called by the configured claim wallet for that code.
* `distributeRefFees` — batch-distributes all pending referral fees across all pools. Iterates over every registered ref code and pays out accrued fees to each code's configured claim wallet. Anyone can call this.

### Via pool contracts (alternative)

`getRefClaimable` and `claimRefFees` are also available directly on pool contracts (without the `tokenA`/`tokenB` pair parameters). See the [Contract Reference](/liquidcore-integration/api-reference#direct-pool-interface) for pool-level signatures.


# Overview

LiquidSwap is a multichain aggregator. It finds optimal swap routes across liquidity on supported chains, with built-in multi-hop routing, revenue sharing, and native token unwrapping.

## Supported chains

| Chain           | `chainId` |
| --------------- | --------- |
| HyperEVM        | `999`     |
| Robinhood Chain | `4663`    |

Pass `chainId` on [route](/liquidswap-integration/route-finding), [tokens](/liquidswap-integration/token-list), [token balances](/liquidswap-integration/token-balances), [liquidity sources](/liquidswap-integration/dexes), and [pools](/liquidswap-integration/find-pools) requests.

## Quick start

1. **Get a route** — call `GET https://api.liqd.ag/v2/route` with `tokenIn`, `tokenOut`, `amountIn`, and `chainId`.
2. **Execute** — send the returned `calldata` to the contract address in `execution.to`.

```javascript
const route = await fetch(
  'https://api.liqd.ag/v2/route?tokenIn=0x555...&tokenOut=0xB8C...&amountIn=100&chainId=999'
).then(r => r.json());

const tx = await signer.sendTransaction({
  to: route.execution.to,
  data: route.execution.calldata,
});
```

That's it. No API keys, no registration, no rate limits.

## Key features

* **No authentication** — start calling endpoints immediately
* **No rate limits** — scale without worrying about quotas or throttling
* **Multichain** — same API across HyperEVM and Robinhood Chain via `chainId`
* **Multi-hop routing** — set `multiHop=true` to route through intermediate tokens
* **Exact input or output** — provide `amountIn` for exact input swaps, or `amountOut` for exact output
* **Native unwrapping** — set `unwrapNative=true` to receive native HYPE (HyperEVM) or ETH (Robinhood Chain) instead of the wrapped token

## Revenue sharing

LiquidSwap charges no forced fees for API usage. You choose your own fee structure:

* **Custom fees** — set `feeBps` (up to 100 = 1%) and `feeRecipient` on route requests. You keep 97.5% of collected fees; 2.5% goes to protocol.
* **Positive slippage** — when swaps execute better than quoted, 50% of positive slippage is captured. If `feeRecipient` is set, half goes to you and half to protocol. Set `feeBps=0` with a `feeRecipient` to earn positive slippage without charging users.
* **Zero-fee option** — omit `feeBps` and `feeRecipient` to operate completely fee-free.

## API endpoints

| Endpoint                                                                  | Description                                                 |
| ------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [`GET /v2/route?chainId=`](/liquidswap-integration/route-finding)         | Find optimal swap routes with ready-to-use calldata         |
| [`GET /dexes?chainId=`](/liquidswap-integration/dexes)                    | List liquidity sources and `routerIndex` values for a chain |
| [`GET /pools?chainId=`](/liquidswap-integration/find-pools)               | Discover pools for a token pair                             |
| [`GET /tokens?chainId=`](/liquidswap-integration/token-list)              | List tracked tokens with metadata                           |
| [`GET /tokens/balances?chainId=`](/liquidswap-integration/token-balances) | Get token balances for a wallet                             |

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

## Contracts

| Chain                    | RouterV2                                     |
| ------------------------ | -------------------------------------------- |
| HyperEVM (`999`)         | `0x744489ee3d540777a66f2cf297479745e0852f7a` |
| Robinhood Chain (`4663`) | `0xfc020bBCe0365f56bbBb78Ce504cE2a2b24E0ae6` |

Always prefer the `execution.to` address from the route response. See [Execution](/liquidswap-integration/execution) for full details.


# Route Finding

`GET https://api.liqd.ag/v2/route`

Calculates optimal swap routes across available liquidity. Returns token metadata, quoted amounts, and ready-to-use calldata for [execution](/liquidswap-integration/execution).

## Parameters

### Required Parameters

| Name        | Type    | Description                                                      | Required | Example                                      |
| ----------- | ------- | ---------------------------------------------------------------- | -------- | -------------------------------------------- |
| `tokenIn`   | address | Contract address of the input token (0x format)                  | Yes      | `0x5555555555555555555555555555555555555555` |
| `tokenOut`  | address | Contract address of the output token (0x format)                 | Yes      | `0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb` |
| `amountIn`  | number  | Amount of input token (human readable, e.g., 100 for 100 tokens) | Yes\*    | `1000`                                       |
| `amountOut` | number  | Desired output amount (human readable, for exact output swaps)   | Yes\*    | `50000`                                      |
| `chainId`   | number  | Chain to route on (`999` = HyperEVM, `4663` = Robinhood Chain)   | Yes      | `999`                                        |

**Note**: Provide either `amountIn` OR `amountOut`, not both.

### Optional Parameters

| Name           | Type    | Description                                                                   | Default | Example     |
| -------------- | ------- | ----------------------------------------------------------------------------- | ------- | ----------- |
| `multiHop`     | boolean | Enable multi-hop routing through intermediate tokens                          | false   | `true`      |
| `slippage`     | number  | Slippage tolerance as percentage (0.1-5.0 recommended)                        | 1.0     | `0.5`       |
| `unwrapNative` | boolean | Unwrap to native token (HYPE on HyperEVM, ETH on Robinhood Chain)             | false   | `true`      |
| `excludeDexes` | string  | Comma-separated `routerIndex` values to exclude from routing                  | none    | `1,3`       |
| `includeDexes` | string  | Comma-separated `routerIndex` values to include only (overrides excludeDexes) | none    | `1,2`       |
| `feeBps`       | number  | Your fee in basis points (100 = 1%, max 100) — you keep 97.5% of this         | 0       | `50`        |
| `feeRecipient` | address | Wallet to receive fee payments and positive slippage                          | none    | `0xaC7d...` |

Resolve `routerIndex` values via [`GET /dexes?chainId=...`](/liquidswap-integration/dexes).

## Example Requests

**HyperEVM exact input:**

```
GET https://api.liqd.ag/v2/route?tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=100&chainId=999
```

**Robinhood Chain exact input:**

```
GET https://api.liqd.ag/v2/route?tokenIn=0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73&tokenOut=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168&amountIn=0.01&chainId=4663
```

**Multi-hop with custom slippage:**

```
GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=100&slippage=1.5&chainId=999
```

**Exact output with native unwrapping:**

```
GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&tokenOut=0x5555555555555555555555555555555555555555&amountOut=100&unwrapNative=true&chainId=999
```

**Exclude specific sources:**

```
GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=100&excludeDexes=1,3&chainId=999
```

**Include only specific sources:**

```
GET https://api.liqd.ag/v2/route?tokenIn=0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73&tokenOut=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168&amountIn=0.01&includeDexes=1,2&chainId=4663
```

**With revenue sharing (0.1% fee):**

```
GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=69&feeBps=10&feeRecipient=0xaC7d51dB236fae22Ceb6453443da248F3A53f94d&chainId=999
```

## Response Fields

| Field                                      | Description                                                       |
| ------------------------------------------ | ----------------------------------------------------------------- |
| `success`                                  | Whether a route was found                                         |
| `tokens.tokenIn` / `tokens.tokenOut`       | Token metadata: `address`, `symbol`, `name`, `decimals`           |
| `tokens.intermediates`                     | Intermediate tokens for multi-hop routes (empty for direct swaps) |
| `amountIn` / `amountOut`                   | Human-readable amounts                                            |
| `averagePriceImpact`                       | Overall price impact across the route                             |
| `execution.to`                             | RouterV2 address for this chain — send the transaction here       |
| `execution.calldata`                       | Ready-to-use transaction data                                     |
| `execution.details.path`                   | Token addresses in the swap path                                  |
| `execution.details.amountIn` / `amountOut` | Amounts in base units                                             |
| `execution.details.minAmountOut`           | Minimum output after slippage (base units)                        |
| `execution.details.hopSwaps`               | Per-hop routing breakdown (array of parallel swap arrays)         |

### `hopSwaps[][]` fields

| Field                        | Description                                                                               |
| ---------------------------- | ----------------------------------------------------------------------------------------- |
| `tokenIn` / `tokenOut`       | Token addresses for this leg                                                              |
| `poolAddress`                | Pool used for this leg                                                                    |
| `routerIndex` / `routerName` | Liquidity source — indexes from [`GET /dexes?chainId=...`](/liquidswap-integration/dexes) |
| `fee`                        | Pool fee (when applicable)                                                                |
| `stable`                     | Whether a stable pool is used (when applicable)                                           |
| `data`                       | Opaque per-pool data blob (may be `0x`)                                                   |
| `amountIn` / `amountOut`     | Amounts for this leg in base units                                                        |
| `priceImpact`                | Price impact for this leg                                                                 |


# Execution

Execute swaps by sending the ready-to-use `calldata` from the [route finding](/liquidswap-integration/route-finding) API to the `RouterV2` contract. That calldata encodes a call to `executeSwaps` or `executeSwapsWithData`.

Always use the `execution.to` address from the route response.

| Chain                    | RouterV2                                     |
| ------------------------ | -------------------------------------------- |
| HyperEVM (`999`)         | `0x744489ee3d540777a66f2cf297479745e0852f7a` |
| Robinhood Chain (`4663`) | `0xfc020bBCe0365f56bbBb78Ce504cE2a2b24E0ae6` |

## Using Calldata from the Route API

```javascript
const response = await fetch(
  'https://api.liqd.ag/v2/route?tokenIn=0x5555...&tokenOut=0xB8CE...&amountIn=100&chainId=999'
);
const routeData = await response.json();

if (routeData.success && routeData.execution) {
  const transaction = {
    to: routeData.execution.to,
    data: routeData.execution.calldata,
    value: 0, // set if swapping from the chain's native token
  };

  const result = await signer.sendTransaction(transaction);
}
```

Fees and positive slippage are already encoded in the calldata when you pass `feeBps` / `feeRecipient` on the route request. See [Revenue Sharing](/liquidswap-integration/overview#revenue-sharing).

## executeSwaps

Primary execution function. Provides positive slippage capture (50% capture rate) and custom fee collection:

```solidity
function executeSwaps(
    address[] calldata tokens,
    uint256 amountIn,
    uint256 minAmountOut,
    uint256 expectedAmountOut,
    Swap[][] calldata hopSwaps,
    uint256 feeBps,
    address feeRecipient
) external payable nonReentrant returns (uint256 userAmountOut)
```

| Name                | Type       | Description                                  |
| ------------------- | ---------- | -------------------------------------------- |
| `tokens`            | address\[] | Token addresses representing the swap path   |
| `amountIn`          | uint256    | Amount of input tokens to swap               |
| `minAmountOut`      | uint256    | Minimum output (slippage protection)         |
| `expectedAmountOut` | uint256    | Expected output (used for positive slippage) |
| `hopSwaps`          | Swap\[]\[] | Swap configurations for each hop             |
| `feeBps`            | uint256    | Fee in basis points (capped at 100 = 1%)     |
| `feeRecipient`      | address    | Receives 97.5% of the fee (2.5% to protocol) |

```solidity
struct Swap {
    address tokenIn;
    address tokenOut;
    uint8 routerIndex;
    uint24 fee;
    uint256 amountIn;
    bool stable;
}
```

## executeSwapsWithData

Same fee and slippage model as `executeSwaps`, but each hop can carry an opaque per-pool `data` blob for sources that need more than `(fee, stable)` to identify a pool. Legs with empty `data` behave like legacy `Swap` legs.

```solidity
function executeSwapsWithData(
    address[] calldata tokens,
    uint256 amountIn,
    uint256 minAmountOut,
    uint256 expectedAmountOut,
    SwapV2[][] calldata hopSwaps,
    uint256 feeBps,
    address feeRecipient
) external payable nonReentrant returns (uint256 userAmountOut)
```

```solidity
struct SwapV2 {
    address tokenIn;
    address tokenOut;
    uint8 routerIndex;
    uint24 fee;
    uint256 amountIn;
    bool stable;
    bytes data;
}
```

You do not need to call these functions manually — use the returned `execution.calldata` instead.

## Native Token Unwrapping

Set `unwrapNative=true` on the route request to receive the chain's native token instead of its wrapped form — HYPE on HyperEVM, ETH on Robinhood Chain. The returned calldata handles unwrapping automatically in the same transaction.

When unwrapping is enabled, the final output token in the path is the dead address `0x000000000000000000000000000000000000dEaD`, which `RouterV2` treats as the native token.


# Liquidity Sources

`GET https://api.liqd.ag/dexes`

Returns the liquidity sources available on a chain, including each source's `routerIndex` for use with `excludeDexes` / `includeDexes` on [route finding](/liquidswap-integration/route-finding) and [find pools](/liquidswap-integration/find-pools).

Indexes and sources vary by chain and may change over time — always query this endpoint rather than hardcoding values.

### Required Parameters

| Name      | Type   | Description                                                 | Required | Example |
| --------- | ------ | ----------------------------------------------------------- | -------- | ------- |
| `chainId` | number | Chain to query (`999` = HyperEVM, `4663` = Robinhood Chain) | Yes      | `4663`  |

**Example Requests:**

```
GET https://api.liqd.ag/dexes?chainId=999
GET https://api.liqd.ag/dexes?chainId=4663
```

### Response Fields

| Field                   | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `chainId`               | Chain that was queried                           |
| `simulatorAddress`      | Simulator contract for the chain                 |
| `data[].routerIndex`    | Index to pass in `excludeDexes` / `includeDexes` |
| `data[].name`           | Display name of the liquidity source             |
| `data[].key`            | Stable identifier for the source                 |
| `data[].adapterAddress` | Adapter contract address                         |
| `count`                 | Number of sources returned                       |


# Find Pools

Returns all pools that contain a specific token pair. Useful for discovering available liquidity and analyzing market depth.

**Endpoint:** `GET https://api.liqd.ag/pools`

**Authentication**: None required — publicly accessible

**Rate Limits**: No rate limits

### Required Parameters

| Name      | Type    | Description                                                 | Required | Example     |
| --------- | ------- | ----------------------------------------------------------- | -------- | ----------- |
| `tokenA`  | address | Address of the first token                                  | Yes      | `0x5555...` |
| `tokenB`  | address | Address of the second token                                 | Yes      | `0xB8CE...` |
| `chainId` | number  | Chain to query (`999` = HyperEVM, `4663` = Robinhood Chain) | Yes      | `999`       |

### Optional Parameters

| Name           | Type   | Description                                          | Default |
| -------------- | ------ | ---------------------------------------------------- | ------- |
| `excludeDexes` | string | Comma-separated `routerIndex` values to exclude      | none    |
| `includeDexes` | string | Comma-separated `routerIndex` values to include only | none    |

Resolve `routerIndex` values via [`GET /dexes?chainId=...`](/liquidswap-integration/dexes).

**Parameter Details:**

* **tokenA & tokenB**: Order doesn't matter — the API finds pools containing both tokens either way
* **excludeDexes** / **includeDexes**: Filter by liquidity source. Cannot be used together — use one or the other

**Example Requests:**

```
# HyperEVM
GET https://api.liqd.ag/pools?tokenA=0x5555555555555555555555555555555555555555&tokenB=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&chainId=999

# Robinhood Chain
GET https://api.liqd.ag/pools?tokenA=0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73&tokenB=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168&chainId=4663

# Exclude specific sources
GET https://api.liqd.ag/pools?tokenA=0x5555555555555555555555555555555555555555&tokenB=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&chainId=999&excludeDexes=1,3

# Include only specific sources
GET https://api.liqd.ag/pools?tokenA=0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73&tokenB=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168&chainId=4663&includeDexes=1,2
```

### Response Fields

| Field                | Description                                                                 |
| -------------------- | --------------------------------------------------------------------------- |
| `success`            | Whether the request succeeded                                               |
| `data[]`             | Array of pools for the pair                                                 |
| `data[].poolAddress` | Pool contract address                                                       |
| `data[].pairedToken` | The other token in the pair relative to the query                           |
| `data[].routerIndex` | Liquidity source index (from [`GET /dexes`](/liquidswap-integration/dexes)) |
| `data[].protocol`    | Liquidity source name                                                       |
| `data[].fee`         | Pool fee                                                                    |
| `data[].stable`      | Whether the pool is a stable pool                                           |
| `data[].pair`        | Human-readable pair symbol                                                  |
| `data[].price`       | Spot price                                                                  |


# Token List

Returns tracked tokens and metadata for a chain.

**Endpoint:** `GET https://api.liqd.ag/tokens`

**Authentication**: None required — publicly accessible

**Rate Limits**: No rate limits

### Required Parameters

| Name      | Type   | Description                                                 | Required | Example |
| --------- | ------ | ----------------------------------------------------------- | -------- | ------- |
| `chainId` | number | Chain to query (`999` = HyperEVM, `4663` = Robinhood Chain) | Yes      | `999`   |

### Optional Parameters

| Name       | Type    | Description                               | Default |
| ---------- | ------- | ----------------------------------------- | ------- |
| `search`   | string  | Filter tokens by address, name, or symbol | none    |
| `limit`    | number  | Maximum number of tokens to return        | none    |
| `offset`   | number  | Pagination offset                         | `0`     |
| `metadata` | boolean | When `"false"`, returns only addresses    | true    |

> **Note:** Tokens are sorted by 24-hour transfer count in descending order.

**Example Requests:**

```
GET https://api.liqd.ag/tokens?chainId=999
GET https://api.liqd.ag/tokens?chainId=4663
GET https://api.liqd.ag/tokens?chainId=999&limit=10
GET https://api.liqd.ag/tokens?chainId=999&offset=10&limit=10
GET https://api.liqd.ag/tokens?chainId=999&search=HYPE
GET https://api.liqd.ag/tokens?chainId=4663&search=WETH
GET https://api.liqd.ag/tokens?chainId=999&metadata=false
```

### Response Fields

| Field                                           | Description                                 |
| ----------------------------------------------- | ------------------------------------------- |
| `success`                                       | Whether the request succeeded               |
| `data.chainId`                                  | Chain that was queried                      |
| `data.tokens`                                   | Token list when `metadata` is not `false`   |
| `data.tokens[].address`                         | Token contract address                      |
| `data.tokens[].name` / `symbol` / `decimals`    | Token metadata                              |
| `data.tokens[].isERC20Verified`                 | Whether the token passed ERC20 verification |
| `data.tokens[].transfers24h` / `totalTransfers` | Transfer activity                           |
| `data.addresses`                                | Address-only list when `metadata=false`     |
| `data.count`                                    | Total matching tokens                       |
| `data.limitedCount`                             | Number returned in this page                |
| `data.offset` / `nextOffset` / `hasMore`        | Pagination                                  |
| `data.searchApplied` / `limitApplied`           | Whether filters were applied                |
| `data.serviceStatus`                            | Indexer status                              |


# Token Balances

Returns token balances for a wallet on a given chain.

**Endpoint:** `GET https://api.liqd.ag/tokens/balances`

**Authentication**: None required — publicly accessible

**Rate Limits**: No rate limits

### Required Parameters

| Name      | Type    | Description                                                 | Required | Example                                      |
| --------- | ------- | ----------------------------------------------------------- | -------- | -------------------------------------------- |
| `wallet`  | address | Wallet to check balances for                                | Yes      | `0x1234567890abcdef1234567890abcdef12345678` |
| `chainId` | number  | Chain to query (`999` = HyperEVM, `4663` = Robinhood Chain) | Yes      | `999`                                        |

### Optional Parameters

| Name    | Type   | Description                        | Default |
| ------- | ------ | ---------------------------------- | ------- |
| `limit` | number | Maximum number of tokens to return | none    |

**Parameter Details:**

* **wallet**: Valid Ethereum-style address (`0x` + 40 hex characters)
* **chainId**: `999` for HyperEVM, `4663` for Robinhood Chain
* **limit**: Useful for top holdings; if omitted, returns all tokens with non-zero balances

**Example Requests:**

```
GET https://api.liqd.ag/tokens/balances?wallet=0x1234567890abcdef1234567890abcdef12345678&chainId=999
GET https://api.liqd.ag/tokens/balances?wallet=0x1234567890abcdef1234567890abcdef12345678&chainId=4663
GET https://api.liqd.ag/tokens/balances?wallet=0x1234567890abcdef1234567890abcdef12345678&chainId=999&limit=10
```

### Response Fields

| Field                                        | Description                   |
| -------------------------------------------- | ----------------------------- |
| `success`                                    | Whether the request succeeded |
| `data.wallet`                                | Wallet that was queried       |
| `data.chainId`                               | Chain that was queried        |
| `data.tokens[]`                              | Non-zero balances             |
| `data.tokens[].token`                        | Token address                 |
| `data.tokens[].balance`                      | Balance in base units         |
| `data.tokens[].name` / `symbol` / `decimals` | Token metadata                |
| `data.count`                                 | Total balances available      |
| `data.limitedCount`                          | Number returned               |
| `data.limitApplied`                          | Whether `limit` was applied   |
| `data.serviceStatus`                         | Indexer status                |


# Overview

LiquidLaunch is a token creation and fair launch platform on Hyperliquid (HyperEVM). Anyone can create an ERC20 token with automated bonding curve trading.

**Contract:** `0xDEC3540f5BA6f2aa3764583A9c29501FeB020030`

## How it works

1. **Create a token** — call `createToken` with metadata. Any HYPE sent with the transaction automatically buys tokens for the creator (anti-snipe).
2. **Trade on the bonding curve** — users buy and sell via `buyTokens` / `sellTokens`. Price adjusts automatically.
3. **Trade via LiquidSwap** — launched tokens are also routable through LiquidSwap on HyperEVM, where users can swap with any supported token (not just HYPE).

## Token specs

| Property               | Value                                   |
| ---------------------- | --------------------------------------- |
| Total supply           | 1,000,000,000 (6 decimals)              |
| Virtual HYPE liquidity | 300 HYPE                                |
| Initial price          | `VIRTUAL_HYPE_LIQUIDITY / TOTAL_SUPPLY` |

All tokens trade on an **x × y = k** constant-product curve against virtual reserves. Price increases as tokens are bought and decreases as they are sold — the same mechanic as Uniswap V2, but with virtual (not deposited) liquidity.

## Bonding

Tokens currently trade exclusively on the LiquidLaunch bonding curve — they do not bond out to an external pool. In a future release, tokens will be able to bond into LiquidLaunch's own Uniswap V2 deployment for deeper liquidity.

## Fees

* **1% on all trades** (deducted from HYPE sent or received)
* **Split:** 50% to token creator, 50% to protocol
* **Claiming:** anyone can call `claimFees(token)` to distribute accumulated fees — only the creator and protocol receive the split, not the caller

## Creator restrictions

Token creators cannot sell for **1 hour** after creation, preventing immediate dumps.


# Creating Tokens

Call `createToken` on the LiquidLaunch contract (HyperEVM) to deploy a new token with bonding curve trading.

**Contract:** `0xDEC3540f5BA6f2aa3764583A9c29501FeB020030`

```solidity
function createToken(
    string memory name,
    string memory symbol,
    string memory image_uri,
    string memory description,
    string memory website,
    string memory twitter,
    string memory telegram,
    string memory discord,
    uint8 dexIndex
) external payable returns (address tokenAddress)
```

## Parameters

| Parameter     | Required | Description                           |
| ------------- | -------- | ------------------------------------- |
| `name`        | yes      | Token name (e.g. "Awesome Coin")      |
| `symbol`      | yes      | Trading symbol (e.g. "AWE")           |
| `image_uri`   | yes      | URL for token logo (IPFS recommended) |
| `description` | yes      | Brief description of the token        |
| `website`     | no       | Project website URL                   |
| `twitter`     | no       | Twitter handle or URL                 |
| `telegram`    | no       | Telegram group/channel link           |
| `discord`     | no       | Discord server link                   |
| `dexIndex`    | yes      | Reserved — use `0`                    |

## Initial buy protection

Any HYPE sent with the `createToken` transaction automatically purchases tokens for the creator before anyone else can buy. This prevents front-running / sniping.

## Creator restrictions

* **1-hour sell lock** — creators cannot sell their tokens for 1 hour after creation


# Trading

Buy and sell tokens on the LiquidLaunch bonding curve. All functions are on the LiquidLaunch contract (`0xDEC3540f5BA6f2aa3764583A9c29501FeB020030`).

## Buying tokens

```solidity
function buyTokens(address token) external payable
```

Send HYPE as `msg.value`. The contract calculates tokens based on the bonding curve, deducts the 1% fee, and transfers tokens to your wallet.

## Selling tokens

```solidity
function sellTokens(address token, uint256 tokenAmount) external
```

Specify how many tokens to sell. You receive HYPE minus the 1% fee. No approval required.

## Estimating trades

Always estimate before trading to understand price impact:

```solidity
function estimateBuy(address token, uint256 hypeAmount) public view returns (uint256)
function estimateSell(address token, uint256 tokenAmount) public view returns (uint256)
```

Both estimates include the 1% fee deduction.

## Checking reserves

```solidity
function getLiquidity(address token) public view returns (uint256 hypeReserve, uint256 tokenReserve)
```

Returns current virtual reserves. Useful for understanding price impact before large trades.

## Full contract reference

All functions, events, data structures, and error codes are documented in the [Contract Reference](/liquidlaunch-integration/api-reference).


# Contract Reference

Complete reference for all LiquidLaunch contract functions, events, and constants.

## Contract Address

* **LiquidLaunch**: `0xDEC3540f5BA6f2aa3764583A9c29501FeB020030`

## Functions

### Token Creation

#### createToken

```solidity
function createToken(
    string memory name,
    string memory symbol,
    string memory image_uri,
    string memory description,
    string memory website,
    string memory twitter,
    string memory telegram,
    string memory discord,
    uint8 dexIndex
) external payable returns (address tokenAddress)
```

Creates a new token with bonding curve trading. Any HYPE sent with this transaction will be automatically used to purchase tokens for the creator as anti-sniper protection. Use `dexIndex` 0.

### Trading Functions

#### buyTokens

```solidity
function buyTokens(address token) external payable
```

Purchase tokens by sending HYPE. 1% fee applies (50/50 split: creator and protocol).

#### sellTokens

```solidity
function sellTokens(address token, uint256 tokenAmount) external
```

Sell tokens back to the bonding curve. 1% fee applies (50/50 split: creator and protocol). No approval required.

### Liquidity & Price Functions

#### getLiquidity

```solidity
function getLiquidity(address token) public view returns (uint256 hypeReserve, uint256 tokenReserve)
```

Get current virtual reserves for a token.

#### estimateBuy

```solidity
function estimateBuy(address token, uint256 hypeAmount) public view returns (uint256)
```

Estimate tokens received for HYPE input (includes 1% fee deduction).

#### estimateSell

```solidity
function estimateSell(address token, uint256 tokenAmount) public view returns (uint256)
```

Estimate HYPE received for token input (includes 1% fee deduction).

### Token Information

#### getTokenMetadata

```solidity
function getTokenMetadata(address token) external view returns (TokenMetadata memory)
```

Get complete token metadata and state.

#### getTokenCreator

```solidity
function getTokenCreator(address tokenAddress) external view returns (address)
```

Get the creator address for a token.

#### getTokenCount

```solidity
function getTokenCount() external view returns (uint256)
```

Get total number of tokens created.

#### getPaginatedTokensWithMetadata

```solidity
function getPaginatedTokensWithMetadata(uint256 start, uint256 limit) 
    external view returns (address[] memory tokens, TokenMetadata[] memory metadata)
```

Get tokens and metadata with pagination.

### Fee Functions

#### claimFees

```solidity
function claimFees(address token) external returns (uint256 whypeReceived)
```

Distributes accumulated fees for a token. **Anyone can call**; only the protocol and the token creator receive the 50/50 split. The caller does not receive fees.

#### previewClaimFees

```solidity
function previewClaimFees(address token) external returns (uint256 whypeAmount, uint256 tokensAmount)
```

Preview fees available for claiming. Must be called using a static call.

#### getClaimedFeesAndBurnedTokens

```solidity
function getClaimedFeesAndBurnedTokens(address token) 
    external view returns (uint256 claimedFees, uint256 burnedTokens)
```

Get total fees claimed and tokens burned for a token.

## Events

### Token Lifecycle

#### TokenCreated

```solidity
event TokenCreated(
    address indexed token,
    address indexed creator,
    string name,
    string symbol,
    string image_uri,
    string description,
    string website,
    string twitter,
    string telegram,
    string discord,
    uint256 creationTimestamp,
    uint256 startingLiquidity,
    uint256 currentHypeReserves,
    uint256 currentTokenReserves,
    uint256 totalSupply,
    uint256 currentPrice,
    uint256 initialPurchaseAmount
);
```

### Trading Events

#### TokensPurchased

```solidity
event TokensPurchased(
    address indexed token,
    address indexed buyer,
    uint256 hypeIn,
    uint256 tokensOut,
    uint256 price,
    uint256 timestamp,
    uint256 hypeReserves,
    uint256 tokenReserves,
    uint256 totalSupply,
    string name,
    string symbol
);
```

#### TokensSold

```solidity
event TokensSold(
    address indexed token,
    address indexed seller,
    uint256 tokensIn,
    uint256 hypeOut,
    uint256 price,
    uint256 timestamp,
    uint256 hypeReserves,
    uint256 tokenReserves,
    uint256 totalSupply,
    string name,
    string symbol
);
```

### Metadata Events

#### TokenMetadataUpdated

```solidity
event TokenMetadataUpdated(
    address indexed token,
    address indexed creator,
    string name,
    string symbol,
    string image_uri,
    string description,
    string website,
    string twitter,
    string telegram,
    string discord,
    uint256 timestamp
);
```

## Data Structures

### TokenMetadata

```solidity
struct TokenMetadata {
    string name;
    string symbol;
    string image_uri;
    string description;
    string website;
    string twitter;
    string telegram;
    string discord;
    address creator;
    uint256 creationTimestamp;
    uint256 startingLiquidity;
    uint8 dexIndex;
}
```

## Constants

### Token Economics

```solidity
uint256 public constant VIRTUAL_HYPE_LIQUIDITY = 300 ether;
uint256 public constant TOTAL_SUPPLY = 1_000_000_000 * 10 ** 6;
```

## Error Codes

### General Errors

* `ZeroAddress()`: Address cannot be zero
* `ZeroAmount()`: Amount cannot be zero
* `EthTransferFailed()`: ETH transfer failed
* `TokenTransferFailed()`: Token transfer failed
* `InsufficientBalance()`: Insufficient balance

### Token Lifecycle Errors

* `TokenNotCreatedByFactory()`: Token not created by this factory
* `TokenCreationFailed()`: Token creation failed
* `TokenFrozen()`: Token is frozen
* `TokenNotFound()`: Token not found

### Trading Errors

* `TokenPurchaseFailed()`: Token purchase failed
* `InsufficientLiquidity()`: Insufficient liquidity
* `CreatorCannotSellYet()`: Creator cannot sell yet (1-hour lock)

### Authorization Errors

* `UnauthorizedMetadataUpdate()`: Unauthorized metadata update


# Brand Kit and Guidelines

<figure><img src="/files/w7DWAoJ7Iq5TPVWax5jC" alt=""><figcaption></figcaption></figure>

{% file src="/files/am1VgaeifohKaJ6MLq1s" %}
Complete Brand Kit Assets
{% endfile %}