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

# Read SDK

> Query market data, account state, and subscribe to real-time updates

<Info>
  A [Node API token](/quickstart/node-api-key) is required. Without one, requests return `401 Unauthorized`.
</Info>

## Purpose

* Fetch market data (prices, depth, trades, candlesticks) and account views (orders, positions, Trading Accounts).
* Works over REST and Aptos views. No signing or private keys required.

## When to use

* Use for dashboards, analytics, and read-heavy server/frontend use cases.
* Do not use for submitting transactions; use the Write SDK instead.

## Initialization

```ts theme={null}
import { DecibelReadDex, TESTNET_CONFIG } from "@decibeltrade/sdk";

const read = new DecibelReadDex(TESTNET_CONFIG, {
  // Required: SDK will send Authorization: Bearer <YOUR_NODE_API_KEY> on fullnode requests
  nodeApiKey: process.env.APTOS_NODE_API_KEY!,
  onWsError: (e) => console.warn("WS error", e), // optional
  onChainFallback: ({ method }) => console.warn(`${method} fell back to chain views`), // optional
});
```

## Main readers

* Markets: `read.markets.getAll()`, `getByName()`
* Prices: `read.marketPrices.getAll()`, `getByName()`, `subscribeByName()`
* Depth: `read.marketDepth.getByName()`
* Trades: `read.marketTrades.getByName()`
* Candlesticks: `read.candlesticks.getByName()`, `subscribeByName()`
* Accounts and orders:
  * `read.accountOverview.getByAddr()`
  * `read.userFees.getByAddr()`
  * `read.userOpenOrders.getBySubaccount()` / `read.userOrderHistory.getBySubaccount()`
  * `read.userPositions.getBySubaccount()`
  * `read.userTradeHistory.getBySubaccount()`
  * `read.userSubaccounts.getByOwner()`
* Portfolio and leaderboard:
  * `read.portfolioChart.getByAddr()`
  * `read.leaderboard.getTopUsers()`
* Vaults and delegations:
  * `read.vaults.getUserOwned()` / `getAll()`
  * `read.delegations.getForSubaccount()`
* Funded First Trade:
  * `read.fundedFirstTrade.getEligibility()` / `getActiveTrial()`
  * `read.fundedFirstTrade.getTrialHistory()` / `getCampaignLocks()` (count-based pagination)
  * `read.fundedFirstTrade.subscribeByAddr()`

## Examples

### Markets

```ts theme={null}
const markets = await read.markets.getAll();
const btc = await read.markets.getByName("BTC-USD");
```

### Prices and candlesticks

```ts theme={null}
const price = await read.marketPrices.getByName("BTC-USD");

// Subscribe (unsubscribe by calling the returned function)
const unsubscribe = read.marketPrices.subscribeByName("BTC-USD", (msg) => {
  console.log("Price update", msg);
});

// Candlesticks
import { CandlestickInterval } from "@decibeltrade/sdk";
const candles = await read.candlesticks.getByName(
  "BTC-USD",
  CandlestickInterval.OneMinute,
  Date.now() - 60 * 60 * 1000,
  Date.now()
);
```

### Account views

```ts theme={null}
const addr = "0x...owner";
const overview = await read.accountOverview.getByAddr(addr);
const subs = await read.userSubaccounts.getByOwner(addr);
```

### User fees

```ts theme={null}
const subAddr = "0x....subaccount";
const fees = await read.userFees.getByAddr({ subAddr });
// fees.user_taker_rate, fees.user_maker_rate, fees.fee_tier (decimals; 0.00034 = 0.034%)
// fees.fee_schedule.tiers.vip[], fees.daily_user_volume[]
```

### User positions

```ts theme={null}
const subAddr = "0x....subaccount";

const stopPositions = read.userPositions.subscribeByAddr(subAddr, (data) => {
  data.positions.forEach((position) => {
    console.log("Position delta", position.market_name, position.open_size);
  });
});

// Stop streaming for this subaccount
stopPositions();
```

## Notes

* For raw REST/WS endpoints, see the API Reference tabs.