@piaa/sdk (Official TypeScript / JavaScript SDK)

The official, production-ready SDK for the PIA Market Intelligence & Realtime Financial Platform.

Designed for institutional algorithmic traders, fintech dashboards, and quantitative applications across Node.js 18+, Bun, Deno, and modern Browsers.

Features

• Zero-Fuss Sensible Defaults: Connect in 3 lines of code with pre-configured endpoints and sensible timeout/retry defaults.
• Dual Proxy-Resilient Auth: Transparently sends both standard Authorization: Bearer <key> and x-api-key headers to guarantee 100% compatibility across Cloudflare tunnels, WAFs, and internal gateways.
• Typed Error Hierarchy: Clear, actionable, strongly-typed errors (AuthenticationError, RateLimitError, TimeoutError, ValidationError, NetworkError).
• Derivatives & Macro Intelligence: Real-time Options Chain, Gamma Exposure (GEX), Fear & Greed Index, and CFTC Commitment of Traders (COT) positioning.
• Zero Sensitive Data Leaks: Automatic redaction of API keys, bearer tokens, and secrets from error logs and stack traces.
• Cross-Platform Realtime Streaming: Built-in resilient WebSocket client with In-Band Message Authentication, ping/pong keep-alives, and automatic re-subscription on reconnect.
• Rate Limit Telemetry: Real-time inspection of RFC 6585 and daily quota headers (X-RateLimit-*, X-DailyQuota-*).

Installation

# Using bun
bun add @piaa/sdk

# Using npm
npm install @piaa/sdk

# Using pnpm / yarn
pnpm add @piaa/sdk

Quickstart

1. REST API Usage

import { PiaClient, RateLimitError, AuthenticationError } from "@piaa/sdk";

// Automatically picks up process.env.PIA_API_KEY if omitted
const client = new PiaClient({
  apiKey: "wi_live_...",
});

async function run() {
  try {
    // 1. Fetch live multi-asset snapshot & symbol catalog
    const symbols = await client.market.getSymbols({ asset_type: "crypto" });
    console.log(`Available crypto symbols: ${symbols.total}`);

    const prices = await client.market.getPrices();
    console.log(`Tracked assets: ${prices.total}`);
    for (const item of prices.items.slice(0, 5)) {
      console.log(`[${item.symbol}] $${item.price} (${item.asset_type})`);
    }

    // 2. Fetch historical OHLCV candlesticks
    const candles = await client.market.getCandles("XAUUSD", {
      timeframe: "1h",
      limit: 100,
    });
    console.log(`Fetched ${candles.count} bars for ${candles.symbol}`);

    // 3. Options Chain & Gamma Exposure (GEX)
    const gex = await client.options.getGex("SPX");
    console.log(`SPX Net GEX: $${gex.net_gex?.toLocaleString()} (0-Gamma: ${gex.zero_gamma_level})`);

    // 4. Macro Sentiment & Positioning (Fear & Greed, COT)
    const fg = await client.macro.getFearGreed();
    console.log(`Fear & Greed Index: ${fg.score} (${fg.rating})`);

    const cot = await client.macro.getCot("GOLD");
    console.log(`Gold Commercial Net: ${cot.reports[0]?.net_position}`);

    // 5. Social Discussions & Breaking News
    const posts = await client.social.getPosts({ limit: 10, symbol: "BTC" });
    console.log(`Latest post by @${posts.items[0]?.author_username}: "${posts.items[0]?.text}"`);

    // 6. Inspect rate limit telemetry
    const quota = client.getRateLimitInfo();
    console.log(`Remaining daily hits: ${quota.dailyRemaining}/${quota.dailyLimit}`);
  } catch (err) {
    if (err instanceof AuthenticationError) {
      console.error("Invalid or expired API key.");
    } else if (err instanceof RateLimitError) {
      console.error(`Rate limited! Retry after ${err.retryAfterSeconds} seconds.`);
    } else {
      console.error("API error:", err);
    }
  }
}

run();

2. Realtime WebSocket Streaming (In-Band Message Auth)

Cross-platform streaming without query-string token leakage:

import { PiaClient } from "@piaa/sdk";

const client = new PiaClient({ apiKey: "wi_live_..." });

// Listen for connection events
client.realtime.on("connect", () => {
  console.log("WebSocket connected. Authenticating...");
});

