Getting Started

This guide will walk you through setting up the VOLS SDK and understanding the token approval workflow.

SDK Initialization

The VOLS V1 SDK provides three main components:

ExchangeSDK: CLOB (Central Limit Order Book) operations for placing and canceling orders
AccountRegistrySDK: Account and subaccount management
AMMSDK: AMM operations for swaps and liquidity provision

Frontend Integration (MetaMask / Wallet)

import SDK from "volsfi-sdk-v1";
import { BrowserProvider } from "ethers";

// Initialize with wallet provider
const provider = new BrowserProvider(window.ethereum);

const sdk = new SDK(
    provider,
    "0x9af250627a941fb2d622ad527aff9cef4d1528e9", // Account Registry Address
    "0x9f028946bc7fd135fc5bf108810a58c8d61539e7", // CLOB Factory Address
    "https://api.prod.vols.fi", // API Base URL
    "AMM_ROUTER_ADDRESS", // AMM Router Address
    "AMM_FACTORY_ADDRESS", // AMM Factory Address
);

// Access individual SDKs
const exchangeSDK = sdk.exchangeSDK; // CLOB operations
const accountSDK = sdk.accountRegistrySDK; // Account management
const ammSDK = sdk.ammSDK; // AMM operations

Token Approval Workflow

Before placing orders or performing swaps, you must approve tokens. The approval workflow differs between CLOB and AMM operations.

For CLOB Orders

Before placing orders on the CLOB, approve tokens to the Exchange/Pair contract:

import { ExchangeSDK } from "volsfi-sdk-v1";
import { ethers, BrowserProvider } from "ethers";

const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

// Initialize SDK
const exchangeSDK = new ExchangeSDK(
    provider,
    "0x9f028946bc7fd135fc5bf108810a58c8d61539e7",
    "https://api.prod.vols.fi",
);

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

// Approve tokens for CLOB exchange
const tokenContract = new ethers.Contract(tokenA, TokenABI, signer);
const approvalAmount = ethers.parseEther("1000");
await tokenContract.approve(pairAddress, approvalAmount);

// Now you can place orders
await exchangeSDK.placeSellOrder(mainAccount, price, amount, tokenA, tokenB);

For AMM Operations

For AMM swaps and liquidity operations, approve tokens to the AMM Router address:

// Approve tokens for AMM Router
const routerAddress = "0xdfA16BAD4ed5Fe68d72c41b3a5669d500CF4D397";
const tokenContract = new ethers.Contract(tokenA, TokenABI, signer);
const approvalAmount = ethers.parseEther("1000");
await tokenContract.approve(routerAddress, approvalAmount);

Token Approval Best Practices

For CLOB Orders

Get the pair address first:

const pairAddress = await exchangeSDK.getPair(tokenA, tokenB);

Approve tokens to the pair contract:

const tokenContract = new ethers.Contract(tokenA, TokenABI, signer);
await tokenContract.approve(pairAddress, approvalAmount);

Check allowance before placing orders:

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

For AMM Swaps

Approve tokens to the AMM Router:

const routerAddress = "0xdfA16BAD4ed5Fe68d72c41b3a5669d500CF4D397";
const tokenContract = new ethers.Contract(tokenA, TokenABI, signer);
await tokenContract.approve(routerAddress, approvalAmount);

AMMSDK validates approvals automatically: The AMMSDK checks both balance and allowance before building transactions. If insufficient, it throws an error.

Approval Amount Strategies

Exact Amount: Approve only what you need for the current transaction
Max Approval: Approve ethers.MaxUint256 to avoid repeated approvals (gas-efficient but higher risk)
Batch Amount: Approve enough for multiple transactions

Example: Max Approval

await tokenContract.approve(spenderAddress, ethers.MaxUint256);

Example: Exact Amount

await tokenContract.approve(spenderAddress, orderAmount);

Important Notes for Market Makers

Transaction Execution

ExchangeSDK methods execute transactions directly and return ContractTransactionResponse:

const tx = await exchangeSDK.placeBuyOrder(...);
await tx.wait(); // Wait for confirmation

AMMSDK methods return TransactionRequest objects that you must sign and send:

const txRequest = await ammSDK.swapExactTokensForTokens(...);
const signer = await provider.getSigner();
const tx = await signer.sendTransaction(txRequest);
await tx.wait();

Gas Estimation

All write operations automatically estimate gas before execution. Gas limit is set based on the estimation.

Error Handling

All SDK methods throw errors for:

Invalid addresses
Insufficient balances
Insufficient approvals
Invalid parameters

Wrap SDK calls in try-catch blocks for production use.

Getting Started

On this page