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

# TypeScript SDK

> Official TypeScript/Node.js SDK for the Ironflow API.

<Note>
  **Package:** `@ironflowsh/sdk`\
  **Requires:** Node.js 18+ or any runtime with native `fetch`
</Note>

## Installation

```bash theme={null}
npm install @ironflowsh/sdk
```

## Setup

```typescript TypeScript theme={null}
import { Ironflow } from "@ironflowsh/sdk";

const client = new Ironflow("if_your_api_key");

// Optional: custom base URL or source
const client = new Ironflow("if_your_api_key", {
  baseUrl: "https://api.ironflow.sh",
  source: "hyperliquid",
});
```

## Account & status

```typescript TypeScript theme={null}
// Liveness probe (no auth required)
const health = await client.healthz();        // { status: "ok" }

// Public component status + freshness
const status = await client.status();

// Rolling-window API + pipeline + synthetic metrics (no auth required)
const metrics = await client.statusMetrics();
console.log(metrics.api.latency_p99_ms, metrics.pipeline.events_per_sec);

// Uptime / freshness timeline — "24h" (default) or "7d"
const history = await client.statusHistory("7d");
console.log(history.uptime_percent, history.points.length);
```

## Markets registry

```typescript TypeScript theme={null}
// Every active market across all classes + issuers
const all = await client.markets();

// Filter by class and/or issuer
const perps    = await client.markets({ market_class: "perp" });
const spot     = await client.markets({ market_class: "spot" });
const outcomes = await client.markets({ market_class: "prediction" }); // HIP-4 binary outcomes
const native   = await client.markets({ issuer: "" });        // native non-builder only
const flxOnly  = await client.markets({ issuer: "flx" });     // HIP-3 builder

// Each row carries the full v3 identity tuple, so it joins with /v1/* responses:
//   { market_id, source, market_class, issuer,
//     base_asset, quote_asset, base_market, display_symbol,
//     hl_coin, active_from_ms }
```

This endpoint reads the registry directly — no per-tier query window applies.

## REST API

All REST methods return a `Page<T>` with `.data`, `.hasMore`, and `.next()`:

```typescript TypeScript theme={null}
// Trades
const trades = await client.trades("BTC-PERP", { limit: 100 });
const fills  = await client.fills({ address: "0xabc", market: "BTC-PERP" });
const candles = await client.candles("BTC-PERP", "1h", { limit: 24 });

// More endpoints
const funding = await client.funding("BTC-PERP");
const oi      = await client.openInterest("BTC-PERP");
const marks   = await client.markPrices("BTC-PERP");
```

## HIP-3 builder markets

Pass the full canonical symbol (`<issuer>:<base>-PERP`) as the `market` argument. Every response object carries `market`, `issuer`, and `base_market` — group by `issuer` to compare builders, by `base_market` to combine builds. Native HL perps return `issuer: ""` and `market === base_market`.

```typescript TypeScript theme={null}
// Felix Exchange's natural-gas perp
const gas = await client.trades("flx:GAS-PERP", { limit: 100 });

// XYZ's NVDA-PERP
const nvda = await client.trades("xyz:NVDA-PERP", { limit: 100 });
for (const trade of nvda.data) {
  console.log(trade.issuer, trade.base_market, trade.price);
  // → "xyz" "NVDA-PERP" "881.20"
}
```

For **cross-issuer** queries (every builder's GOLD-PERP in one call) use the `base_market` + omitted-`issuer` form via cURL — the typed REST methods take `market` as their first argument. See [Sources & Markets](/concepts/sources-and-markets) for the full filter scheme.

## HIP-4 outcome contracts

HIP-4 binary prediction markets (live since 2026-05-02) carry `market_class: "prediction"`. Display symbols read as `{UNDERLYING}-{TARGET}-{EXPIRY}-{Yes|No}` and complementary outcomes have prices summing to 1.0 (the implied probability).

```typescript TypeScript theme={null}
// Latest trades on the "Yes" side of the BTC-above-$78,213 daily binary
const ticks = await client.trades("BTC-78213-20260503-Yes", { limit: 10 });
for (const t of ticks.data) {
  console.log(`Yes @ ${t.price}, size ${t.size}`); // price ∈ (0, 1)
}

// Historical fills on the same market
const yes = await client.fills({ address: "0xabc", market: "BTC-78213-20260503-Yes" });

// Resolution metadata (target price, expiry, period) lives on /v1/markets
const outcomes = await client.markets({ market_class: "prediction" });
console.log(outcomes[0].metadata); // { class: "priceBinary", underlying: "BTC", expiry, targetPrice, period, ... }
```

Perp-only endpoints (`/v1/funding`, `/v1/open-interest`, `/v1/mark-prices`) return `400 INVALID_MARKET_CLASS` on prediction symbols — those concepts don't apply to fully-collateralized binaries.

## Pagination

```typescript TypeScript theme={null}
let page = await client.trades("BTC-PERP", { limit: 1000 });

while (true) {
  for (const trade of page.data) {
    process(trade);
  }
  if (!page.hasMore) break;
  page = await page.next();
}
```

## Vault Operations

```typescript TypeScript theme={null}
const ops = await client.vaultOperations({ vault: "0xvault_address" });
```

## Cohorts

```typescript TypeScript theme={null}
// List predefined + custom cohorts
const cohorts = await client.listCohorts();

// Create custom cohort
await client.createCohort({ name: "my_wallets", addresses: ["0xabc", "0xdef"] });

// Get addresses
const addrs = await client.cohortAddresses("top_pnl_30d");

// Delete
await client.deleteCohort("my_wallets");
```

## Analytics

`net-flows` and `funding-stats` work on every tier; `liquidation-levels`, `order-flow`, and `vault-leaderboard` require Builder or above.

```typescript TypeScript theme={null}
const flows    = await client.netFlows({ interval: "1d", limit: 7 });
const levels   = await client.liquidationLevels("BTC-PERP", { bucket_size: 100 });
const orderFlow = await client.orderFlow();
const vaults   = await client.vaultLeaderboard({ limit: 10 });
const funding  = await client.fundingStats("BTC-PERP", { interval: "1d" });
```

## Error handling

```typescript TypeScript theme={null}
import { Ironflow, RateLimitError, AuthError, TierError, IronflowError } from "@ironflowsh/sdk";

try {
  const page = await client.trades("BTC-PERP");
} catch (err) {
  if (err instanceof RateLimitError) {
    await sleep(err.retryAfterMs);
  } else if (err instanceof AuthError) {
    console.error("Invalid API key");
  } else if (err instanceof TierError) {
    console.error("Feature not available on your tier");
  } else if (err instanceof IronflowError) {
    console.error(err.code, err.status, err.message);
  }
}
```

## Full type reference

All response types are exported from the package:

```typescript TypeScript theme={null}
import type {
  Trade, BookSnapshot, BookLevel, Candle,
  FundingRate, Liquidation, OpenInterest, MarkPrice,
  Deposit, Withdrawal, OrderStatus, VaultOperation,
  Trigger, CreateTriggerRequest, TriggerRule,
  CohortInfo, CohortAddresses,
  NetFlow, LiquidationLevel, OrderFlow,
  VaultLeaderboardEntry, FundingStats,
  Market, MarketsResponse, MarketsOptions,
  StatusResponse, StatusMetricsResponse, StatusHistoryResponse, UptimePoint,
  MeResponse, HealthResponse,
  QueryOptions, CandleOptions, AnalyticsOptions,
} from "@ironflowsh/sdk";
```


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