Reads - Hedgin

Every read needs the read scope. A read returns the data of the API’s { vault, data } body, parsed against the schemas in the SDK. listVaults returns the vaults array of its own { vaults } body. If a response does not match its schema, the method throws an ApiError with the code contract_mismatch. The SDK never returns a half-parsed object. See Errors. Amounts are base-unit strings. The route column names the API endpoint behind each method. Request and response fields are documented in the API reference.

Methods

Method	Route	Returns
`listVaults()`	`GET /vaults`	`VaultSummary[]`: the vaults this key manages.
`getVault(vault)`	`GET /vaults/{vault}`	`VaultDetail`: fees, limits, pending requests, pause flags, NAV epoch.
`getHoldings(vault)`	`GET /vaults/{vault}/holdings`	`Holdings`: token balances and their value.
`getStrategies(vault)`	`GET /vaults/{vault}/strategies`	`Strategy[]`: open Jupiter, DLMM, and Phoenix strategies.
`getNavHistory(vault, limit?)`	`GET /vaults/{vault}/nav`	`NavHistoryPoint[]`: posted NAVs, oldest first. The API returns the latest 200 by default.
`getRequests(vault)`	`GET /vaults/{vault}/requests`	`RequestQueue`: queued deposits and withdrawals.
`getStrategyHistory(vault)`	`GET /vaults/{vault}/strategy-history`	`StrategyHistoryItem[]`: closed strategies and their per-mint cash flows, newest first.
`getPhoenix(vault)`	`GET /vaults/{vault}/phoenix`	`PhoenixManager`: onboarding status, markets, open orders, margin.
`getQuote(request)`	`GET /jupiter/quote`	`Quote`: a Jupiter quote for one swap.
`searchPools(vault, query, page?)`	`GET /dlmm/pools`	`PoolSearchPage`: Meteora DLMM pools that match `query`. `page` defaults to 1.
`getToken(vault, mint)`	`GET /tokens/{mint}`	`TokenDetail`: symbol, decimals, price, and Jupiter verification for any mint.
`getPool(vault, lbPair)`	`GET /dlmm/pools/{lbPair}`	`PoolInfo`: one pool with its active bin.

vault is the vault address. lbPair is the Meteora DLMM pool address. The examples below assume hedge is a client from createHedgeClient and vault and lbPair are address strings.

Vaults

listVaults is the usual first call. Each VaultSummary carries the deposit token’s symbol and decimals, so you can format totalAssets without another request.

const vaults = await hedge.listVaults();
for (const v of vaults) {
  console.log(v.name, v.status, formatUnits(v.totalAssets, v.depositDecimals), v.depositSymbol);
}

getVault returns the on-chain vault state. navPerShare is scaled by 1e9, so "1000000000" means one deposit-mint base unit per share base unit. protocol.maxSlippageBps is the protocol-wide slippage cap.

const detail = await hedge.getVault(vault);
console.log(detail.navEpoch, detail.depositPaused, detail.protocol.maxSlippageBps);

Holdings and strategies

getHoldings values the vault’s tokens. When some token has no price, partial is true and unpriced lists the mints. A missing value is not zero.

const holdings = await hedge.getHoldings(vault);
if (holdings.partial) console.warn("Unpriced tokens:", holdings.unpriced);
for (const row of holdings.tokens) console.log(row.token.symbol, row.amount);

getStrategies returns a union keyed by type: jupiter, dlmm, phoenix, or unreadable. An unreadable strategy carries the protocol and a reason. On current servers a dlmm strategy also carries inclusive lowerBinId and upperBinId, the pool’s activeBinId, and per-bin bins. These fields are optional in the type because older servers omit them.

for (const strategy of await hedge.getStrategies(vault)) {
  if (strategy.type === "dlmm") console.log(strategy.position, strategy.lowerBinId, strategy.upperBinId, strategy.activeBinId);
  else if (strategy.type === "jupiter") console.log(strategy.symbol, strategy.vaultBalance);
  else if (strategy.type === "phoenix") console.log(strategy.equity, strategy.leverage);
  else console.warn(strategy.protocol, strategy.reason);
}

NAV, requests, and history

getNavHistory returns posted NAVs, oldest first. Pass limit to ask for fewer points. A point with overridden: true was set by an admin nav_override, not by the keeper.

