SDK Overview

TypeScript SDK for interacting with VOLS V2 AMM, CLOB, Indexer, and API on Hedera network

Features

Frontend wallet integration - Works with MetaMask, WalletConnect, and browser wallets
Backend support - Use with Node.js and private keys for server-side operations
Exchange operations - Place orders, cancel orders, query order book
Account registry management - Main accounts, sub-accounts, permissions
API client - Market data, trade history, and analytics
Full TypeScript support - Complete type definitions included
Built on ethers.js v6 - Modern, secure blockchain interaction

Installation

npm install volsfi-sdk-v1

Prerequisites

For Frontend Development

Modern web browser with wallet extension (MetaMask, etc.)
npm or yarn

For Backend Development

Node.js v24 or higher
npm or yarn
Private key for transaction signing
Access to Hedera RPC endpoint

Quick Start

Frontend Usage (Browser with Wallet)

Use with MetaMask, WalletConnect, or any browser wallet:

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

// Connect to user's wallet
const provider = new BrowserProvider(window.ethereum);

// Initialize SDK
const sdk = new SDK(
    provider,
    "0x9AF250627A941FB2d622Ad527aff9cef4d1528e9", // Account Registry
    "0x9f028946bc7fD135fc5Bf108810a58C8d61539E7", // Factory
    "https://api.prod.vols.fi", // API Base URL
    "0xdfA16BAD4ed5Fe68d72c41b3a5669d500CF4D397", // AMM Router
    "0x2C5c32e8F427F9c41c24a70340cA92885883B8Be", // AMM Factory
);

// Place a sell order - wallet will prompt for signature
await sdk.exchangeSDK.placeSellOrder(
    mainAccount,
    price,
    amount,
    tokenA,
    tokenB,
);

Backend Usage (Node.js with Private Key)

Use in Node.js scripts or backend services:

import { JsonRpcProvider, Wallet } from "ethers";
import { SDK } from "volsfi-sdk-v1";

// Setup provider and wallet
const provider = new JsonRpcProvider("https://mainnet.hashio.io/api");
const wallet = new Wallet(process.env.PRIVATE_KEY, provider);

// Initialize SDK with signer
const sdk = new SDK(
    provider,
    "0x9af250627a941fb2d622ad527aff9cef4d1528e9", // Account Registry
    "0x9f028946bc7fd135fc5bf108810a58c8d61539e7", // Factory
    "https://api.prod.vols.fi", // API Base URL
    "AMM_ROUTER_ADDRESS", // AMM Router
    "AMM_FACTORY_ADDRESS", // AMM Factory
    wallet, // Signer (optional, for write operations)
);

// Place a sell order
await sdk.exchangeSDK.placeSellOrder(
    mainAccount,
    price,
    amount,
    tokenA,
    tokenB,
);

Using Individual SDKs

You can also use individual SDK components:

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

const provider = new BrowserProvider(window.ethereum);

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

// Read operations (no signer required)
const pair = await exchangeSDK.getPair(tokenA, tokenB);
const orders = await exchangeSDK.getLimitedOrders(tokenA, tokenB, 10, true);

// Write operations (wallet will sign)
await exchangeSDK.placeBuyOrder(mainAccount, price, amount, tokenA, tokenB);