JavaScript SDK

Official JavaScript/TypeScript SDK for the Windy Network API.

Features

  • Full API Coverage: REST endpoints for crypto, stocks, forex, options, and market calendar
  • Multiple Auth Methods: API Key, Basic Auth, OAuth 2.0 (all grant types)
  • Real-time Streaming: WebSocket, Server-Sent Events (SSE), and long-polling
  • TypeScript First: Full type definitions for all endpoints and responses
  • Universal: Works in Node.js 18+ and all modern browsers
  • Zero Dependencies: Uses native fetch and WebSocket APIs

Installation

npm install @windy-network/client-js

Quick Start

import { WindyClient } from '@windy-network/client-js';

// Create client with API key
const client = WindyClient('your-api-key');

// Get crypto rate
const btc = await client.crypto.getRate('BTC', 'USD');
console.log(`BTC: $${btc.rate}`);

// Get stock quote
const apple = await client.stocks.getQuote('AAPL');
console.log(`AAPL: $${apple.price}`);

// Get forex rate
const eurUsd = await client.forex.getRate('EUR', 'USD');
console.log(`EUR/USD: ${eurUsd.rate}`);

Authentication

API Key

const client = WindyClient('your-api-key');

// Or with full config
const client = WindyClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.windy.network',
});

Basic Auth

const client = WindyClient({
  auth: {
    type: 'basic',
    username: 'your-username',
    password: 'your-password',
  },
});

OAuth 2.0

import { WindyClient, OAuthClient } from '@windy-network/client-js';

// Client credentials grant (server-to-server)
const client = WindyClient({
  auth: {
    type: 'oauth',
    clientId: 'your-client-id',
    clientSecret: 'your-secret',
    scopes: ['crypto:read', 'stock:read'],
  },
});

// Get OAuth client for manual token management
const oauth = client.getAuthProvider() as OAuthClient;
await oauth.clientCredentialsGrant();

// Now use the client
const rates = await client.crypto.getRates();

REST API

Crypto

// Get single rate
const rate = await client.crypto.getRate('BTC', 'USD');

// Get multiple rates
const rates = await client.crypto.getRates({
  symbols: ['BTC', 'ETH', 'SOL'],
});

// Get ticker from exchange
const ticker = await client.crypto.getTicker('binance', 'BTC', 'USDT');

// Get OHLC candlesticks
const ohlc = await client.crypto.getOHLC('BTC', 'USD', {
  timeframe: 'h1',
  limit: 100,
});

// Get technical indicators
const rsi = await client.crypto.getRSI('BTC', 'USD', {
  timeframe: 'h1',
  period: 14,
});

// Get orderbook
const orderbook = await client.crypto.getOrderbook('BTC', 'USD', {
  depth: 20,
});

// Get market summary
const summary = await client.crypto.getMarketSummary();

// Get top gainers/losers
const gainers = await client.crypto.getGainers({ limit: 10 });
const losers = await client.crypto.getLosers({ limit: 10 });

Stocks

const quote = await client.stocks.getQuote('AAPL');
const quotes = await client.stocks.getQuotes({ symbols: ['AAPL', 'GOOGL', 'MSFT'] });

Forex

const rate = await client.forex.getRate('EUR', 'USD');
const rates = await client.forex.getRates({ base: 'USD', quotes: ['EUR', 'GBP', 'JPY'] });

Options

const chain = await client.options.getChain('AAPL', {
  expiration: '2024-12-20',
});

Market Calendar

// Get full calendar status
const status = await client.calendar.getStatus();

// Get forex sessions
const sessions = await client.calendar.getForexSessions();

// Get exchange hours
const nyse = await client.calendar.getExchange('NYSE');

// Get holidays
const holidays = await client.calendar.getHolidays({ year: 2024 });

User Features

// Alerts
const alerts = await client.user.getAlerts();
const alert = await client.user.createAlert({
  symbol: 'BTC',
  type: 'price_above',
  target_value: 50000,
});

// Watchlists
const watchlists = await client.user.getWatchlists();
const watchlist = await client.user.createWatchlist({
  name: 'My Crypto',
  symbols: ['BTC', 'ETH', 'SOL'],
});

// Portfolio
const portfolio = await client.user.getPortfolio();
const positions = await client.user.getPositions();

Real-time Streaming

WebSocket

const ws = client.streaming.websocket();

ws.on('connect', () => console.log('Connected'));
ws.on('error', (err) => console.error(err));
ws.on('reconnect', (attempt) => console.log('Reconnecting...', attempt));

await ws.connect();

// Subscribe to channels
const sub = ws.subscribe('crypto:rate:BTC:USD', (message) => {
  console.log('BTC:', message.data.rate);
});

// Unsubscribe
sub.unsubscribe();

// Disconnect
await ws.disconnect();

Server-Sent Events (SSE)

const sse = client.streaming.sse();

sse.subscribe('crypto:rate:BTC:USD', (message) => {
  console.log('BTC:', message.data.rate);
});

await sse.connect();

Long-Polling

const polling = client.streaming.polling();

polling.subscribe('crypto:rate:BTC:USD', (message) => {
  console.log('BTC:', message.data.rate);
});

await polling.connect();

Error Handling

import {
  WindyClient,
  ApiError,
  AuthenticationError,
  RateLimitError,
  NetworkError,
} from '@windy-network/client-js';

try {
  const rate = await client.crypto.getRate('BTC', 'USD');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof ApiError) {
    console.error(`API error: ${error.message} (${error.code})`);
  }
}

Configuration

const client = WindyClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.windy.network', // REST API base
  websocketUrl: 'wss://ws.windy.network/v1/crypto/stream/ws',
  sseUrl: 'https://api.windy.network/v1/crypto/stream/sse',
  timeout: 30000, // Request timeout in ms
  retries: 3, // Max retry attempts
});

TypeScript

All types are exported and can be imported:

import type {
  CryptoRate,
  Ticker,
  OHLCData,
  StockQuote,
  ForexRate,
  Alert,
  Watchlist,
  StreamMessage,
} from '@windy-network/client-js';

Requirements

  • Node.js 18+ or modern browser
  • ES2022+ environment

Source Code

The SDK source code is available on GitHub: