VOLS SDK v1

TypeScript SDK for interacting with VOLS V2 AMM, VOLS CLOB (Central Limit Order Book), 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

Documentation

• SDK API Reference - Comprehensive API documentation with detailed method signatures, parameters, and examples

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

Installation

npm install volsfi-sdk-v1

Usage

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);

Token Approval Workflow

Before placing orders or performing swaps, you must approve tokens:

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, approve tokens to the AMM Router address instead of the pair address.

Development Setup

Clone and install dependencies:

git clone <repository-url>
cd vols-v1-sdk
npm install

Configure environment variables:

cp env-example .env

Edit .env file:

PK=your_private_key_here
RPC_URL=https://mainnet.hashio.io/api
API_BASE_URL=https://api.prod.vols.fi

Build

Compile TypeScript to JavaScript:

npm run build

The compiled output will be in the dist/ directory.

Testing

Run all tests:

npm test

Run tests in watch mode:

npm test -- --watch

Project Structure

vols-v1-sdk/
├── src/
│   ├── api/
│   │   └── index.ts                # API client for market data & analytics
│   ├── scripts/
│   │   ├── AccountRegistrySDK.ts   # Account & sub-account management
│   │   ├── ExchangeSDK.ts          # CLOB order placement & management
│   │   └── AMMSDK.ts               # AMM swap & liquidity operations
│   ├── abi/                        # Smart contract ABIs
│   │   ├── AccountRegistry.json    # Account registry contract
│   │   ├── Exchange.json           # CLOB exchange contract
│   │   ├── Factory.json            # CLOB factory contract
│   │   ├── Token.json              # ERC20 token contract
│   │   ├── VolsV2Factory.json      # AMM factory contract
│   │   ├── VolsV2Router.json       # AMM router contract
│   │   ├── VolsV2Pair.json         # AMM pair contract
│   │   └── VolsV2ERC20.json        # AMM LP token contract
│   └── index.ts                    # Main SDK wrapper
│
├── tests/
│   ├── account-registry/           # Account registry tests
│   ├── amm/                        # AMM tests (swap, liquidity, pairs)
│   ├── exchange/                   # Exchange CLOB tests
│   ├── base-config.ts              # Shared test configuration
│   └── api.test.ts                 # API endpoint tests
│
├── dist/                           # Compiled JavaScript output (generated)
├── .env                            # Environment variables (not committed)
├── env-example                     # Example environment file
├── package.json                    # Dependencies & scripts
├── tsconfig.json                   # TypeScript configuration
├── jest.config.cjs                 # Jest test configuration
└── README.md                       # Documentation

Contract Addresses

Hedera Mainnet (Chain ID: 295)

• Account Registry: 0x9af250627a941fb2d622ad527aff9cef4d1528e9
• Factory: 0x9f028946bc7fd135fc5bf108810a58c8d61539e7

API Endpoints

• Production: https://api.prod.vols.fi

Dependencies

Production

• axios: HTTP client
• dotenv: Environment variable management
• ethers: Ethereum/blockchain interaction [V6]
• ts-node: TypeScript execution

Development

• @types/jest: Jest type definitions
• @types/node: Node.js type definitions
• jest: Testing framework
• ts-jest: Jest TypeScript preprocessor
• typescript: TypeScript compiler

Publishing

Before publishing to npm:

npm login               # Login to your npm registry account
npm run build           # Compile TypeScript
npm test                # Ensure all tests pass
npm publish             # Publish to npm registry

Type Definitions

Type definitions are automatically generated in dist/ when you run npm run build.