trade-data-generator
Version:
Generate realistic real-time market data for trading UIs — equity, forex and crypto. Emits tick, candle, orderbook and market status events via EventEmitter.
444 lines (345 loc) • 12.3 kB
Markdown
# trade-data-generator
[](https://www.npmjs.com/package/trade-data-generator)
[](https://github.com/monupareeklg/trade-data-generator/blob/master/LICENSE)
[](https://www.npmjs.com/package/trade-data-generator)
[](https://www.npmjs.com/package/trade-data-generator)
[]()
[]()
The universal market data layer for trading UIs.
**Simulation** for development. **Real exchange data** for production.
Same API. Same format. One library.
## Why this exists
Building a trading UI requires live market data at every stage:
- **Development** — you need realistic fake data to build and test your UI
- **Production** — you need real exchange data for your users
Most developers use two completely different libraries for this — one for testing, one for production. That means rewriting your data handling code when you go live.
`trade-data-generator` solves both with one API. Switch from simulation to real Binance data by changing one line.
## Features
- **Simulation mode** — realistic fake data, zero API keys, works offline
- **Binance connector** — real-time Binance WebSocket data, no API key needed
- **Same API for both** — switch sources with one config change
- **Pluggable connectors** — build your own connector for any exchange
- **Realistic price engine** — mean reversion, volatility, trend bias
- **Accurate order book** — bid always below ask, volume tapers with depth
- **OHLCV candles** — multiple intervals simultaneously
- **Market hours** — equity and forex respect open/close times
- **EventEmitter API** — wire into any WebSocket server
- **Zero dependencies** — nothing extra installs
- **TypeScript support** — full `.d.ts` definitions included
- **167 tests** — 91.9% coverage
## Installation
```bash
npm install trade-data-generator
```
## The core idea
```javascript
const { MarketFeed } = require("trade-data-generator");
// Development — realistic fake data
const feed = new MarketFeed({
source: "simulation", // default, can be omitted
type: "crypto",
pairs: [{ symbol: "BTC/USDT", startPrice: 45000 }],
});
// Production — real Binance data (one line change)
const feed = new MarketFeed({
source: "binance", // switch source
type: "crypto",
pairs: [{ symbol: "BTC/USDT" }], // no startPrice needed
});
// Same events. Same format. Always.
feed.on("tick", (data) => console.log(data));
feed.on("candle", (data) => console.log(data));
feed.on("depth", (data) => console.log(data));
feed.start();
```
## Sources
### `simulation` (default)
Generates realistic synthetic market data locally.
No network calls. No API keys. Works offline.
```javascript
const feed = new MarketFeed({
source: "simulation", // or omit — simulation is the default
type: "crypto",
pairs: [
{ symbol: "BTC/USDT", startPrice: 45000, volatility: 0.004 },
{ symbol: "ETH/USDT", startPrice: 2800, volatility: 0.005 },
{ symbol: "SOL/USDT", startPrice: 120, volatility: 0.008 },
],
});
```
### `binance`
Real-time market data from Binance public WebSocket.
No API key required.
```javascript
const feed = new MarketFeed({
source: "binance",
type: "crypto",
pairs: [
{ symbol: "BTC/USDT" },
{ symbol: "ETH/USDT" },
{ symbol: "SOL/USDT" },
],
});
```
Streams per symbol:
- `@ticker` — price, volume, 24h stats
- `@depth10` — order book top 10 levels
- `@kline_*` — candles per interval
Auto-reconnect with exponential backoff included.
### Custom connectors
Build your own connector for any exchange or data source:
```javascript
const {
MarketFeed,
BaseConnector,
registerConnector,
} = require("trade-data-generator");
class MyExchangeConnector extends BaseConnector {
async connect() {
/* open WebSocket */
}
async disconnect() {
/* close WebSocket */
}
async subscribe(symbols) {
/* subscribe to pairs */
}
async unsubscribe(symbols) {
/* unsubscribe */
}
normalizeTick(raw) {
/* convert to standard format */
}
normalizeCandle(raw) {
/* convert to standard format */
}
normalizeDepth(raw) {
/* convert to standard format */
}
}
registerConnector("myexchange", MyExchangeConnector);
const feed = new MarketFeed({
source: "myexchange",
type: "crypto",
pairs: [{ symbol: "BTC/USDT" }],
});
```
## WebSocket integration
The library emits events — you own the WebSocket server.
Works with Socket.io, ws, Pusher, Ably or any transport.
```javascript
const { MarketFeed } = require("trade-data-generator");
const { Server } = require("socket.io");
const http = require("http");
const server = http.createServer();
const io = new Server(server, { cors: { origin: "*" } });
const feed = new MarketFeed({
source: "binance",
type: "crypto",
pairs: [{ symbol: "BTC/USDT" }, { symbol: "ETH/USDT" }],
});
feed.on("tick", (data) => io.to(data.symbol).emit("ticker", data));
feed.on("candle", (data) => io.to(data.symbol).emit("candle", data));
feed.on("depth", (data) => io.to(data.symbol).emit("orderbook", data));
io.on("connection", (socket) => {
socket.on("subscribe", ({ symbol }) => {
socket.join(symbol);
socket.emit("snapshot", feed.getState(symbol));
});
socket.on("unsubscribe", ({ symbol }) => {
socket.leave(symbol);
});
});
feed.start();
server.listen(3001);
```
## Market types
### Crypto — always open
```javascript
const feed = new MarketFeed({
type: "crypto",
pairs: [
{ symbol: "BTC/USDT", startPrice: 45000, volatility: 0.004, precision: 2 },
{ symbol: "ETH/USDT", startPrice: 2800, volatility: 0.005, precision: 2 },
],
});
```
### Equity — market hours
```javascript
const feed = new MarketFeed({
type: "equity",
marketHours: {
open: "09:30",
close: "16:00",
timezone: "America/New_York",
days: [1, 2, 3, 4, 5],
},
pairs: [
{ symbol: "AAPL", startPrice: 175.5, volatility: 0.002, precision: 2 },
{ symbol: "GOOGL", startPrice: 142.3, volatility: 0.003, precision: 2 },
],
});
```
### Forex — pip precision
```javascript
const feed = new MarketFeed({
type: "forex",
marketHours: {
open: "00:00",
close: "23:59",
timezone: "UTC",
days: [1, 2, 3, 4, 5],
},
pairs: [
{ symbol: "EUR/USD", startPrice: 1.0845, volatility: 0.0003, precision: 5 },
{ symbol: "GBP/USD", startPrice: 1.2678, volatility: 0.0004, precision: 5 },
{ symbol: "USD/JPY", startPrice: 149.85, volatility: 0.0002, precision: 3 },
],
});
```
## Events
```javascript
feed.on("tick", (data) => {
// {
// symbol: 'BTC/USDT',
// type: 'crypto',
// source: 'binance',
// timestamp: 1714900000000,
// price: 80920.00,
// bid: 80920.00,
// ask: 80920.01,
// spread: 0.01,
// volume: 14376.18,
// change: +88.68,
// changePct: +0.11,
// high24h: 82479.32,
// low24h: 80279.77,
// open24h: 80831.32,
// previous: 80919.99,
// }
});
feed.on("candle", (data) => {
// {
// symbol: 'BTC/USDT',
// interval: '1m',
// openTime: 1714900000000,
// closeTime: 1714900060000,
// open: 80900.00,
// high: 80950.00,
// low: 80880.00,
// close: 80920.00,
// volume: 42.18,
// closed: true,
// source: 'binance',
// }
});
feed.on("depth", (data) => {
// {
// symbol: 'BTC/USDT',
// timestamp: 1714900000000,
// source: 'binance',
// bids: [{ price, volume, side }, ...10 levels],
// asks: [{ price, volume, side }, ...10 levels],
// }
});
feed.on("open", (info) => {}); // market opened (equity/forex)
feed.on("closed", (info) => {}); // market closed (equity/forex)
feed.on("error", (err) => {}); // error on a symbol
```
## Configuration
### MarketFeed options
| Option | Type | Default | Description |
| ----------------- | ---------- | -------------- | --------------------------------------- |
| `source` | `string` | `'simulation'` | `'simulation'` \| `'binance'` \| custom |
| `type` | `string` | required | `'crypto'` \| `'forex'` \| `'equity'` |
| `pairs` | `Array` | required | Array of pair configs |
| `interval` | `number` | `1000` | Ms between ticks (simulation only) |
| `candleIntervals` | `string[]` | `['1m']` | Candle intervals to track |
| `depth` | `number` | `10` | Order book levels each side |
| `maxCandles` | `number` | `1000` | Max candle history (simulation only) |
| `marketHours` | `Object` | — | Required for `equity` and `forex` |
### Pair options
| Option | Type | Required | Description |
| ------------ | -------- | --------------- | ---------------------------- |
| `symbol` | `string` | always | e.g. `'BTC/USDT'` |
| `startPrice` | `number` | simulation only | Initial price |
| `volatility` | `number` | — | Max % move per tick |
| `trend` | `number` | — | Drift per tick |
| `precision` | `number` | — | Decimal places |
| `tickSize` | `number` | — | Minimum price increment |
| `spreadPct` | `number` | — | Bid/ask spread as % of price |
| `volume` | `Object` | — | `{ min: 100, max: 10000 }` |
### Candle intervals
`'1s'` `'1m'` `'5m'` `'15m'` `'1h'` `'4h'` `'1d'`
## API
```javascript
feed.start(); // Start feed
feed.stop(); // Stop completely
feed.pause(); // Pause (simulation only)
feed.resume(); // Resume after pause
feed.getState(symbol); // Current state for symbol
feed.getCandles(symbol, interval, limit); // Candle history (simulation)
feed.getSymbols(); // All symbol names
feed.getMarketStatus(); // Market open/close status
feed.getSource(); // Active source name
feed.reset(symbol); // Reset symbol (simulation)
feed.resetAll(); // Reset all (simulation)
feed.isRunning(); // true | false
// Register custom connector
registerConnector("myexchange", MyConnectorClass);
// List available sources
getAvailableSources(); // ['simulation', 'binance', ...]
```
## Examples
```bash
node examples/crypto.js # Simulation — crypto
node examples/equity.js # Simulation — US stocks
node examples/forex.js # Simulation — forex pairs
```
## Changelog
### v3.0.0
- Connector architecture — pluggable data sources
- `source` option — `'simulation'` | `'binance'` | custom
- Binance connector — real-time data, no API key needed
- `BaseConnector` — extend to build your own connector
- `registerConnector()` — register custom connectors
- `getAvailableSources()` — list available sources
- `getSource()` — get active source name
- `source` field added to all events
- Fully backward compatible — existing code works unchanged
### v2.0.0
- Complete rewrite — EventEmitter API
- Accurate order book, mean reversion price engine
- Multiple candle intervals, market hours
- Zero dependencies, TypeScript support
## Contributing
We welcome connectors for new exchanges and data sources.
1. Fork the repository
2. Create `src/connectors/yourexchange.js`
3. Extend `BaseConnector`
4. Add tests in `test/`
5. Open a pull request
See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.
## Author
**Love Pareek** — [monupareeklg@gmail.com](mailto:monupareeklg@gmail.com)
GitHub: [monupareeklg](https://github.com/monupareeklg)
Contributor: [Kush Pareek](https://github.com/kushpareek)
## License
MIT — see [LICENSE](./LICENSE)
⭐️ If this saved you time, star it on [GitHub](https://github.com/monupareeklg/trade-data-generator)!