> Feedback: If these docs are stale, missing, or confusing, post sanitized feedback to `https://docs.tempo.xyz/api/feedback` with `source: "mcp"`, a short `message`, and any relevant `toolName`, `relatedResource`, or `client`.
# Providing Liquidity

Provide liquidity to the DEX by placing limit orders or flip orders in the onchain orderbook.

When your orders are filled, you earn the spread between bid and ask prices while helping facilitate trades for other users.

You can only place orders on pairs between a token and its designated quote token. All TIP-20 tokens specify a quote token for trading pairs. [pathUSD](/docs/protocol/exchange/quote-tokens#pathusd) can be used as a simple choice for a quote token.

## Overview

The DEX uses an onchain orderbook where you can place orders at specific price ticks. Orders are matched using price-time priority, meaning better-priced orders fill first, and within the same price, earlier orders fill first.

Unlike traditional AMMs, you specify exact prices where you want to buy or sell, giving you more precise control over your liquidity provision strategy.

## Order Types

### Limit Orders

Standard orders that remain in the book at a specific price until filled or cancelled.

```solidity
function place(
    address token,
    uint128 amount,
    bool isBid,
    int16 tick
) external returns (uint128 orderId)
```

**Parameters:**

* `token` - The token address you're trading (must trade against its quote token)
* `amount` - The amount of the token denominated in `token`
* `isBid` - `true` for a buy order, `false` for a sell order
* `tick` - The price tick: `(price - 1) * 100_000` where price is in quote token per token

**Returns:**

* `orderId` - Unique identifier for this order

**Example: Place a bid to buy 1000 USDG at $0.9990**

```solidity
// tick = (0.9990 - 1) * 100_000 = -10
uint128 orderId = exchange.place(
    USDG_ADDRESS,
    1000e6,      // Amount: 1000 USDG
    true,        // isBid: buying USDG
    -10          // tick: price = $0.9990
);
```

**Example: Place an ask to sell 1000 USDG at $1.0010**

```solidity
// tick = (1.0010 - 1) * 100_000 = 10
uint128 orderId = exchange.place(
    USDG_ADDRESS,
    1000e6,      // Amount: 1000 USDG
    false,       // isBid: selling USDG
    10           // tick: price = $1.0010
);
```

### Flip Orders

Special orders that automatically reverse to the opposite side when completely filled, creating perpetual liquidity similar to an automated market maker pool.

```solidity
function placeFlip(
    address token,
    uint128 amount,
    bool isBid,
    int16 tick,
    int16 flipTick
) external returns (uint128 orderId)
```

**Parameters:**

* All parameters from `place()`, plus:
* `flipTick` - The price where the order will flip to when filled
  * Must be greater than or equal to `tick` if `isBid` is true
  * Must be less than or equal to `tick` if `isBid` is false

**Returns:**

* `orderId` - Unique identifier for this flip order

**Example: Place a flip order providing liquidity on both sides**

```solidity
// Place a bid at $0.9990 that flips to an ask at $1.0010
uint128 orderId = exchange.placeFlip(
    USDG_ADDRESS,
    1000e6,      // Amount: 1000 USDG
    true,        // isBid: start as a buy order
    -10,         // tick: buy at $0.9990
    10           // flipTick: sell at $1.0010 after filled
);
```

When this order is completely filled:

1. You buy 1000 USDG at $0.9990
2. The same order ID automatically rests as an ask for 1000 USDG at $1.0010 and emits `OrderFlipped`
3. When that fills, it flips back to a bid at $0.9990
4. This continues indefinitely, earning the spread each time

:::info
Flip orders act like a liquidity pool position, automatically providing liquidity on both sides of the market as they're filled back and forth.
:::

## Understanding Ticks

Prices are specified using ticks with 0.1 basis point (0.001%) precision:

**Tick Formula:** `tick = (price - 1) × 100_000`

**Price Formula:** `price = 1 + (tick / 100_000)`

Where `price` is the token price in quote token units.

### Example Tick Calculations

| Price | Tick | Calculation |
|-------|------|-------------|
| $0.9990 | -100 | (0.9990 - 1) × 100\_000 = -100 |
| $0.9998 | -20 | (0.9998 - 1) × 100\_000 = -20 |
| $1.0000 | 0 | (1.0000 - 1) × 100\_000 = 0 |
| $1.0002 | 20 | (1.0002 - 1) × 100\_000 = 20 |
| $1.0010 | 100 | (1.0010 - 1) × 100\_000 = 100 |

:::warning
Price ticks are limited to ±2% from peg (±2000 ticks). Orders outside this range will be rejected.
:::

## Bid vs Ask

* **Bid (isBid = true)**: An order to *buy* the token using its quote token
* **Ask (isBid = false)**: An order to *sell* the token for its quote token

For a USDG/USD pair where USD is the quote:

* A bid buys USDG with USD at your specified price
* An ask sells USDG for USD at your specified price

## Order Execution Timeline

Orders follow a specific lifecycle:

1. **Placement**: When you call `place()` or `placeFlip()`:
   * Tokens are debited from your DEX balance (or transferred if insufficient)
   * Order is immediately added to the active book and visible to other contracts
   * Returns an order ID immediately

2. **Filling**: As market orders execute against your order:
   * Your order fills partially or completely
   * Proceeds are credited to your DEX balance
   * If a flip order fills completely, the same `orderId` is immediately rewritten on the opposite side and an `OrderFlipped` event is emitted

## Cancelling Orders

Remove an order from the book before it's filled:

```solidity
function cancel(
    uint128 orderId
) external
```

**Example:**

```solidity
// Cancel order #12345
exchange.cancel(12345);
```

Cancellations execute immediately, and any unfilled portion of your order is refunded to your [DEX balance](/docs/protocol/exchange/exchange-balance).

:::warning
You can only cancel your own orders. Attempting to cancel another user's order will revert.
:::

## Flip-order indexing

**Indexers and analytics:**

* Subscribe to the `OrderFlipped(orderId, newSide, newTick, ...)` event on the DEX
* Key order state by `orderId` and let it change side and tick over its lifetime
* Do not expect `nextOrderId` to advance per flip

**Frontends and SDKs:**

* Surface the persistent `orderId` across the flip lifecycle in user-facing order status

**Smart contracts and tooling:**

* Do not assert that `flipTick != tick`; same-tick flips are valid

See the [compatibility section of TIP-1056](https://tips.sh/1056#compatibility) for additional migration guidance.