Providing Liquidity

Add liquidity for a token pair by placing orders on the Stablecoin DEX. You can provide liquidity on the buy or sell side of the orderbook, with limit or flip orders. To learn more about order types see the documentation on order types.

In this guide you will learn how to place buy and sell orders to provide liquidity on the Stablecoin DEX orderbook.

Demo

Place an Order

demo

Create an account, or use an existing one.

Add testnet funds to your account.

Approve spend and place buy order for 100 AlphaUSD

Query order details

Steps

Set up your client

Ensure that you have set up your client by following the guide.

Approve spend

To place an order, you need to approve the Stablecoin DEX contract to spend the order's "spend" token.

Approve Spend

demo

Create an account, or use an existing one.

Approve the Stablecoin DEX to spend pathUSD

import {  } from 'viem'
import {  } from 'viem/tempo'
import {  } from 'wagmi/tempo'
 
const  = '0x20c0000000000000000000000000000000000000'
const  = '0x20c0000000000000000000000000000000000001'
 
function (: { : 'buy' | 'sell' }) {
  const {  } = 
  // buying AlphaUSD requires we spend pathUSD
  const  =  === 'buy' ?  :  
  const { :  } = ..() 
 
  return (
    < ="button" ={() => {
      ({ 
        : ('100', 6), 
        : ., 
        : , 
      }) 
  }}>
      Approve Spend
    </>
  )
}

Place order

Once the spend is approved, you can place an order by calling the place action on the Stablecoin DEX.

Place Order

demo

Create an account, or use an existing one.

Approve spend and place buy order for 100 AlphaUSD

import { ,  } from 'viem/tempo'
import {  } from 'viem'
import {  } from 'wagmi'
 
const  = '0x20c0000000000000000000000000000000000000'
const  = '0x20c0000000000000000000000000000000000001'
 
function (: { : 'buy' | 'sell' }) {
  const {  } = 
  // buying AlphaUSD requires we spend pathUSD
  const  =  === 'buy' ?  : 
 
  const  = () 
 
  return (
    < ="button" ={() => {
      const  = [ 
        ...({ 
          : ., 
          : ('100', 6), 
          : , 
        }), 
        ...({ 
          : , 
          : ('100', 6), 
          : , 
          : 0, 
        }), 
      ] 
      .({  }) 
    }}>
      Place Order
    </>
  )
}

View order details

After placing an order, you can query its details to see the current state, including the amount filled and remaining using Hooks.dex.useOrder.

View Order

demo

Create an account, or use an existing one.

Add testnet funds to your account.

Approve spend and place buy order for 100 AlphaUSD

Query order details

import {  } from 'wagmi/tempo'
 
const  = 123n
 
const { : ,  } = ..({
  ,
})
 
.('Type:', ?. ? 'Buy' : 'Sell')
.('Amount:', ?..())
.('Remaining:', ?..())
.('Tick:', ?.)
.('Is flip order:', ?.)

For more details on querying orders, see the Hooks.dex.useOrder documentation.

Recipes

Cancel order

Cancel an order using its order ID.

When you cancel an order, any remaining funds are credited to your exchange balance (not directly to your wallet). To move funds back to your wallet, you can withdraw them to your wallet.

Place and Cancel an Order

demo

Create an account, or use an existing one.

Add testnet funds to your account.

Approve spend and place buy order for 100 AlphaUSD

Cancel the order

import { ,  } from 'viem/tempo'
import {  } from 'wagmi/tempo'
import {  } from 'viem'
import {  } from 'wagmi'
 
const  = '0x20c0000000000000000000000000000000000000'
const  = '0x20c0000000000000000000000000000000000001'
 
function () {
  const  = ()
  const  = ..() 
 
  const  = () => {
    const  = [
      ...({
        : .,
        : ('100', 6),
        : ,
      }),
      ...({
        : ,
        : ('100', 6),
        : 'buy',
        : 0,
      }),
    ]
    .({  })
  }
 
  return (
    <>
      < ="button" ={}>
        Place Order
      </>
      < ={
        () => {
          .()
          const  = new (. as HTMLFormElement)
          const  = (.('orderId') as string)
 
          .({  }) 
        }
      }>
        < ="text" ="orderId" ="Order ID" />
        <
          ="submit"
          ={.}
        > 
        {. ? 'Canceling...' : 'Cancel Order'}
        </> 
      </>
    </>
  )
}

Determining quote token

Each token has a designated quote token that it trades against on the DEX. For most stablecoins, this will be pathUSD.

Use the token.useGetMetadata hook to retrieve a token's quote token.

import {  } from 'wagmi/tempo'
 
const { :  } = ..({ 
  : '0x20c0000000000000000000000000000000000001', // AlphaUSD
}) 
 
.('Token:', ?.)
Token: AlphaUSD
.('Quote Token:', ?.) // returns `pathUSD` address Quote Token: 0x20c0000000000000000000000000000000000000

Flip order

Flip orders automatically switch between buy and sell sides when filled, providing continuous liquidity. Use viem's dex.placeFlip to create a flip order call.

import { ,  } from 'viem/tempo'
import {  } from 'viem'
import {  } from 'wagmi'
 
const  = '0x20c0000000000000000000000000000000000000'
const  = '0x20c0000000000000000000000000000000000001'
 
function (: { : 'buy' | 'sell' }) {
  const {  } = 
  // buying AlphaUSD requires we spend pathUSD
  const  =  === 'buy' ?  : 
 
  const  = ()
 
  return (
    < ="button" ={() => {
      const  = [
        ...({
          : .,
          : ('100', 6),
          : ,
        }),
        ...({ 
          : ,
          : ('100', 6),
          : ,
          : 0,
        }),
      ]
      .({  })
    }}>
      Place Flip Order
    </>
  )
}

Place order at specific price

Ticks represent prices relative to the quote token (usually pathUSD). The formula is:

tick = (price - 1) * 100_000

For example, price $1.0000 → tick = 0, price $0.9990 → tick = -10, and price $1.0010 → tick = 10.

Use the Tick utility to convert between prices and ticks:

import { Actions, Tick } from 'viem/tempo'
import { parseUnits } from 'viem'
 
const alphaUsd = '0x20c0000000000000000000000000000000000001'
 
// buy order at $0.9990 (tick: -10)
const buyCall = Actions.dex.place.call({ 
  token: alphaUsd, 
  amount: parseUnits('100', 6), 
  type: 'buy', 
  tick: Tick.fromPrice('0.9990'), // -10
}) 
 
// sell order at $1.0010 (tick: 10)
const sellCall = Actions.dex.place.call({ 
  token: alphaUsd, 
  amount: parseUnits('100', 6), 
  type: 'sell', 
  tick: Tick.fromPrice('1.0010'), // 10
})

For more details including tick precision, limits, and calculation examples, see Understanding Ticks.

Best practices

Batch calls

You can batch the calls to approve spend and place the order in a single transaction for efficiency. See the guide on batch transactions for more details.

Learning resources

Executing Swaps

Learn how to execute swaps and trade stablecoins on the DEX

Protocol Exchange Specification

Deep dive into the Stablecoin DEX protocol specification

Exchange Balance

Manage token balances on the exchange to optimize gas costs