# Trading

How to execute and estimate LiquidCore swaps. Use the router for automatic pool discovery; direct pool calls are also supported.

### Swap Function

**Recommended:** Execute swaps via the [LiquidCore Router](https://docs.liqd.ag/api-reference#router) (`0x625aC1D165c776121A52ff158e76e3544B4a0b8B`). Approve the router for `tokenIn`, then call `swap(tokenIn, tokenOut, amountIn, minAmountOut)`. The router discovers the correct pool automatically, so integrators don't need to update code when new pools are added. See [Integration Guide](https://docs.liqd.ag/liquidcore-integration/integration-guide).

**Optional referral-aware routing:** The router also supports:

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

Use a non-zero `refCode` only when it is allowlisted by LiquidCore's on-chain referral registry.

See [Referrals](https://docs.liqd.ag/liquidcore-integration/referrals) for referral-specific behavior and payout functions.

**Option: direct pool.** You can call `swap` on a pool contract directly if you already know the pool address (see [Overview](https://docs.liqd.ag/overview#pools)). Approve the pool for `tokenIn`, then call:

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

Pool contracts also expose a referral-aware overload:

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

#### Parameters

| Parameter      | Type    | Description                                                 |
| -------------- | ------- | ----------------------------------------------------------- |
| `tokenIn`      | address | Address of token being sold                                 |
| `tokenOut`     | address | Address of token being bought                               |
| `amountIn`     | uint256 | Amount of `tokenIn` to swap                                 |
| `minAmountOut` | uint256 | Minimum amount of `tokenOut` expected (slippage protection) |

**Returns:** Actual amount of `tokenOut` received

### Fee behavior

* Effective output depends on current pool conditions.
* Use `estimateSwap` or the quote API before submitting transactions.

#### Supported Trading Pairs

See the [Overview](https://docs.liqd.ag/overview#supported-trading-pairs) for pool addresses and token details.

### Swap Estimation

#### Preview Swaps (On-Chain)

Before executing, estimate swap outcomes:

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

#### Quote API (Off-Chain)

Use `GET /liquidcore/quote` for swap quotes (single or comma-separated `amountIn`). Full request/response and execution steps: [API Endpoints](https://docs.liqd.ag/liquidcore-integration/api-endpoints).

### Error Handling

When calling a **pool** directly, common errors include:

```solidity
error InvalidToken();           // Token not supported by pool
error ZeroAmount();            // Amount input is zero  
error SlippageExceeded();      // Output below minAmountOut
error InsufficientReserve();   // Pool lacks sufficient tokens
error TransferFailed();        // Token transfer failed
error PriceDeviationTooLarge(); // Spot price too far from oracle
```

When using the **router**, see [API Reference](https://docs.liqd.ag/api-reference#router) for `NoPoolForPair` and `TransferFailed`.

#### Error Resolution

* **InvalidToken**: Ensure using correct token addresses for the specific pool
* **ZeroAmount**: Check amount input is greater than zero
* **SlippageExceeded**: Increase slippage tolerance or reduce trade size
* **InsufficientReserve**: Pool lacks liquidity, try smaller amount
* **PriceDeviationTooLarge**: Spot price differs from oracle price