API Client SDK
REST API client for market data, trade history, and analytics
The API_SDK provides a REST API client for market data, trade history, and analytics from the VOLS indexer.
Initialization
import { API_SDK } from "vols-v1-sdk";
const apiSDK = new API_SDK("https://api.prod.vols.fi");Core Methods
fetchHistoricalPrices
Get historical price data for trading pairs.
Signature:
async fetchHistoricalPrices(from: string, to: string, identifier?: string): Promise<FetchResponse>Parameters:
from: string- Start timestamp (Unix seconds)to: string- End timestamp (Unix seconds)identifier?: string- Optional pair (0x address or name like "USDC/HBAR")
Example:
// All pairs
const all = await apiSDK.fetchHistoricalPrices("1704067200", "1704153600");
// Specific pair
const pair = await apiSDK.fetchHistoricalPrices("1704067200", "1704153600", "USDC/HBAR");fetchTradeHistory
Get trade history for a pair.
Signature:
async fetchTradeHistory(from: string, to: string, identifier: string): Promise<FetchResponse>fetchTotal
Get total trading volume statistics.
Signature:
async fetchTotal(from: string, to: string): Promise<FetchResponse>fetchPairs
Get list of all trading pairs.
Signature:
async fetchPairs(from: string, to: string): Promise<any>fetchOrders
Get order data for a pair.
Signature:
async fetchOrders(from: string, to: string, identifier: string): Promise<FetchResponse>fetchMarketDetails
Get market information.
Signature:
async fetchMarketDetails(from: string, to: string, address?: string): Promise<FetchResponse>fetchTrades
Get user-specific trade history.
Signature:
async fetchTrades(from: string, to: string, userAddress: string): Promise<FetchResponse>fetchCandleWick
Get candlestick chart data.
Signature:
async fetchCandleWick(from: string, to: string, identifier: string): Promise<FetchResponse>fetchDetails
Get detailed pair information.
Signature:
async fetchDetails(identifier: string): Promise<FetchResponse>fetchUserPNL
Get profit/loss for a user.
Signature:
async fetchUserPNL(address?: string): Promise<FetchResponse>fetchPairNames
Get all pair names.
Signature:
async fetchPairNames(): Promise<FetchResponse>fetchSimpleGraphData
Get simplified graph data.
Signature:
async fetchSimpleGraphData(from: string, to: string, identifier: string): Promise<FetchResponse>Account Registry Methods
fetchAccountStatus
Check if a main account is enabled.
Signature:
async fetchAccountStatus(main: string): Promise<RegistryAccountStatus>Returns: { main: string, enabled: boolean }
fetchSubaccounts
Get subaccounts for a main account.
Signature:
async fetchSubaccounts(main: string, sub?: string): Promise<RegistrySubaccount[]>Returns: Array of { main: string, sub: string }
fetchKeysAdded
Get active keys with permissions.
Signature:
async fetchKeysAdded(main: string, sub?: string): Promise<RegistryKeyCurrent[]>Returns: Array of { key: string, permissions: { canTrade: boolean, canCancel: boolean } }
fetchKeysRevoked
Get revoked keys.
Signature:
async fetchKeysRevoked(main: string, sub?: string): Promise<RegistryKeyCurrent[]>fetchTradingStatus
Check if trading is enabled for a subaccount.
Signature:
async fetchTradingStatus(main: string, sub: string): Promise<{ enabled: boolean }>fetchWithdrawalsStatus
Check if withdrawals are enabled.
Signature:
async fetchWithdrawalsStatus(main: string, sub: string): Promise<{ enabled: boolean }>Fee Calculator Methods
calculateTradeOutput
Calculate fees and output for a trade.
Signature:
async calculateTradeOutput(request: FeeCalculationRequest): Promise<FeeCalculationResponse>Parameters:
request: { tokenAddress: string, quantity: string, price: string }
Returns: Fee breakdown with buyer/seller fees, net output, price impact
Example:
const calc = await apiSDK.calculateTradeOutput({
tokenAddress: "0xToken...",
quantity: "1000000000000000000", // 1 token
price: "1000000000000000000"
});
console.log(`Net Output: ${calc.netOutput}`);fetchFeeConfiguration
Get fee configuration for a token.
Signature:
async fetchFeeConfiguration(tokenAddress: string): Promise<FeeConfigurationResponse>Returns: { tokenAddress, fees: { buyerFeePercent, sellerFeePercent }, source, note }
Response Types
All methods return FetchResponse:
interface FetchResponse {
s?: string | null; // Status ("ok" for success)
status?: string | null; // Alternative status
errmsg?: string | null; // Error message
data?: any | null; // Response data
}Error Handling
Methods throw errors when API returns non-ok status. Always use try-catch:
try {
const data = await apiSDK.fetchHistoricalPrices("1704067200", "1704153600");
} catch (error) {
console.error("API error:", error);
}