JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 32
  • Score
    100M100P100Q78360F
  • License MIT

TypeScript SDK for Ironflow market data API — on-chain derivatives data

Package Exports

  • @ironflowsh/sdk

Readme

@ironflowsh/sdk

TypeScript SDK for the Ironflow market data API — on-chain derivatives data.

  • Zero runtime dependencies (native fetch)
  • Full TypeScript types for all endpoints and WebSocket streams
  • Automatic pagination with async page.next()
  • Typed error classes with retry-after support

Install

npm install @ironflowsh/sdk

Requires Node.js 18+ (uses native fetch and WebSocket).

Quick Start

import { Ironflow } from "@ironflowsh/sdk";

const client = new Ironflow("if_your_api_key");

// Get recent trades
const page = await client.trades("BTC-PERP", { limit: 10 });
for (const trade of page.data) {
  console.log(trade.price, trade.size, trade.side);
}

// Paginate
if (page.hasMore) {
  const next = await page.next();
}

Configuration

const client = new Ironflow("if_your_api_key", {
  baseUrl: "https://api.ironflow.sh",  // default
  source: "hyperliquid",               // default
  timeout: 30_000,                     // request timeout in ms (default: 30s)
});

REST Endpoints

Market Data

// Trades
const trades = await client.trades("BTC-PERP", { limit: 100 });

// Fills (requires address)
const fills = await client.fills({ address: "0xabc...", market: "ETH-PERP" });

// Order book snapshot
const book = await client.book("BTC-PERP");
// book.bids[0].price, book.bids[0].size

// OHLCV candles
const candles = await client.candles("BTC-PERP", "1h", { limit: 24 });

// Liquidations
const liqs = await client.liquidations("BTC-PERP");

// Funding rates
const rates = await client.funding("BTC-PERP");

// Open interest
const oi = await client.openInterest("BTC-PERP");

// Mark prices
const prices = await client.markPrices("BTC-PERP");

// Deposits & withdrawals
const deps = await client.deposits({ address: "0xabc..." });
const wds = await client.withdrawals({ address: "0xabc..." });

// Order statuses
const orders = await client.orderStatuses({ address: "0xabc..." });

// Vault operations
const vaults = await client.vaultOperations({ vault: "HLP" });

Analytics (Builder+)

const flows = await client.netFlows({ interval: "1d", limit: 7 });
// flows[0].deposits, flows[0].withdrawals, flows[0].net_flow

const levels = await client.liquidationLevels("BTC-PERP", { bucket_size: 100 });
// levels[0].price_bucket, levels[0].count, levels[0].total_size

const orderFlow = await client.orderFlow();
// orderFlow[0].total_orders, orderFlow[0].filled_orders, orderFlow[0].fill_rate

const leaderboard = await client.vaultLeaderboard();
// leaderboard[0].vault, leaderboard[0].total_deposits, leaderboard[0].net_flow

const funding = await client.fundingStats("BTC-PERP", { interval: "8h" });
// funding[0].avg_rate, funding[0].min_rate, funding[0].max_rate

Triggers

// Create a webhook trigger
const trigger = await client.createTrigger({
  name: "whale-alert",
  channel: "trades",
  webhook_url: "https://your-server.com/hook",
  rule: {
    condition: { field: "data.size", op: "gt", value: "100" },
  },
});

// List, toggle, delete
const triggers = await client.listTriggers();
await client.toggleTrigger(trigger.id, false);
await client.deleteTrigger(trigger.id);

// Test a rule without creating
const result = await client.testTrigger({
  rule: { condition: { field: "data.size", op: "gt", value: "10" } },
  event: { data: { size: "50", market: "BTC-PERP" } },
});
console.log(result.matched); // true

Cohorts (Enterprise)

const cohorts = await client.listCohorts();
const addrs = await client.cohortAddresses("top_pnl_30d");
await client.createCohort({ name: "my_whales", addresses: ["0xabc..."] });
await client.deleteCohort("my_whales");

Export (Builder+)

const data = await client.exportData({
  event_type: "fills",
  market: "BTC-PERP",
  format: "csv",
});
// data is Uint8Array — write to file or parse

Status

const status = await client.status();
console.log(status.status); // "ok"
console.log(status.venues.hyperliquid.streams.fills.age_seconds);

Info API Proxy

const meta = await client.info({ type: "metaAndAssetCtxs" });

WebSocket Streaming

All stream methods return typed AsyncIterable objects:

// Real-time trades
for await (const trade of client.stream.trades("BTC-PERP")) {
  console.log(trade.price, trade.size, trade.side);
}

// Wallet fills (copy trading)
for await (const fill of client.stream.fills("0xleader")) {
  console.log(fill.side, fill.size, fill.market);
}

// Order book updates
for await (const snap of client.stream.book("ETH-PERP")) {
  console.log(snap.bids[0].price, snap.asks[0].price);
}

// Filter by minimum size
for await (const trade of client.stream.trades("BTC-PERP", { min_size: "10" })) {
  // Only trades >= 10 BTC
}

Available streams: trades, fills, book, bookL4, orders, liquidations, fundingRates, deposits, withdrawals, vaultOperations.

Error Handling

import { Ironflow, RateLimitError, AuthError, TierError, QueryWindowError } from "@ironflowsh/sdk";

try {
  const trades = await client.trades("BTC-PERP");
} catch (err) {
  if (err instanceof RateLimitError) {
    // Retry after the specified delay
    console.log(`Rate limited, retry in ${err.retryAfterMs}ms`);
  } else if (err instanceof AuthError) {
    console.log("Invalid API key");
  } else if (err instanceof TierError) {
    console.log("Upgrade your plan for this endpoint");
  } else if (err instanceof QueryWindowError) {
    console.log("Time range too wide for your tier");
  }
}

Pagination

All list endpoints return a Page<T> with async pagination:

let page = await client.trades("BTC-PERP", { limit: 1000 });
const allTrades = [...page.data];

while (page.hasMore) {
  page = await page.next();
  allTrades.push(...page.data);
}

License

MIT