Exchange SDK (CLOB)

The ExchangeSDK handles CLOB (Central Limit Order Book) order operations, fee management, and order book queries.

Pair Management

getPair

Get the exchange contract address for a token pair.

Signature:

async getPair(tokenA: string, tokenB: string): Promise<string>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address

Returns: Promise<string> - Exchange contract address

createPair

Create a new trading pair (if it doesn't exist).

Signature:

async createPair(tokenA: string, tokenB: string): Promise<string>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address

Returns: Promise<string> - Exchange contract address

Order Placement

placeSellOrder

Place a sell limit order.

Signature:

async placeSellOrder(
  main: string,
  sellPrice: bigint,
  sellAmount: bigint,
  tokenA: string,
  tokenB: string
): Promise<ContractTransactionResponse>

Parameters:

• main: string - Main account address
• sellPrice: bigint - Sell price
• sellAmount: bigint - Amount to sell
• tokenA: string - Token to sell
• tokenB: string - Token to receive

Returns: Promise<ContractTransactionResponse>

Token Approval Requirement:

Before placing sell orders, you must approve the Exchange contract to spend your tokens:

// Get the exchange/pair address
const pairAddress = await exchangeSDK.getPair(tokenA, tokenB);

// Approve tokenA for the exchange
const tokenContract = new ethers.Contract(tokenA, TokenABI, signer);
const amount = ethers.parseEther("1000"); // Amount to approve
await tokenContract.approve(pairAddress, amount);

// Verify approval
const allowance = await tokenContract.allowance(userAddress, pairAddress);
if (allowance < sellAmount) {
  throw new Error("Insufficient token approval");
}

The SDK will throw an error "Not enough approval" if the allowance is insufficient.

placeBuyOrder

Place a buy limit order.

Signature:

async placeBuyOrder(
  main: string,
  buyPrice: bigint,
  buyAmount: bigint,
  tokenA: string,
  tokenB: string
): Promise<ContractTransactionResponse>

Parameters:

• main: string - Main account address
• buyPrice: bigint - Buy price
• buyAmount: bigint - Amount to buy
• tokenA: string - Token to buy
• tokenB: string - Token to spend

Returns: Promise<ContractTransactionResponse>

Token Approval Requirement:

Before placing buy orders, you must approve the Exchange contract to spend your tokens:

// Get the exchange/pair address
const pairAddress = await exchangeSDK.getPair(tokenA, tokenB);

// Approve tokenB for the exchange
const tokenContract = new ethers.Contract(tokenB, TokenABI, signer);
const amount = ethers.parseEther("1000"); // Amount to approve
await tokenContract.approve(pairAddress, amount);

// Verify approval
const allowance = await tokenContract.allowance(userAddress, pairAddress);
if (allowance < buyAmount) {
  throw new Error("Insufficient token approval");
}

The SDK will throw an error "Not enough approval" if the allowance is insufficient.

placeSellOrderTo

Place a sell order with a specified recipient.

Signature:

async placeSellOrderTo(
  main: string,
  sellPrice: bigint,
  sellAmount: bigint,
  to: string,
  tokenA: string,
  tokenB: string
): Promise<ContractTransactionResponse>

Parameters:

• main: string - Main account address
• sellPrice: bigint - Sell price
• sellAmount: bigint - Amount to sell
• to: string - Recipient address
• tokenA: string - Token to sell
• tokenB: string - Token to receive

Returns: Promise<ContractTransactionResponse>

placeBuyOrderTo

Place a buy order with a specified recipient.

Signature:

async placeBuyOrderTo(
  main: string,
  buyPrice: bigint,
  buyAmount: bigint,
  to: string,
  tokenA: string,
  tokenB: string
): Promise<ContractTransactionResponse>

Parameters:

• main: string - Main account address
• buyPrice: bigint - Buy price
• buyAmount: bigint - Amount to buy
• to: string - Recipient address
• tokenA: string - Token to buy
• tokenB: string - Token to spend

Returns: Promise<ContractTransactionResponse>

placeSellOrderViaSubaccount

Place a sell order via a subaccount.

Signature:

async placeSellOrderViaSubaccount(
  main: string,
  sellPrice: bigint,
  sellAmount: bigint,
  tokenA: string,
  tokenB: string
): Promise<ContractTransactionResponse>

Parameters:

• main: string - Main account address
• sellPrice: bigint - Sell price
• sellAmount: bigint - Amount to sell
• tokenA: string - Token to sell
• tokenB: string - Token to receive

Returns: Promise<ContractTransactionResponse>

placeBuyOrderViaSubaccount

Place a buy order via a subaccount.

Signature:

async placeBuyOrderViaSubaccount(
  main: string,
  buyPrice: bigint,
  buyAmount: bigint,
  tokenA: string,
  tokenB: string
): Promise<ContractTransactionResponse>

Parameters:

• main: string - Main account address
• buyPrice: bigint - Buy price
• buyAmount: bigint - Amount to buy
• tokenA: string - Token to buy
• tokenB: string - Token to spend

Returns: Promise<ContractTransactionResponse>

Order Cancellation

deleteSellOrder

Cancel a sell order.

Signature:

async deleteSellOrder(
  tokenA: string,
  tokenB: string,
  price: bigint,
  orderId: string
): Promise<ContractTransactionResponse>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address
• price: bigint - Order price
• orderId: string - Order ID to cancel

Returns: Promise<ContractTransactionResponse>

deleteBuyOrder

Cancel a buy order.

Signature:

async deleteBuyOrder(
  tokenA: string,
  tokenB: string,
  price: bigint,
  orderId: string
): Promise<ContractTransactionResponse>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address
• price: bigint - Order price
• orderId: string - Order ID to cancel

Returns: Promise<ContractTransactionResponse>

deleteSellOrderForMain

Cancel a sell order for a specific main account (via subaccount).

Signature:

async deleteSellOrderForMain(
  tokenA: string,
  tokenB: string,
  main: string,
  price: bigint,
  orderId: string
): Promise<ContractTransactionResponse>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address
• main: string - Main account address
• price: bigint - Order price
• orderId: string - Order ID to cancel

Returns: Promise<ContractTransactionResponse>

deleteBuyOrderForMain

Cancel a buy order for a specific main account (via subaccount).

Signature:

async deleteBuyOrderForMain(
  tokenA: string,
  tokenB: string,
  main: string,
  price: bigint,
  orderId: string
): Promise<ContractTransactionResponse>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address
• main: string - Main account address
• price: bigint - Order price
• orderId: string - Order ID to cancel

Returns: Promise<ContractTransactionResponse>

Fee Management

getBuyerFeePercent

Get the buyer fee percentage for an exchange.

Signature:

async getBuyerFeePercent(exchangeAddress: string): Promise<bigint>

Parameters:

• exchangeAddress: string - Exchange contract address

Returns: Promise<bigint> - Fee percentage

getSellerFeePercent

Get the seller fee percentage for an exchange.

Signature:

async getSellerFeePercent(exchangeAddress: string): Promise<bigint>

Parameters:

• exchangeAddress: string - Exchange contract address

Returns: Promise<bigint> - Fee percentage

updateBuyerFeePercent

Update the buyer fee percentage (admin only).

Signature:

async updateBuyerFeePercent(
  exchangeAddress: string,
  newFeePercent: bigint
): Promise<ContractTransactionResponse>

Parameters:

• exchangeAddress: string - Exchange contract address
• newFeePercent: bigint - New fee percentage

Returns: Promise<ContractTransactionResponse>

updateSellerFeePercent

Update the seller fee percentage (admin only).

Signature:

async updateSellerFeePercent(
  exchangeAddress: string,
  newFeePercent: bigint
): Promise<ContractTransactionResponse>

Parameters:

• exchangeAddress: string - Exchange contract address
• newFeePercent: bigint - New fee percentage

Returns: Promise<ContractTransactionResponse>

getFeeReceiver

Get the fee receiver address for an exchange.

Signature:

async getFeeReceiver(exchangeAddress: string): Promise<string>

Parameters:

• exchangeAddress: string - Exchange contract address

Returns: Promise<string> - Fee receiver address

updateFeeReceiver

Update the fee receiver address (admin only).

Signature:

async updateFeeReceiver(exchangeAddress: string, newFeeReceiver: string): Promise<any>

Parameters:

• exchangeAddress: string - Exchange contract address
• newFeeReceiver: string - New fee receiver address

Returns: Promise<any> - Transaction receipt

Volume Management

getMinimumSellVolume

Get the minimum sell volume for an exchange.

Signature:

async getMinimumSellVolume(exchangeAddress: string): Promise<bigint>

Parameters:

• exchangeAddress: string - Exchange contract address

Returns: Promise<bigint> - Minimum sell volume

getMinimumBuyVolume

Get the minimum buy volume for an exchange.

Signature:

async getMinimumBuyVolume(exchangeAddress: string): Promise<bigint>

Parameters:

• exchangeAddress: string - Exchange contract address

Returns: Promise<bigint> - Minimum buy volume

updateMinimumSellVolume

Update the minimum sell volume (admin only).

Signature:

async updateMinimumSellVolume(
  exchangeAddress: string,
  newMinimumSellVolume: bigint
): Promise<ContractTransactionResponse>

Parameters:

• exchangeAddress: string - Exchange contract address
• newMinimumSellVolume: bigint - New minimum sell volume

Returns: Promise<ContractTransactionResponse>

updateMinimumBuyVolume

Update the minimum buy volume (admin only).

Signature:

async updateMinimumBuyVolume(
  exchangeAddress: string,
  newMinimumBuyVolume: bigint
): Promise<ContractTransactionResponse>

Parameters:

• exchangeAddress: string - Exchange contract address
• newMinimumBuyVolume: bigint - New minimum buy volume

Returns: Promise<ContractTransactionResponse>

Price Management

getPriceStep

Get the price step (tick size) for an exchange.

Signature:

async getPriceStep(exchangeAddress: string): Promise<bigint>

Parameters:

• exchangeAddress: string - Exchange contract address

Returns: Promise<bigint> - Price step value

setPriceStep

Set the price step (tick size) for an exchange (admin only).

Signature:

async setPriceStep(exchangeAddress: string, priceStep: bigint): Promise<ContractTransactionResponse>

Parameters:

• exchangeAddress: string - Exchange contract address
• priceStep: bigint - New price step value

Returns: Promise<ContractTransactionResponse>

Order Book Queries

getLimitedOrders

Get a limited number of orders from the order book.

Signature:

async getLimitedOrders(
  tokenA: string,
  tokenB: string,
  maxOrders: number,
  isBuyOrders: boolean
): Promise<{orders: any[], prices: string[]}>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address
• maxOrders: number - Maximum number of orders to fetch
• isBuyOrders: boolean - true for buy orders, false for sell orders

Returns: Promise<{orders: any[], prices: string[]}>

getOutputAmount

Get the output amount for a given input amount and token.

Signature:

async getOutputAmount(
  tokenA: string,
  tokenB: string,
  inputToken: string,
  inputAmount: bigint
): Promise<{outputAmount: string, price: string}>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address
• inputToken: string - Input token address
• inputAmount: bigint - Input amount

Returns: Promise<{outputAmount: string, price: string}>

getActiveBuyOrders

Get all active buy orders for the connected wallet.

Signature:

async getActiveBuyOrders(tokenA: string, tokenB: string): Promise<any[]>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address

Returns: Promise<any[]> - Array of buy order objects

getActiveSellOrders

Get all active sell orders for the connected wallet.

Signature:

async getActiveSellOrders(tokenA: string, tokenB: string): Promise<any[]>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address

Returns: Promise<any[]> - Array of sell order objects

getActiveBuyOrdersForUser

Get all active buy orders for a specific user.

Signature:

async getActiveBuyOrdersForUser(tokenA: string, tokenB: string, user: string): Promise<any[]>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address
• user: string - User address

Returns: Promise<any[]> - Array of buy order objects

getActiveSellOrdersForUser

Get all active sell orders for a specific user.

Signature:

async getActiveSellOrdersForUser(tokenA: string, tokenB: string, user: string): Promise<any[]>

Parameters:

• tokenA: string - First token address
• tokenB: string - Second token address
• user: string - User address

Returns: Promise<any[]> - Array of sell order objects

balanceOf

Get token balances for the connected wallet.

Signature:

async balanceOf(tokenAAddress: string, tokenBAddress: string): Promise<{ tokenA: bigint; tokenB: bigint }>

Parameters:

• tokenAAddress: string - First token address
• tokenBAddress: string - Second token address

Returns: Promise<{ tokenA: bigint; tokenB: bigint }>