// Fired once In-Band authentication is accepted by the server
client.realtime.on("authenticated", (info) => {
  console.log("Authenticated! Tier:", info.plan);

  // Subscribe to market symbols
  client.realtime.subscribe(["XAUUSD", "BTCUSDT", "EURUSD"]);
});

// Handle real-time price ticks
client.realtime.on("tick", (tick) => {
  console.log(`[TICK] ${tick.symbol} -> $${tick.price} (bid: ${tick.bid}, ask: ${tick.ask})`);
});

// Handle disconnections (auto-reconnect is handled automatically)
client.realtime.on("disconnect", ({ code, reason }) => {
  console.warn(`WebSocket closed (${code}): ${reason}`);
});

// Start streaming
client.realtime.connect();

// To stop and prevent auto-reconnection:
// client.realtime.disconnect();

Complete Resource Reference

| Resource | Methods | Endpoint | Description | |---|---|---|---| | client.market | getPrices(), getCandles(), getOrderBook() | /api/v1/market/* | Live price snapshot, ClickHouse OHLCV candles, and Level 2 DOM. | | client.options | getChain(), getGex(), getSummary() | /api/v1/options/* | Full options chain, Gamma Exposure levels, and put/call sentiment. | | client.macro | getFearGreed(), getCot(), getCentralBankStance() | /api/v1/fear-greed, /api/v1/cot/*, /api/v1/central-banks/* | Fear & Greed sentiment index, CFTC institutional COT reports, and central bank monetary policy stance. | | client.social | getPosts(), getFeed() | /api/v1/social/* | Real-time social sentiment and discussion feeds from Twitter/𝕏. | | client.news | getNews() | /api/v1/news | Curated multi-asset financial news headlines and articles. | | client.economic | getCalendar() | /api/v1/economic/calendar | Global economic calendar events, CPI releases, and rate decisions. | | client.fixedIncome | getYieldCurve() | /api/v1/rates/yield-curve | Benchmark sovereign bond yield curves across tenors. | | client.ws | createTicket() | /api/v1/ws/ticket | Ephemeral single-use WebSocket connection tickets. | | client.realtime | connect(), subscribe(), unsubscribe(), disconnect() | /api/v1/ws | Low-latency streaming socket client with event emitters. |

Configuration Reference

const client = new PiaClient({
  // Secret API key. Falls back to process.env.PIA_API_KEY
  apiKey: "wi_live_...",

  // Unified REST gateway (Default: "https://api-engine.wign.dev")
  baseUrl: "https://api-engine.wign.dev",

  // Realtime streaming gateway (Default: "wss://api-engine.wign.dev/api/v1/ws")
  wsUrl: "wss://api-engine.wign.dev/api/v1/ws",

  // Request timeout in milliseconds (Default: 15,000)
  timeoutMs: 10_000,

  // Maximum retry attempts for transient errors (Default: 3)
  maxRetries: 3,

  // Initial retry delay for exponential backoff (Default: 500ms)
  retryDelayMs: 500,

  // Custom HTTP headers injected into all requests
  headers: {
    "X-Client-App": "my-trading-bot",
  },

  // Custom fetch implementation (useful for mocking or custom proxies)
  fetch: customFetch,

  // Custom WebSocket implementation (e.g. 'ws' in Node.js)
  WebSocket: customWebSocket,

  // Enable verbose debug logs (Default: false)
  debug: false,
});

Error Handling

All errors thrown by the SDK inherit from PiaError:

| Error Class | HTTP Status | Description | Properties | |---|---|---|---| | ConfigurationError | N/A | Missing or invalid client configuration | message | | ValidationError | N/A | Invalid method arguments (e.g. empty symbol) | paramName | | AuthenticationError | 401 | Invalid, expired, or revoked API key | statusCode, endpoint | | PermissionError | 403 | API key lacks required scope (e.g. realtime:ws) | requiredScope | | RateLimitError | 429 | Rate limit or daily quota exceeded | retryAfterSeconds, dailyRemaining, minuteRemaining | | TimeoutError | 408 / N/A | Request exceeded configured timeoutMs | timeoutMs, endpoint | | NetworkError | N/A | Network drop, DNS resolution failure | causeError | | ParseError | N/A | Response was not valid JSON | rawText | | ApiError | Other | General HTTP errors | statusCode, rawBody |

Testing

Run the test suite using Bun:

bun test