PredictionData TypeScript Client

A TypeScript/Node.js library for streaming historical market data from the PredictionData API. Access order books, trades, and on-chain fills for prediction markets.

Installation

npm install predictiondata

or

yarn add predictiondata

Quick Start

import { PredictionDataClient, Channel } from 'predictiondata';

const client = new PredictionDataClient({ apiKey: '<YOUR_API_KEY>' });

const messages = client.replay({
  exchange: 'polymarket',
  fromDate: '2024-11-01',
  toDate: '2024-11-15',
  filters: [new Channel({ name: 'trades', symbols: ['will-trump-win-2024/YES'] })],
});

for await (const [exchangeTimestamp, message] of messages) {
  console.log(`Time: ${exchangeTimestamp}ms, Trade: ${JSON.stringify(message)}`);
}

Features

• Async iteration - Efficiently stream large amounts of historical data
• Multiple data types - Access order books, trades, and on-chain fills
• Flexible filtering - Filter by market slug or token ID
• Type-safe - Full TypeScript support with type definitions
• Node.js compatible - Works in Node.js 14+

Data Types

Order Books

Incremental order book reconstructions with bid/ask prices and sizes.

new Channel({ name: 'books', symbols: ['will-trump-win-2024/YES'] });

Schema:

• exchange_timestamp (string): Exchange timestamp in milliseconds
• local_timestamp (string): Server capture timestamp in milliseconds
• ask_prices (string): Comma-separated ask prices
• ask_sizes (string): Comma-separated ask sizes
• bid_prices (string): Comma-separated bid prices
• bid_sizes (string): Comma-separated bid sizes

Trades

Executed trades from the order book.

new Channel({ name: 'trades', symbols: ['will-trump-win-2024/YES'] });

Schema:

• exchange_timestamp (string): Exchange timestamp in milliseconds
• local_timestamp (string): Server capture timestamp in milliseconds
• side (string): "BUY" or "SELL"
• size (number): Trade size
• price (number): Trade price

On-chain Fills

On-chain settlement data from blockchain transactions.

new Channel({ name: 'onchain_fills', symbols: ['will-trump-win-2024/YES'] });

Schema:

• block_number (number): Blockchain block number
• block_timestamp (string): Block timestamp in milliseconds
• side (string): "BUY" or "SELL"
• size (number): Fill size
• price (number): Fill price
• maker (string): Maker address
• taker (string): Taker address

Usage Examples

Stream Multiple Markets

import { PredictionDataClient, Channel } from 'predictiondata';

const client = new PredictionDataClient({ apiKey: 'your_api_key' });

const messages = client.replay({
  exchange: 'polymarket',
  fromDate: '2024-11-01',
  toDate: '2024-11-15',
  filters: [
    new Channel({
      name: 'trades',
      symbols: ['will-trump-win-2024/YES', 'will-biden-win-2024/YES'],
    }),
  ],
});

for await (const [exchangeTimestamp, message] of messages) {
  console.log(`Market: ${message._symbol}`);
  console.log(`Side: ${message.side}, Size: ${message.size}, Price: ${message.price}`);
}

Use Token IDs Instead of Slugs

new Channel({ name: 'onchain_fills', tokenIds: ['0x1234567890abcdef...'] });

Fetch Single Day

For non-streaming use cases, fetch a complete day of data:

const data = await client.fetchDay({
  exchange: 'polymarket',
  dataType: 'trades',
  identifier: 'will-trump-win-2024/YES',
  date: '2024-11-15',
});

console.log(`Found ${data.length} trades`);

API Reference

PredictionDataClient

Main client class for accessing the PredictionData API.

Constructor:

new PredictionDataClient(options: {
  apiKey: string;
  baseUrl?: string; // default: 'http://datasets.predictiondata.dev'
})

Methods:

• replay(options) - Stream historical data
  • Returns: AsyncGenerator<[number, Message]>
• fetchDay(options) - Fetch single day
  • Returns: Promise<Message[]>

Channel

Represents a data channel filter.

Constructor:

new Channel(config: {
  name: string | DataType;
  symbols?: string[];
  tokenIds?: string[];
})

• name: Data type - "books", "trades", or "onchain_fills"
• symbols: List of market slugs (format: "event-slug/OUTCOME")
• tokenIds: List of token IDs (alternative to symbols)

Types

• DataType - Enum of available data types
• Message - Base message interface
• BookMessage - Order book message type
• TradeMessage - Trade message type
• OnchainFillMessage - On-chain fill message type

Market Identifiers

Markets can be identified by either:

1. Slug (format: event-slug/OUTCOME):

   • Example: will-trump-win-2024/YES
   • Use for human-readable queries

2. Token ID (contract address):

   • Example: 0x1234567890abcdef...
   • Use for programmatic queries

Error Handling

The client handles missing data gracefully. Missing data files (404 responses) are skipped automatically.

for await (const [exchangeTimestamp, message] of client.replay(options)) {
  try {
    // Process message
  } catch (error) {
    console.error(`Error processing message: ${error}`);
  }
}

Development

Install Dependencies

npm install

Build

npm run build

Run Tests

npm test

Lint

npm run lint

Format Code

npm run format

License

MIT License

Support

• Documentation: https://predictiondata.dev/docs
• Issues: https://github.com/predictiondata/predictiondata-ts/issues
• Email: [email protected]

Changelog

0.1.1 (2024-11-17)

• Updated documentation to clarify multi-exchange support

0.1.0 (2024-11-17)

• Initial release
• Support for books, trades, and on-chain fills
• Async iteration API
• Market filtering by slug or token ID