@typedtrader/exchange 0.2.5 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (153) hide show
  1. package/README.md +144 -6
  2. package/dist/broker/Broker.d.ts +152 -0
  3. package/dist/broker/Broker.js +124 -0
  4. package/dist/broker/Broker.js.map +1 -0
  5. package/dist/broker/BrokerMock.d.ts +51 -0
  6. package/dist/broker/BrokerMock.js +333 -0
  7. package/dist/broker/BrokerMock.js.map +1 -0
  8. package/dist/broker/MarketDataSource.d.ts +11 -0
  9. package/dist/broker/MarketDataSource.js +26 -0
  10. package/dist/broker/MarketDataSource.js.map +1 -0
  11. package/dist/broker/TradingPair.d.ts +12 -0
  12. package/dist/broker/TradingPair.js +22 -0
  13. package/dist/broker/TradingPair.js.map +1 -0
  14. package/dist/broker/alpaca/AlpacaBroker.d.ts +49 -0
  15. package/dist/broker/alpaca/AlpacaBroker.js +258 -0
  16. package/dist/broker/alpaca/AlpacaBroker.js.map +1 -0
  17. package/dist/broker/alpaca/AlpacaBrokerMapper.d.ts +12 -0
  18. package/dist/broker/alpaca/AlpacaBrokerMapper.js +96 -0
  19. package/dist/broker/alpaca/AlpacaBrokerMapper.js.map +1 -0
  20. package/dist/broker/alpaca/AlpacaBrokerMock.d.ts +15 -0
  21. package/dist/broker/alpaca/AlpacaBrokerMock.js +29 -0
  22. package/dist/broker/alpaca/AlpacaBrokerMock.js.map +1 -0
  23. package/dist/broker/alpaca/AlpacaMarketData.d.ts +19 -0
  24. package/dist/broker/alpaca/AlpacaMarketData.js +130 -0
  25. package/dist/broker/alpaca/AlpacaMarketData.js.map +1 -0
  26. package/dist/broker/alpaca/AlpacaTradingWebSocket.d.ts +15 -0
  27. package/dist/broker/alpaca/AlpacaTradingWebSocket.js +95 -0
  28. package/dist/broker/alpaca/AlpacaTradingWebSocket.js.map +1 -0
  29. package/dist/broker/alpaca/AlpacaWebSocket.d.ts +14 -0
  30. package/dist/broker/alpaca/AlpacaWebSocket.js +93 -0
  31. package/dist/broker/alpaca/AlpacaWebSocket.js.map +1 -0
  32. package/dist/broker/alpaca/alpacaSymbol.d.ts +4 -0
  33. package/dist/broker/alpaca/alpacaSymbol.js +20 -0
  34. package/dist/broker/alpaca/alpacaSymbol.js.map +1 -0
  35. package/dist/broker/alpaca/api/AlpacaAPI.d.ts +277 -0
  36. package/dist/broker/alpaca/api/AlpacaAPI.js +108 -0
  37. package/dist/broker/alpaca/api/AlpacaAPI.js.map +1 -0
  38. package/dist/broker/alpaca/api/AlpacaStream.d.ts +13 -0
  39. package/dist/broker/alpaca/api/AlpacaStream.js +61 -0
  40. package/dist/broker/alpaca/api/AlpacaStream.js.map +1 -0
  41. package/dist/broker/alpaca/api/AlpacaTradingStream.d.ts +12 -0
  42. package/dist/broker/alpaca/api/AlpacaTradingStream.js +59 -0
  43. package/dist/broker/alpaca/api/AlpacaTradingStream.js.map +1 -0
  44. package/dist/broker/alpaca/api/schema/AccountSchema.d.ts +26 -0
  45. package/dist/broker/alpaca/api/schema/AccountSchema.js +26 -0
  46. package/dist/broker/alpaca/api/schema/AccountSchema.js.map +1 -0
  47. package/dist/broker/alpaca/api/schema/AssetSchema.d.ts +19 -0
  48. package/dist/broker/alpaca/api/schema/AssetSchema.js +19 -0
  49. package/dist/broker/alpaca/api/schema/AssetSchema.js.map +1 -0
  50. package/dist/broker/alpaca/api/schema/BarSchema.d.ts +37 -0
  51. package/dist/broker/alpaca/api/schema/BarSchema.js +19 -0
  52. package/dist/broker/alpaca/api/schema/BarSchema.js.map +1 -0
  53. package/dist/broker/alpaca/api/schema/ClockSchema.d.ts +7 -0
  54. package/dist/broker/alpaca/api/schema/ClockSchema.js +8 -0
  55. package/dist/broker/alpaca/api/schema/ClockSchema.js.map +1 -0
  56. package/dist/broker/alpaca/api/schema/OrderSchema.d.ts +78 -0
  57. package/dist/broker/alpaca/api/schema/OrderSchema.js +73 -0
  58. package/dist/broker/alpaca/api/schema/OrderSchema.js.map +1 -0
  59. package/dist/broker/alpaca/api/schema/PositionSchema.d.ts +31 -0
  60. package/dist/broker/alpaca/api/schema/PositionSchema.js +23 -0
  61. package/dist/broker/alpaca/api/schema/PositionSchema.js.map +1 -0
  62. package/dist/broker/alpaca/api/schema/SnapshotSchema.d.ts +82 -0
  63. package/dist/broker/alpaca/api/schema/SnapshotSchema.js +15 -0
  64. package/dist/broker/alpaca/api/schema/SnapshotSchema.js.map +1 -0
  65. package/dist/broker/alpaca/api/schema/StreamSchema.d.ts +48 -0
  66. package/dist/broker/alpaca/api/schema/StreamSchema.js +32 -0
  67. package/dist/broker/alpaca/api/schema/StreamSchema.js.map +1 -0
  68. package/dist/broker/alpaca/api/schema/TradingStreamSchema.d.ts +61 -0
  69. package/dist/broker/alpaca/api/schema/TradingStreamSchema.js +30 -0
  70. package/dist/broker/alpaca/api/schema/TradingStreamSchema.js.map +1 -0
  71. package/dist/broker/alpaca/getAlpacaClient.d.ts +8 -0
  72. package/dist/broker/alpaca/getAlpacaClient.js +28 -0
  73. package/dist/broker/alpaca/getAlpacaClient.js.map +1 -0
  74. package/dist/broker/alpaca/getAlpacaMarketData.d.ts +2 -0
  75. package/dist/broker/alpaca/getAlpacaMarketData.js +11 -0
  76. package/dist/broker/alpaca/getAlpacaMarketData.js.map +1 -0
  77. package/dist/broker/alpaca/getAlpacaRules.d.ts +11 -0
  78. package/dist/broker/alpaca/getAlpacaRules.js +17 -0
  79. package/dist/broker/alpaca/getAlpacaRules.js.map +1 -0
  80. package/dist/broker/alpaca/index.d.ts +17 -0
  81. package/dist/broker/alpaca/index.js +18 -0
  82. package/dist/broker/alpaca/index.js.map +1 -0
  83. package/dist/broker/getAuthenticatedBrokerClient.d.ts +4 -0
  84. package/dist/broker/getAuthenticatedBrokerClient.js +7 -0
  85. package/dist/broker/getAuthenticatedBrokerClient.js.map +1 -0
  86. package/dist/broker/getBrokerClient.d.ts +10 -0
  87. package/dist/broker/getBrokerClient.js +29 -0
  88. package/dist/broker/getBrokerClient.js.map +1 -0
  89. package/dist/broker/index.d.ts +6 -0
  90. package/dist/broker/index.js +7 -0
  91. package/dist/broker/index.js.map +1 -0
  92. package/dist/broker/trading212/Trading212Broker.d.ts +41 -0
  93. package/dist/broker/trading212/Trading212Broker.js +249 -0
  94. package/dist/broker/trading212/Trading212Broker.js.map +1 -0
  95. package/dist/broker/trading212/Trading212BrokerMapper.d.ts +10 -0
  96. package/dist/broker/trading212/Trading212BrokerMapper.js +84 -0
  97. package/dist/broker/trading212/Trading212BrokerMapper.js.map +1 -0
  98. package/dist/broker/trading212/api/Trading212API.d.ts +202 -0
  99. package/dist/broker/trading212/api/Trading212API.js +143 -0
  100. package/dist/broker/trading212/api/Trading212API.js.map +1 -0
  101. package/dist/broker/trading212/api/schema/AccountSchema.d.ts +16 -0
  102. package/dist/broker/trading212/api/schema/AccountSchema.js +15 -0
  103. package/dist/broker/trading212/api/schema/AccountSchema.js.map +1 -0
  104. package/dist/broker/trading212/api/schema/HistoryOrderSchema.d.ts +136 -0
  105. package/dist/broker/trading212/api/schema/HistoryOrderSchema.js +57 -0
  106. package/dist/broker/trading212/api/schema/HistoryOrderSchema.js.map +1 -0
  107. package/dist/broker/trading212/api/schema/InstrumentSchema.d.ts +37 -0
  108. package/dist/broker/trading212/api/schema/InstrumentSchema.js +26 -0
  109. package/dist/broker/trading212/api/schema/InstrumentSchema.js.map +1 -0
  110. package/dist/broker/trading212/api/schema/OrderSchema.d.ts +97 -0
  111. package/dist/broker/trading212/api/schema/OrderSchema.js +61 -0
  112. package/dist/broker/trading212/api/schema/OrderSchema.js.map +1 -0
  113. package/dist/broker/trading212/api/schema/PositionSchema.d.ts +14 -0
  114. package/dist/broker/trading212/api/schema/PositionSchema.js +14 -0
  115. package/dist/broker/trading212/api/schema/PositionSchema.js.map +1 -0
  116. package/dist/broker/trading212/getTrading212Client.d.ts +8 -0
  117. package/dist/broker/trading212/getTrading212Client.js +5 -0
  118. package/dist/broker/trading212/getTrading212Client.js.map +1 -0
  119. package/dist/broker/trading212/index.d.ts +4 -0
  120. package/dist/broker/trading212/index.js +5 -0
  121. package/dist/broker/trading212/index.js.map +1 -0
  122. package/dist/candle/BatchedCandle.d.ts +24 -0
  123. package/dist/candle/BatchedCandle.js +4 -0
  124. package/dist/candle/BatchedCandle.js.map +1 -0
  125. package/dist/candle/CandleBatcher.d.ts +35 -0
  126. package/dist/candle/CandleBatcher.js +233 -0
  127. package/dist/candle/CandleBatcher.js.map +1 -0
  128. package/dist/candle/index.d.ts +2 -0
  129. package/dist/candle/index.js +3 -0
  130. package/dist/candle/index.js.map +1 -0
  131. package/dist/candle/writeCandles.d.ts +2 -0
  132. package/dist/candle/writeCandles.js +5 -0
  133. package/dist/candle/writeCandles.js.map +1 -0
  134. package/dist/index.d.ts +5 -0
  135. package/dist/index.js +6 -0
  136. package/dist/index.js.map +1 -0
  137. package/dist/util/SimplifiedHttpError.d.ts +11 -0
  138. package/dist/util/SimplifiedHttpError.js +17 -0
  139. package/dist/util/SimplifiedHttpError.js.map +1 -0
  140. package/dist/util/index.d.ts +1 -0
  141. package/dist/util/index.js +2 -0
  142. package/dist/util/index.js.map +1 -0
  143. package/dist/util/isEarningsDay.d.ts +15 -0
  144. package/dist/util/isEarningsDay.js +39 -0
  145. package/dist/util/isEarningsDay.js.map +1 -0
  146. package/dist/util/simplifyError.d.ts +2 -0
  147. package/dist/util/simplifyError.js +16 -0
  148. package/dist/util/simplifyError.js.map +1 -0
  149. package/package.json +45 -43
  150. package/dist/index.cjs +0 -966
  151. package/dist/index.d.cts +0 -361
  152. package/dist/index.d.mts +0 -361
  153. package/dist/index.mjs +0 -919