const navs = await hedge.getNavHistory(vault, 10);
console.log(navs.at(-1)?.navPerShare);

getRequests lists queued deposits and withdrawals. A request is pending until a later NAV epoch is posted, then resolvable. Deposit amount is in deposit-mint base units. Withdrawal shares is in share base units.

const { deposits, withdrawals } = await hedge.getRequests(vault);
console.log(deposits.length, withdrawals.length);

getNavHistory and getStrategyHistory throw an ApiError with the code HistoryUnavailable (HTTP 503) when the deployment has no history database.

try {
  const closed = await hedge.getStrategyHistory(vault);
  console.log(closed[0]?.tokens[0]?.realizedPnl);
} catch (error) {
  if (error instanceof ApiError && error.code === "HistoryUnavailable") console.log("No history database");
  else throw error;
}

realizedPnl is a signed base-unit string. It equals returned + feesRetained - contributed, so a loss is negative. A strategy with exact: false was opened before exact accounting existed, and its totals may be incomplete.

Phoenix

getPhoenix reports where the vault is in Phoenix setup. status is none (no strategy), registered (strategy exists, trader not onboarded), or ready (can deposit and trade). openOrders, withdrawable, and account are null when Phoenix’s own API is down. account is also null before onboarding. Handle null before you use them.

const phoenix = await hedge.getPhoenix(vault);
console.log(phoenix.status, phoenix.openOrders?.length ?? "unavailable");

Quotes, tokens, and pools

getQuote asks Jupiter for a quote. amount is a base-unit string in the input mint’s units.

const quote = await hedge.getQuote({
  vault,
  inputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  outputMint: "So11111111111111111111111111111111111111112",
  amount: "1000000",
  slippageBps: 50,
});
console.log(quote.outAmount, quote.routeLabels);

getToken resolves a pasted contract address to its symbol, decimals, and Jupiter verification. verified is null when verification is unknown. Warn the user before a swap that involves an unverified token.

const token = await hedge.getToken(vault, "So11111111111111111111111111111111111111112");
console.log(token.symbol, token.decimals, token.verified);

searchPools finds DLMM pools that match a query such as a token symbol. getPool returns one pool with its activeBinId, which you need to choose the lowerBinId and exclusive upperBinId of a dlmm/open.

const page = await hedge.searchPools(vault, "SOL");
console.log(page.total, page.pools[0]?.address);

const pool = await hedge.getPool(vault, lbPair);
console.log(pool.activeBinId, pool.activePrice);

activePrice is token Y per token X, as a string.

Units and helpers

The SDK exports pure helpers that never touch the network.

Helper	Signature	Purpose
`parseUnits`	`(display: string, decimals: number) => string`	Converts a display amount such as `"1.5"` or `"1,000"` to base units. Throws if the text has more fractional digits than the token has, instead of rounding.
`formatUnits`	`(baseUnits: string, decimals: number) => string`	Converts base units to a display amount. Neither function goes through `number`.
`binRangeForPrices`	`(pool, minPrice, maxPrice) => PriceRange`	Turns a price range (token Y per token X) into the smallest `lowerBinId` and exclusive `upperBinId` that cover it, with `binCount`, which `sides` the range can hold, and the actual edge prices. Throws above 1,400 bins.
`binPrice`	`(pool, binId) => number`	The price of one bin.
`flipSide`	`(tokenXMint, depositMint) => "x" \| "y"`	The non-deposit token that `dlmm/flip` sells.
`flipRange`	`(selection, activeBinId, side) => InclusiveBinRange \| null`	The part of a bin selection that holds only one side’s token, as `dlmm/flip` needs. `null` when none does.

binRangeForPrices and binPrice take a PoolInfo-shaped argument with activeBinId, activePrice, and binStep. A PoolInfo from getPool fits. The constants DLMM_MAX_POSITION_BINS (1,400) and DLMM_BINS_PER_TRANSACTION (70) are also exported. One position account holds 70 bins, so a wider open becomes several transactions.

const amount = parseUnits("1.5", 6); // "1500000"
console.log(formatUnits(amount, 6)); // "1.5"

const range = binRangeForPrices(pool, 140, 160);
console.log(range.lowerBinId, range.upperBinId, range.binCount, range.sides);

​Methods

​Vaults

​Holdings and strategies

​NAV, requests, and history

​Phoenix

​Quotes, tokens, and pools

​Units and helpers