> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hedgin.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Reads

> Every HedgeClient read method with its API route, return type, and an example, plus the unit helpers.

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](/sdk/safety#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](/api-reference/introduction).

## 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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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`.

```ts theme={null}
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.

```ts theme={null}
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);
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.