package/README.md CHANGED
@@ -1,11 +1,149 @@
1
1
  # @typedtrader/exchange
2
2
 
3
- Utilities for handling trading exchange data with proper type safety and aggregation.
3
+ Typed broker clients for algorithmic trading in TypeScript. Trade through brokers like [Alpaca](https://alpaca.markets/) and [Trading212](https://www.trading212.com/) with one consistent API: every response validated at runtime (zod), all money math in arbitrary precision (big.js), live candles streamed over WebSocket.
4
+
5
+ ### [Install](#installation) · [Brokers](#supported-brokers) · [Quick Start](#quick-start-alpaca) · [Raw API](#raw-api-access) · [Rate Limits](#rate-limiting) · [Extend](#bring-your-own-broker)
6
+
7
+ ## Motivation
8
+
9
+ This package provides a unified trading API for traditional brokers like Alpaca and Trading212. Write your strategy against one typed `Broker` contract and it runs on any supported broker, the way [CCXT](https://github.com/ccxt/ccxt) does it for crypto exchanges.
10
+
11
+ It also covers more of trading than the basic paths most broker APIs wrap: long and short positions, market and limit orders, fills, fee estimation, and trading rules.
12
+
13
+ ## Installation
14
+
15
+ ```sh
16
+ npm install @typedtrader/exchange
17
+ ```
18
+
19
+ The package is ESM-only and targets the latest Node.js LTS.
4
20
 
5
21
  ## Features
6
22
 
7
- - **Candle Batching:** Aggregates multiple exchange candles into larger timeframes
8
- - **Type Safety:** Zod schemas for runtime validation of exchange data
9
- - **High Precision:** Uses `big.js` for arbitrary-precision decimal arithmetic
10
- - **Event-Driven:** Built-in EventEmitter for streaming candle updates
11
- - **Flexible Intervals:** Timeframes using human-readable strings (e.g., "1h", "5m")
23
+ - **One API for every broker:** place market/limit orders, list balances, watch fills and candles with the same methods on every supported broker
24
+ - **Paper trading:** a single `usePaperTrading` flag switches a broker to its sandbox environment
25
+ - **Runtime validation:** every API response is parsed with zod schemas, so malformed data fails loudly instead of corrupting your strategy
26
+ - **High precision:** `big.js` for order sizes, prices, and fees, with no floating-point drift
27
+ - **Streaming candles:** WebSocket-fed minute bars, batched into larger timeframes using human-readable intervals (e.g. `"5m"`, `"1h"`)
28
+ - **Fee awareness:** `getFeeRates()` / `estimateFee()` let strategies subtract round-trip costs before entering a position
29
+
30
+ ## Supported Brokers
31
+
32
+ | id | name | markets | paper trading | market data | order updates | API docs |
33
+ | --- | --- | --- | :-: | --- | --- | --- |
34
+ | `alpaca` | [Alpaca](https://alpaca.markets/) | US stocks, ETFs, crypto | ✅ | ✅ IEX feed, WebSocket streamed | ✅ WebSocket stream | [docs.alpaca.markets](https://docs.alpaca.markets/reference/) |
35
+ | `trading212` | [Trading212](https://www.trading212.com/) | 13,000+ US/UK/EU stocks and ETFs | ✅ | ❌ bring your own source | 🔁 polled (~60s) | [docs.trading212.com](https://docs.trading212.com/api) |
36
+
37
+ More brokers are planned, and the `Broker` abstraction is built for it (see [Bring Your Own Broker](#bring-your-own-broker)).
38
+
39
+ You create the API keys yourself in each broker's dashboard. The package uses your credentials but never creates accounts or keys for you: [Alpaca API keys](https://docs.alpaca.markets/us/docs/getting-started) · [Trading212 API keys](https://helpcentre.trading212.com/hc/en-us/articles/14584770928157-Trading-212-API-key)
40
+
41
+ ## Quick Start: Alpaca
42
+
43
+ ```ts
44
+ import {getAlpacaClient, TradingPair} from '@typedtrader/exchange';
45
+
46
+ const broker = getAlpacaClient({
47
+ apiKey: 'ALPACA_API_KEY',
48
+ apiSecret: 'ALPACA_API_SECRET',
49
+ usePaperTrading: true,
50
+ });
51
+
52
+ await broker.verifyCredentials();
53
+
54
+ const pair = new TradingPair('AAPL', 'USD');
55
+ const latest = await broker.getLatestCandle(pair, 60_000);
56
+ await broker.placeLimitOrder(pair, {side: 'BUY', size: '1', price: latest.close});
57
+ ```
58
+
59
+ **Why Alpaca:**
60
+
61
+ - **Commission-free** US stocks and ETFs, with fractional shares.
62
+ - **Free paper trading** that mirrors the live API, so strategies can be validated without risking capital.
63
+ - **Free market data** via the IEX feed, including WebSocket-streamed minute bars (the source this package pairs with other brokers).
64
+ - **Crypto** trades 24/7 alongside equities.
65
+ - **[24/5 trading](https://docs.alpaca.markets/us/docs/245-trading)** of US stocks via an overnight session, so positions can be opened or closed from Sunday evening through Friday evening.
66
+ - **Add funds commission-free** with [Revolut](https://www.revolut.com/), avoiding the transfer fees most banks charge.
67
+
68
+ **Resources:** [API Reference](https://docs.alpaca.markets/reference/) · [OpenAPI Files](https://docs.alpaca.markets/openapi) · [24/5 Trading](https://docs.alpaca.markets/us/docs/245-trading)
69
+
70
+ ## Quick Start: Trading212
71
+
72
+ Trading212's API has no historical bars and no WebSocket, so the broker is paired with an external market-data source. For US equities, Alpaca's feed is the natural choice: it is free, works with a paper account, and streams minute bars over WebSocket.
73
+
74
+ ```ts
75
+ import {AlpacaMarketData, getTrading212Client, TradingPair} from '@typedtrader/exchange';
76
+
77
+ // 1. Construct an Alpaca-backed market-data source.
78
+ const marketData = new AlpacaMarketData({
79
+ apiKey: 'ALPACA_API_KEY',
80
+ apiSecret: 'ALPACA_API_SECRET',
81
+ usePaperTrading: false, // read-only; doesn't place orders
82
+ });
83
+
84
+ // 2. Wire it into the Trading212 broker.
85
+ const broker = getTrading212Client({
86
+ apiKey: 'TRADING212_API_KEY',
87
+ apiSecret: 'TRADING212_API_SECRET',
88
+ usePaperTrading: true,
89
+ marketData, // required: Trading212 has no candles of its own
90
+ });
91
+
92
+ // 3. Use the broker as if it provided everything natively. Symbol mapping is automatic:
93
+ // Trading212's `AAPL_US_EQ` is stripped to Alpaca's `AAPL` behind the scenes.
94
+ const pair = new TradingPair('AAPL_US_EQ', 'USD');
95
+ const latest = await broker.getLatestCandle(pair, 60_000); // → from Alpaca's WebSocket
96
+ await broker.placeLimitOrder(pair, {side: 'BUY', size: '1', price: latest.close}); // → Trading212
97
+ ```
98
+
99
+ **Why Trading212:**
100
+
101
+ - **Commission-free** investing in 13,000+ stocks and ETFs, with fractional shares from £1/€1.
102
+ - **Broad UK, European, and US coverage.**
103
+ - **Multi-currency accounts** for depositing and investing in 13 currencies.
104
+ - **Tax-advantaged Stocks & Shares ISA** (and Cash ISA) for UK residents, with no account fees.
105
+ - **Daily [interest](https://www.trading212.com/interest-on-cash)** paid on uninvested cash.
106
+
107
+ **Good to know:**
108
+
109
+ - **Cross-currency fees.** Trading212 debits a currency-conversion fee on cross-currency trades (e.g. a EUR account buying USD instruments) at ~0.15% per leg. `getFeeRates()` surfaces this as `CURRENCY_CONVERSION_FEE`; `estimateFee()` includes it in the total.
110
+ - **Order updates are polled.** Trading212 has no order-stream WebSocket, so `watchOrders` polls once per minute (matching Trading212's documented rate limit). Fills arrive within ~60 seconds rather than push-style.
111
+
112
+ **Resources:** [API Documentation](https://docs.trading212.com/api) · [Fees](https://helpcentre.trading212.com/hc/en-us/articles/11471996799517)
113
+
114
+ ## Raw API Access
115
+
116
+ The low-level REST clients are exported too, for direct calls without the broker abstraction. They keep the zod-validated responses and rate-limit-aware retries:
117
+
118
+ ```ts
119
+ import {Trading212API} from '@typedtrader/exchange';
120
+
121
+ const api = new Trading212API({
122
+ apiKey: 'TRADING212_API_KEY',
123
+ apiSecret: 'TRADING212_API_SECRET',
124
+ usePaperTrading: true,
125
+ });
126
+
127
+ const cash = await api.getAccountCash();
128
+ const positions = await api.getPositions();
129
+ const orders = await api.getHistoryOrders(); // auto-paginates
130
+ ```
131
+
132
+ Every broker integration exports its raw client the same way (`AlpacaAPI`, `Trading212API`, ...).
133
+
134
+ ## Rate Limiting
135
+
136
+ Brokers enforce rate limits. The package respects them automatically:
137
+
138
+ - **Automatic retries with broker-aware delays.** Every client uses `axios-retry`, with retry delays calibrated per endpoint to the broker's documented limits (e.g. Trading212 account cash: 1 req / 2s, order history: 1 req / 60s), so a rate-limited request waits exactly as long as it must.
139
+ - **Polling matches documented limits.** Where the package polls (Trading212's `watchOrders`), the interval defaults to the broker's documented rate limit rather than hammering the API.
140
+ - **Transient network errors** (`EAI_AGAIN`, HTTP 429/5xx) are retried transparently; non-retryable errors (401, 403, validation failures) surface immediately.
141
+
142
+ ## Bring Your Own Broker
143
+
144
+ The built-in integrations are first-class, but any broker can be added:
145
+
146
+ - **Extend the abstract `Broker` class** and your integration plugs straight into the `trading-strategies` package's `TradingSession` (live trading) and `BacktestExecutor` (backtesting) with no extra wiring.
147
+ - **Extend `MarketDataSource`** to stream candles from your own data provider. Execution and market data are deliberately separated, so any data source can be paired with any broker.
148
+
149
+ See [`BROKER_TEMPLATE.md`](https://github.com/bennycode/trading-signals/blob/main/packages/exchange/BROKER_TEMPLATE.md) for the conventions every integration follows.
@@ -0,0 +1,152 @@
1
+ import Big from 'big.js';
2
+ import { EventEmitter } from 'node:events';
3
+ import type { TradingPair } from './TradingPair.js';
4
+ import { z } from 'zod';
5
+ export declare const OrderSide: {
6
+ readonly BUY: 'BUY';
7
+ readonly SELL: 'SELL';
8
+ };
9
+ export type OrderSide = (typeof OrderSide)[keyof typeof OrderSide];
10
+ interface OrderBase {
11
+ side: OrderSide;
12
+ size: string;
13
+ type: OrderType;
14
+ }
15
+ export declare const CandleBaseSchema: z.ZodObject<{
16
+ base: z.ZodString;
17
+ counter: z.ZodString;
18
+ isLatest: z.ZodOptional<z.ZodBoolean>;
19
+ openTimeInISO: z.ZodString;
20
+ openTimeInMillis: z.ZodNumber;
21
+ sizeInMillis: z.ZodNumber;
22
+ }, z.core.$strip>;
23
+ export type CandleBase = z.infer<typeof CandleBaseSchema>;
24
+ export declare const OrderType: {
25
+ readonly LIMIT: 'LIMIT';
26
+ readonly MARKET: 'MARKET';
27
+ };
28
+ export type OrderType = (typeof OrderType)[keyof typeof OrderType];
29
+ export declare const CandleSchema: z.ZodObject<{
30
+ base: z.ZodString;
31
+ counter: z.ZodString;
32
+ isLatest: z.ZodOptional<z.ZodBoolean>;
33
+ openTimeInISO: z.ZodString;
34
+ openTimeInMillis: z.ZodNumber;
35
+ sizeInMillis: z.ZodNumber;
36
+ close: z.ZodString;
37
+ closeAsk: z.ZodOptional<z.ZodString>;
38
+ high: z.ZodString;
39
+ highAsk: z.ZodOptional<z.ZodString>;
40
+ low: z.ZodString;
41
+ lowAsk: z.ZodOptional<z.ZodString>;
42
+ open: z.ZodString;
43
+ openAsk: z.ZodOptional<z.ZodString>;
44
+ volume: z.ZodString;
45
+ }, z.core.$strip>;
46
+ export type Candle = z.infer<typeof CandleSchema>;
47
+ export interface CandleImportRequest {
48
+ intervalInMillis: number;
49
+ startTimeFirstCandle: string;
50
+ startTimeLastCandle: string;
51
+ }
52
+ export interface FeeRate {
53
+ LIMIT: Big;
54
+ MARKET: Big;
55
+ CURRENCY_CONVERSION_FEE?: Big;
56
+ }
57
+ export declare const OrderPosition: {
58
+ readonly LONG: 'LONG';
59
+ readonly SHORT: 'SHORT';
60
+ };
61
+ export type OrderPosition = (typeof OrderPosition)[keyof typeof OrderPosition];
62
+ export interface Fill {
63
+ created_at: string;
64
+ fee: string;
65
+ feeAsset: string;
66
+ order_id: string;
67
+ pair: TradingPair;
68
+ position: OrderPosition;
69
+ price: string;
70
+ side: OrderSide;
71
+ size: string;
72
+ }
73
+ export interface ExchangePendingOrderBase {
74
+ id: string;
75
+ pair: TradingPair;
76
+ side: OrderSide;
77
+ size: string;
78
+ type: OrderType;
79
+ }
80
+ export interface PendingLimitOrder extends ExchangePendingOrderBase {
81
+ price: string;
82
+ type: 'LIMIT';
83
+ }
84
+ export interface PendingMarketOrder extends ExchangePendingOrderBase {
85
+ type: 'MARKET';
86
+ sizeInCounter?: boolean;
87
+ }
88
+ export interface MarketOrderOptions extends OrderBase {
89
+ sizeInCounter: boolean;
90
+ type: 'MARKET';
91
+ }
92
+ export interface LimitOrderOptions extends OrderBase {
93
+ price: string;
94
+ sizeInCounter: false;
95
+ type: 'LIMIT';
96
+ }
97
+ export type OrderOptions = MarketOrderOptions | LimitOrderOptions;
98
+ export type PendingOrder = PendingLimitOrder | PendingMarketOrder;
99
+ export interface Balance {
100
+ available: string;
101
+ currency: string;
102
+ hold: string;
103
+ position: OrderPosition;
104
+ }
105
+ export interface ExchangeAvailableBalance {
106
+ base: Big;
107
+ counter: Big;
108
+ }
109
+ export interface TradingRules {
110
+ base_increment: string;
111
+ base_max_size: string;
112
+ base_min_size: string;
113
+ counter_increment: string;
114
+ counter_min_size: string;
115
+ pair: TradingPair;
116
+ }
117
+ export declare abstract class Broker extends EventEmitter {
118
+ loggerName: string;
119
+ constructor(loggerName: string);
120
+ static toExchangeOrderSide(baseBalance: Big.BigSource, counterBalance: Big.BigSource, priceInCounter: Big.BigSource): OrderSide;
121
+ abstract listBalances(): Promise<Balance[]>;
122
+ abstract cancelOpenOrders(pair: TradingPair): Promise<string[]>;
123
+ abstract cancelOrderById(pair: TradingPair, orderId: string): Promise<void>;
124
+ abstract getOpenOrders(pair: TradingPair): Promise<PendingOrder[]>;
125
+ getLatestFill(pair: TradingPair, side: OrderSide): Promise<Fill | undefined>;
126
+ abstract getFills(pair: TradingPair): Promise<Fill[]>;
127
+ abstract getFillByOrderId(pair: TradingPair, orderId: string): Promise<Fill | undefined>;
128
+ abstract watchOrders(): Promise<string>;
129
+ abstract unwatchOrders(topicId: string): void;
130
+ abstract getTradingRules(pair: TradingPair): Promise<TradingRules>;
131
+ abstract getFeeRates(pair: TradingPair): Promise<FeeRate>;
132
+ getFeeRate(pair: TradingPair, orderType: OrderType): Promise<Big>;
133
+ estimateFee(pair: TradingPair, orderType: OrderType, notional: Big): Promise<{
134
+ commission: Big;
135
+ currencyConversion: Big;
136
+ total: Big;
137
+ feeAsset: string;
138
+ }>;
139
+ protected getFeeAsset(pair: TradingPair): Promise<string>;
140
+ getAvailableBalances(pair: TradingPair): Promise<ExchangeAvailableBalance>;
141
+ abstract getTime(): Promise<string>;
142
+ verifyCredentials(): Promise<void>;
143
+ protected abstract placeOrder(pair: TradingPair, options: LimitOrderOptions): Promise<PendingLimitOrder>;
144
+ protected abstract placeOrder(pair: TradingPair, options: MarketOrderOptions): Promise<PendingMarketOrder>;
145
+ protected abstract placeOrder(pair: TradingPair, options: OrderOptions): Promise<PendingOrder>;
146
+ placeLimitOrder(pair: TradingPair, options: Omit<LimitOrderOptions, 'type' | 'sizeInCounter'>): Promise<PendingLimitOrder>;
147
+ placeMarketOrder(pair: TradingPair, options: Omit<MarketOrderOptions, 'type'>): Promise<PendingMarketOrder>;
148
+ abstract disconnect(): void;
149
+ abstract getName(): string;
150
+ abstract getSmallestInterval(): number;
151
+ }
152
+ export {};
@@ -0,0 +1,124 @@
1
+ import Big from 'big.js';
2
+ import { EventEmitter } from 'node:events';
3
+ import { z } from 'zod';
4
+ export const OrderSide = {
5
+ BUY: 'BUY',
6
+ SELL: 'SELL',
7
+ };
8
+ export const CandleBaseSchema = z.object({
9
+ base: z.string(),
10
+ counter: z.string(),
11
+ isLatest: z.boolean().optional(),
12
+ openTimeInISO: z.string(),
13
+ openTimeInMillis: z.number(),
14
+ sizeInMillis: z.number(),
15
+ });
16
+ export const OrderType = {
17
+ LIMIT: 'LIMIT',
18
+ MARKET: 'MARKET',
19
+ };
20
+ export const CandleSchema = z
21
+ .object({
22
+ close: z.string(),
23
+ closeAsk: z.string().optional(),
24
+ high: z.string(),
25
+ highAsk: z.string().optional(),
26
+ low: z.string(),
27
+ lowAsk: z.string().optional(),
28
+ open: z.string(),
29
+ openAsk: z.string().optional(),
30
+ volume: z.string(),
31
+ })
32
+ .merge(CandleBaseSchema);
33
+ export const OrderPosition = {
34
+ LONG: 'LONG',
35
+ SHORT: 'SHORT',
36
+ };
37
+ export class Broker extends EventEmitter {
38
+ loggerName;
39
+ constructor(loggerName) {
40
+ super();
41
+ this.loggerName = loggerName;
42
+ }
43
+ static toExchangeOrderSide(baseBalance, counterBalance, priceInCounter) {
44
+ const currentBaseWorthInCounter = new Big(baseBalance).mul(priceInCounter);
45
+ const currentCounterWorthInCounter = new Big(counterBalance);
46
+ if (currentBaseWorthInCounter.gt(currentCounterWorthInCounter)) {
47
+ return OrderSide.BUY;
48
+ }
49
+ return OrderSide.SELL;
50
+ }
51
+ async getLatestFill(pair, side) {
52
+ const fills = await this.getFills(pair);
53
+ const fill = fills.find(fill => fill.side === side);
54
+ if (fill) {
55
+ return fill;
56
+ }
57
+ return undefined;
58
+ }
59
+ async getFeeRate(pair, orderType) {
60
+ const feeRate = await this.getFeeRates(pair);
61
+ return feeRate[orderType];
62
+ }
63
+ async estimateFee(pair, orderType, notional) {
64
+ const rates = await this.getFeeRates(pair);
65
+ const commission = notional.times(rates[orderType]);
66
+ const conversionRate = rates.CURRENCY_CONVERSION_FEE;
67
+ const currencyConversion = conversionRate ? notional.times(conversionRate) : new Big(0);
68
+ return {
69
+ commission,
70
+ currencyConversion,
71
+ feeAsset: await this.getFeeAsset(pair),
72
+ total: commission.plus(currencyConversion),
73
+ };
74
+ }
75
+ async getFeeAsset(pair) {
76
+ return pair.counter;
77
+ }
78
+ async getAvailableBalances(pair) {
79
+ const balances = await this.listBalances();
80
+ let baseBalance = balances.find(balance => balance.currency === pair.base);
81
+ let counterBalance = balances.find(balance => balance.currency === pair.counter);
82
+ if (!baseBalance) {
83
+ baseBalance = {
84
+ available: '0',
85
+ currency: pair.base,
86
+ hold: '0',
87
+ position: OrderPosition.LONG,
88
+ };
89
+ }
90
+ if (!counterBalance) {
91
+ counterBalance = {
92
+ available: '0',
93
+ currency: pair.counter,
94
+ hold: '0',
95
+ position: OrderPosition.LONG,
96
+ };
97
+ }
98
+ return {
99
+ base: new Big(baseBalance.available),
100
+ counter: new Big(counterBalance.available),
101
+ };
102
+ }
103
+ async verifyCredentials() {
104
+ await this.getTime();
105
+ }
106
+ placeLimitOrder(pair, options) {
107
+ return this.placeOrder(pair, {
108
+ price: options.price,
109
+ side: options.side,
110
+ size: options.size,
111
+ sizeInCounter: false,
112
+ type: OrderType.LIMIT,
113
+ });
114
+ }
115
+ placeMarketOrder(pair, options) {
116
+ return this.placeOrder(pair, {
117
+ side: options.side,
118
+ size: options.size,
119
+ sizeInCounter: options.sizeInCounter,
120
+ type: OrderType.MARKET,
121
+ });
122
+ }
123
+ }
124
+ //# sourceMappingURL=Broker.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Broker.js","sourceRoot":"","sources":["../../src/broker/Broker.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,51 @@
1
+ import Big from 'big.js';
2
+ import { Broker, type Balance, type Candle, type FeeRate, type Fill, type LimitOrderOptions, type MarketOrderOptions, type PendingLimitOrder, type PendingMarketOrder, type PendingOrder, type TradingRules } from './Broker.js';
3
+ import type { TradingPair } from './TradingPair.js';
4
+ export interface ExchangeMockBalance {
5
+ available: Big;
6
+ hold: Big;
7
+ }
8
+ export declare abstract class BrokerMock extends Broker {
9
+ #private;
10
+ constructor(config: {
11
+ balances: Map<string, ExchangeMockBalance>;
12
+ });
13
+ setHistoricalCandles(candles: Candle[]): void;
14
+ getRecentCandles(_pair: TradingPair, count: number, _intervalInMillis: number): Promise<Candle[]>;
15
+ abstract getFeeRates(pair: TradingPair): Promise<FeeRate>;
16
+ abstract getTradingRules(pair: TradingPair): Promise<TradingRules>;
17
+ abstract getName(): string;
18
+ abstract getSmallestInterval(): number;
19
+ processCandle(candle: Candle): Fill[];
20
+ protected placeOrder(pair: TradingPair, options: LimitOrderOptions): Promise<PendingLimitOrder>;
21
+ protected placeOrder(pair: TradingPair, options: MarketOrderOptions): Promise<PendingMarketOrder>;
22
+ setCachedFeeRates(rates: FeeRate): void;
23
+ listBalances(): Promise<Balance[]>;
24
+ getFills(pair: TradingPair): Promise<Fill[]>;
25
+ getFillByOrderId(_pair: TradingPair, orderId: string): Promise<Fill | undefined>;
26
+ cancelOrderById(_pair: TradingPair, orderId: string): Promise<void>;
27
+ cancelOpenOrders(pair: TradingPair): Promise<string[]>;
28
+ getLatestCandle(_pair: TradingPair, _intervalInMillis: number): Promise<{
29
+ base: string;
30
+ counter: string;
31
+ isLatest?: boolean | undefined;
32
+ openTimeInISO: string;
33
+ openTimeInMillis: number;
34
+ sizeInMillis: number;
35
+ close: string;
36
+ closeAsk?: string | undefined;
37
+ high: string;
38
+ highAsk?: string | undefined;
39
+ low: string;
40
+ lowAsk?: string | undefined;
41
+ open: string;
42
+ openAsk?: string | undefined;
43
+ volume: string;
44
+ }>;
45
+ getTime(): Promise<string>;
46
+ getOpenOrders(pair: TradingPair): Promise<PendingOrder[]>;
47
+ watchOrders(): Promise<`${string}-${string}-${string}-${string}-${string}`>;
48
+ unwatchOrders(topicId: string): void;
49
+ disconnect(): void;
50
+ getPendingOrders(): PendingOrder[];
51
+ }