valr-typescript-client 1.0.0

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.
@@ -0,0 +1,3256 @@
1
+ import { AxiosRequestConfig, AxiosResponse, AxiosInstance } from 'axios';
2
+ import WebSocket from 'ws';
3
+ import EventEmitter from 'eventemitter3';
4
+
5
+ /**
6
+ * HTTP client configuration
7
+ */
8
+ interface HttpClientConfig {
9
+ baseURL?: string;
10
+ timeout?: number;
11
+ headers?: Record<string, string>;
12
+ }
13
+ /**
14
+ * HTTP client wrapper for VALR API
15
+ */
16
+ declare class HttpClient {
17
+ private axiosInstance;
18
+ constructor(config?: HttpClientConfig);
19
+ /**
20
+ * Perform GET request
21
+ */
22
+ get<T = any>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
23
+ /**
24
+ * Perform POST request
25
+ */
26
+ post<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
27
+ /**
28
+ * Perform PUT request
29
+ */
30
+ put<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
31
+ /**
32
+ * Perform PATCH request
33
+ */
34
+ patch<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
35
+ /**
36
+ * Perform DELETE request
37
+ */
38
+ delete<T = any>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
39
+ /**
40
+ * Set default header
41
+ */
42
+ setHeader(key: string, value: string): void;
43
+ /**
44
+ * Remove default header
45
+ */
46
+ removeHeader(key: string): void;
47
+ /**
48
+ * Get the underlying Axios instance
49
+ */
50
+ getInstance(): AxiosInstance;
51
+ }
52
+
53
+ /**
54
+ * Common types used across VALR API
55
+ */
56
+ /**
57
+ * Order side (buy or sell)
58
+ */
59
+ type OrderSide = 'BUY' | 'SELL';
60
+ /**
61
+ * Order type
62
+ */
63
+ type OrderType = 'MARKET' | 'LIMIT' | 'STOP_LOSS_LIMIT' | 'TAKE_PROFIT_LIMIT';
64
+ /**
65
+ * Time in force for orders
66
+ */
67
+ type TimeInForce = 'GTC' | 'IOC' | 'FOK';
68
+ /**
69
+ * Order status
70
+ */
71
+ type OrderStatus = 'PLACED' | 'PARTIALLY_FILLED' | 'FILLED' | 'CANCELLED' | 'FAILED' | 'PENDING';
72
+ /**
73
+ * Post-only order behavior
74
+ */
75
+ type PostOnly = 'POST_ONLY_REPRICE' | 'POST_ONLY_REJECT' | 'NOT_POST_ONLY';
76
+ /**
77
+ * Transaction type
78
+ */
79
+ type TransactionType = 'LIMIT_BUY' | 'LIMIT_SELL' | 'MARKET_BUY' | 'MARKET_SELL' | 'SIMPLE_BUY' | 'SIMPLE_SELL' | 'DEPOSIT' | 'WITHDRAWAL' | 'BLOCKCHAIN_RECEIVE' | 'BLOCKCHAIN_SEND' | 'FIAT_DEPOSIT' | 'FIAT_WITHDRAWAL' | 'REFERRAL_REBATE' | 'REFERRAL_REWARD' | 'PROMOTIONAL_REBATE' | 'INTERNAL_TRANSFER' | 'STAKING_REWARD' | 'INTEREST_PAYMENT';
80
+ /**
81
+ * Currency code (e.g., BTC, ETH, ZAR, USDC)
82
+ */
83
+ type CurrencyCode = string;
84
+ /**
85
+ * Currency pair (e.g., BTCZAR, ETHUSDC)
86
+ */
87
+ type CurrencyPair = string;
88
+ /**
89
+ * Network type for crypto deposits/withdrawals
90
+ */
91
+ type NetworkType = string;
92
+ /**
93
+ * Cryptocurrency address
94
+ */
95
+ type CryptoAddress = string;
96
+ /**
97
+ * Currency pair type
98
+ */
99
+ type PairType = 'SPOT' | 'FUTURES';
100
+ /**
101
+ * Pagination parameters
102
+ */
103
+ interface PaginationParams {
104
+ /** Number of records to skip */
105
+ skip?: number;
106
+ /** Maximum number of records to return */
107
+ limit?: number;
108
+ }
109
+ /**
110
+ * Pagination parameters with beforeId
111
+ */
112
+ interface CursorPaginationParams {
113
+ /** ID to paginate before */
114
+ beforeId?: string;
115
+ /** Maximum number of records to return */
116
+ limit?: number;
117
+ }
118
+ /**
119
+ * Time range filter
120
+ */
121
+ interface TimeRangeParams {
122
+ /** Start time (ISO 8601 format) */
123
+ startTime?: string;
124
+ /** End time (ISO 8601 format) */
125
+ endTime?: string;
126
+ }
127
+ /**
128
+ * Price and quantity
129
+ */
130
+ interface PriceQuantity {
131
+ /** Price per unit */
132
+ price: string;
133
+ /** Quantity */
134
+ quantity: string;
135
+ }
136
+ /**
137
+ * Order book entry
138
+ */
139
+ interface OrderBookEntry$1 {
140
+ /** Order side */
141
+ side: OrderSide;
142
+ /** Quantity */
143
+ quantity: string;
144
+ /** Price */
145
+ price: string;
146
+ /** Currency pair */
147
+ currencyPair: CurrencyPair;
148
+ /** Number of orders at this price level */
149
+ orderCount: number;
150
+ }
151
+ /**
152
+ * Customer order ID (optional unique identifier provided by customer)
153
+ */
154
+ type CustomerOrderId = string;
155
+ /**
156
+ * Internal order ID (generated by VALR)
157
+ */
158
+ type OrderId = string;
159
+ /**
160
+ * Subaccount ID
161
+ */
162
+ type SubaccountId = string;
163
+ /**
164
+ * ISO 8601 timestamp string
165
+ */
166
+ type ISOTimestamp = string;
167
+ /**
168
+ * Conditional order trigger type
169
+ */
170
+ type ConditionalOrderTriggerType = 'MARK_PRICE' | 'LAST_TRADED_PRICE';
171
+ /**
172
+ * Stop loss or take profit order type
173
+ */
174
+ type ConditionalOrderType = 'STOP_LOSS' | 'TAKE_PROFIT';
175
+ /**
176
+ * Batch order status
177
+ */
178
+ type BatchOrderStatus = 'ACCEPTED' | 'FAILED';
179
+
180
+ /**
181
+ * Server time response
182
+ */
183
+ interface ServerTime {
184
+ /** Unix epoch time in seconds */
185
+ epochTime: number;
186
+ /** ISO 8601 timestamp */
187
+ time: ISOTimestamp;
188
+ }
189
+ /**
190
+ * VALR API status
191
+ */
192
+ interface ValrStatus {
193
+ /** Current status of the API */
194
+ status: 'online' | 'offline' | 'maintenance';
195
+ }
196
+ /**
197
+ * Currency information
198
+ */
199
+ interface Currency {
200
+ /** Currency symbol (e.g., BTC, ETH, ZAR) */
201
+ symbol: CurrencyCode;
202
+ /** Whether the currency is currently active */
203
+ isActive: boolean;
204
+ /** Short name for display */
205
+ shortName: string;
206
+ /** Full name of the currency */
207
+ longName: string;
208
+ /** Number of decimal places */
209
+ decimalPlaces: string;
210
+ /** Decimal places for withdrawals */
211
+ withdrawalDecimalPlaces: string;
212
+ /** Whether currency can be used as collateral */
213
+ collateral: boolean;
214
+ /** Collateral discount */
215
+ collateralDiscount?: string;
216
+ /** Supported network types for this currency */
217
+ supportedNetworkTypes?: string[];
218
+ /** Default network type */
219
+ defaultNetworkType?: string;
220
+ /** Whether currency supports deposits */
221
+ supportDeposit?: boolean;
222
+ /** Whether currency supports withdrawals */
223
+ supportWithdrawal?: boolean;
224
+ /** Minimum deposit amount */
225
+ minDeposit?: string;
226
+ /** Minimum withdrawal amount */
227
+ minWithdrawal?: string;
228
+ /** Withdrawal fee */
229
+ withdrawalFee?: string;
230
+ }
231
+ /**
232
+ * Currency pair information
233
+ */
234
+ interface CurrencyPairInfo {
235
+ /** Currency pair symbol (e.g., BTCZAR, ETHUSDC) */
236
+ symbol: CurrencyPair;
237
+ /** Base currency */
238
+ baseCurrency: CurrencyCode;
239
+ /** Quote currency */
240
+ quoteCurrency: CurrencyCode;
241
+ /** Short name for display */
242
+ shortName: string;
243
+ /** Whether the pair is active */
244
+ active: boolean;
245
+ /** Minimum base amount for orders */
246
+ minBaseAmount: string;
247
+ /** Maximum base amount for orders */
248
+ maxBaseAmount: string;
249
+ /** Minimum quote amount for orders */
250
+ minQuoteAmount: string;
251
+ /** Maximum quote amount for orders */
252
+ maxQuoteAmount: string;
253
+ /** Number of decimal places for price */
254
+ tickSize: string;
255
+ /** Minimum increment for base amount */
256
+ baseDecimalPlaces: string;
257
+ /** Quote currency decimal places */
258
+ quoteDecimalPlaces?: string;
259
+ }
260
+ /**
261
+ * Market summary for a currency pair
262
+ */
263
+ interface MarketSummary {
264
+ /** Currency pair */
265
+ currencyPair: CurrencyPair;
266
+ /** Current ask (sell) price */
267
+ askPrice: string;
268
+ /** Current bid (buy) price */
269
+ bidPrice: string;
270
+ /** Last traded price */
271
+ lastTradedPrice: string;
272
+ /** Previous 24h close price */
273
+ previousClosePrice: string;
274
+ /** 24h base volume */
275
+ baseVolume: string;
276
+ /** 24h quote volume */
277
+ quoteVolume: string;
278
+ /** 24h high price */
279
+ highPrice: string;
280
+ /** 24h low price */
281
+ lowPrice: string;
282
+ /** Timestamp of this summary */
283
+ created: ISOTimestamp;
284
+ /** 24h price change percentage */
285
+ changeFromPrevious?: string;
286
+ /** Mark price (for futures) */
287
+ markPrice?: string;
288
+ }
289
+ /**
290
+ * Order book entry
291
+ */
292
+ interface OrderBookEntry {
293
+ /** Order side */
294
+ side: OrderSide | 'buy' | 'sell';
295
+ /** Quantity available at this price */
296
+ quantity: string;
297
+ /** Price level */
298
+ price: string;
299
+ /** Currency pair */
300
+ currencyPair: CurrencyPair;
301
+ /** Number of orders at this price level */
302
+ orderCount: number;
303
+ /** Position (for full order book) */
304
+ positionAtCrossOver?: number;
305
+ /** ID (for full order book) */
306
+ id?: string;
307
+ }
308
+ /**
309
+ * Aggregated order book
310
+ */
311
+ interface OrderBook {
312
+ /** Ask orders (sell side) */
313
+ Asks: OrderBookEntry[];
314
+ /** Bid orders (buy side) */
315
+ Bids: OrderBookEntry[];
316
+ /** Last change sequence number */
317
+ LastChange?: string;
318
+ /** Checksum for validation */
319
+ Checksum?: number;
320
+ }
321
+ /**
322
+ * Trade history entry
323
+ */
324
+ interface Trade {
325
+ /** Trade price */
326
+ price: string;
327
+ /** Trade quantity */
328
+ quantity: string;
329
+ /** Currency pair */
330
+ currencyPair: CurrencyPair;
331
+ /** When the trade occurred */
332
+ tradedAt: ISOTimestamp;
333
+ /** Taker side of the trade */
334
+ takerSide: OrderSide | 'buy' | 'sell';
335
+ /** Sequence ID for ordering */
336
+ sequenceId: number;
337
+ /** Trade ID */
338
+ id: string;
339
+ /** Quote volume */
340
+ quoteVolume?: string;
341
+ }
342
+ /**
343
+ * Supported order types for a currency pair
344
+ */
345
+ interface CurrencyPairOrderTypes {
346
+ /** Currency pair */
347
+ currencyPair: CurrencyPair;
348
+ /** Supported order types */
349
+ orderTypes: string[];
350
+ }
351
+ /**
352
+ * Price/Mark price bucket (OHLC data)
353
+ */
354
+ interface PriceBucket {
355
+ /** Currency pair symbol */
356
+ currencyPairSymbol: CurrencyPair;
357
+ /** Bucket period in seconds */
358
+ bucketPeriodInSeconds: number;
359
+ /** Bucket start time */
360
+ startTime: ISOTimestamp;
361
+ /** Opening price */
362
+ open: string;
363
+ /** Highest price in bucket */
364
+ high: string;
365
+ /** Lowest price in bucket */
366
+ low: string;
367
+ /** Closing price */
368
+ close: string;
369
+ /** Volume in base currency */
370
+ volume?: string;
371
+ /** Number of trades in this bucket */
372
+ numberOfTrades?: number;
373
+ }
374
+ /**
375
+ * Futures contract information
376
+ */
377
+ interface FuturesInfo {
378
+ /** Currency pair */
379
+ currencyPair: CurrencyPair;
380
+ /** Estimated funding rate */
381
+ estimatedFundingRate: string;
382
+ /** Open interest */
383
+ openInterest: string;
384
+ /** Next funding run timestamp (Unix milliseconds) */
385
+ nextFundingRun: number;
386
+ /** Next PnL run timestamp (Unix milliseconds) */
387
+ nextPnlRun: number;
388
+ }
389
+ /**
390
+ * Funding rate history entry
391
+ */
392
+ interface FundingRateHistory {
393
+ /** Currency pair */
394
+ currencyPair: CurrencyPair;
395
+ /** Funding rate */
396
+ fundingRate: string;
397
+ /** When funding occurred */
398
+ fundingTime: ISOTimestamp;
399
+ }
400
+ /**
401
+ * Loan information for a currency
402
+ */
403
+ interface LoanInfo {
404
+ /** Whether lending is supported */
405
+ lendingSupported: boolean;
406
+ /** Currency short name */
407
+ shortName: CurrencyCode;
408
+ /** Minimum interest rate */
409
+ minimumRate: string;
410
+ /** Maximum interest rate */
411
+ maximumRate: string;
412
+ /** Minimum loan amount */
413
+ minimumAmount: string;
414
+ /** Maximum loan amount */
415
+ maximumAmount: string;
416
+ }
417
+ /**
418
+ * Leverage options for a currency pair
419
+ */
420
+ interface LeverageOption {
421
+ /** Currency pair symbol */
422
+ pairSymbol: CurrencyPair;
423
+ /** Leverage multiple */
424
+ leverageMultiple: number;
425
+ /** Initial margin fraction */
426
+ initialMarginFraction: number;
427
+ /** Maintenance margin fraction */
428
+ maintenanceMarginFraction: number;
429
+ /** Auto-close margin fraction */
430
+ autoCloseMarginFraction: number;
431
+ /** Risk limit value */
432
+ riskLimitValue: number;
433
+ }
434
+ /**
435
+ * Query parameters for trade history
436
+ */
437
+ interface TradeHistoryParams extends PaginationParams, CursorPaginationParams, TimeRangeParams {
438
+ }
439
+ /**
440
+ * Query parameters for price buckets
441
+ */
442
+ interface PriceBucketsParams extends PaginationParams, TimeRangeParams {
443
+ /** Bucket period in seconds (e.g., 60, 300, 3600) */
444
+ periodSeconds?: number;
445
+ /** Include empty buckets */
446
+ includeEmpty?: boolean;
447
+ }
448
+ /**
449
+ * Query parameters for order types
450
+ */
451
+ interface OrderTypesParams {
452
+ /** Include inactive currency pairs */
453
+ includeInactivePairs?: boolean;
454
+ }
455
+
456
+ /**
457
+ * Account balance
458
+ */
459
+ interface Balance {
460
+ /** Currency code */
461
+ currency: CurrencyCode;
462
+ /** Available balance */
463
+ available: string;
464
+ /** Reserved balance (in open orders, etc.) */
465
+ reserved: string;
466
+ /** Total balance (available + reserved) */
467
+ total: string;
468
+ /** Updated timestamp */
469
+ updatedAt?: ISOTimestamp;
470
+ }
471
+ /**
472
+ * Transaction history entry
473
+ */
474
+ interface Transaction {
475
+ /** Transaction type */
476
+ transactionType: {
477
+ /** Type code */
478
+ type: TransactionType;
479
+ /** Human-readable description */
480
+ description: string;
481
+ };
482
+ /** Debited currency */
483
+ debitCurrency: CurrencyCode;
484
+ /** Debited amount */
485
+ debitValue: string;
486
+ /** Credited currency */
487
+ creditCurrency: CurrencyCode;
488
+ /** Credited amount */
489
+ creditValue: string;
490
+ /** Fee currency */
491
+ feeCurrency: CurrencyCode;
492
+ /** Fee value */
493
+ feeValue: string;
494
+ /** Event timestamp */
495
+ eventAt: ISOTimestamp;
496
+ /** Additional info (e.g., address, orderId) */
497
+ additionalInfo?: Record<string, any>;
498
+ /** Transaction ID */
499
+ id: string;
500
+ }
501
+ /**
502
+ * Trade history entry
503
+ */
504
+ interface AccountTrade$1 {
505
+ /** Trade price */
506
+ price: string;
507
+ /** Trade quantity */
508
+ quantity: string;
509
+ /** Currency pair */
510
+ currencyPair: CurrencyPair;
511
+ /** Timestamp of trade */
512
+ tradedAt: ISOTimestamp;
513
+ /** Order side (buy or sell) */
514
+ side: OrderSide;
515
+ /** Sequence ID */
516
+ sequenceId: number;
517
+ /** Trade ID */
518
+ id: string;
519
+ /** Order ID */
520
+ orderId: string;
521
+ /** Quote volume */
522
+ quoteVolume: string;
523
+ /** Fee currency */
524
+ feeCurrency?: CurrencyCode;
525
+ /** Fee amount */
526
+ feeValue?: string;
527
+ /** Taker or maker */
528
+ takerOrMaker?: 'TAKER' | 'MAKER';
529
+ /** Customer order ID if provided */
530
+ customerOrderId?: string;
531
+ }
532
+ /**
533
+ * Trade fee tier
534
+ */
535
+ interface TradeFee {
536
+ /** Currency pair */
537
+ currencyPair: CurrencyPair;
538
+ /** Maker fee (as decimal, e.g., 0.001 = 0.1%) */
539
+ makerFee: string;
540
+ /** Taker fee (as decimal) */
541
+ takerFee: string;
542
+ /** 30-day volume in ZAR */
543
+ thirtyDayVolume?: string;
544
+ }
545
+ /**
546
+ * Subaccount information
547
+ */
548
+ interface Subaccount {
549
+ /** Subaccount ID */
550
+ id: SubaccountId;
551
+ /** Subaccount label/name */
552
+ label: string;
553
+ /** When the subaccount was created */
554
+ createdAt: ISOTimestamp;
555
+ }
556
+ /**
557
+ * API key information
558
+ */
559
+ interface ApiKey {
560
+ /** API key (masked) */
561
+ key: string;
562
+ /** Key label/name */
563
+ label: string;
564
+ /** Permissions */
565
+ permissions: {
566
+ /** View permission */
567
+ view: boolean;
568
+ /** Trade permission */
569
+ trade: boolean;
570
+ /** Transfer permission */
571
+ transfer: boolean;
572
+ /** Withdraw permission */
573
+ withdraw: boolean;
574
+ /** Link bank account permission */
575
+ linkBankAccount: boolean;
576
+ };
577
+ /** When created */
578
+ createdAt: ISOTimestamp;
579
+ /** Last used timestamp */
580
+ lastUsedAt?: ISOTimestamp;
581
+ }
582
+ /**
583
+ * Query parameters for balances
584
+ */
585
+ interface BalancesParams {
586
+ /** Exclude currencies with zero balance */
587
+ excludeZeroBalances?: boolean;
588
+ }
589
+ /**
590
+ * Query parameters for transaction history
591
+ */
592
+ interface TransactionHistoryParams extends PaginationParams, CursorPaginationParams, TimeRangeParams {
593
+ /** Filter by transaction types */
594
+ transactionTypes?: TransactionType[];
595
+ /** Filter by currency */
596
+ currency?: CurrencyCode;
597
+ }
598
+ /**
599
+ * Create API key request
600
+ */
601
+ interface CreateApiKeyRequest {
602
+ /** Label for the API key */
603
+ label: string;
604
+ /** Permissions */
605
+ permissions: {
606
+ view?: boolean;
607
+ trade?: boolean;
608
+ transfer?: boolean;
609
+ withdraw?: boolean;
610
+ linkBankAccount?: boolean;
611
+ };
612
+ /** Subaccount ID (if creating key for subaccount) */
613
+ subaccountId?: SubaccountId;
614
+ }
615
+ /**
616
+ * Create API key response
617
+ */
618
+ interface CreateApiKeyResponse {
619
+ /** API key */
620
+ apiKey: string;
621
+ /** API secret (only returned once!) */
622
+ apiSecret: string;
623
+ /** Key information */
624
+ keyInfo: ApiKey;
625
+ }
626
+ /**
627
+ * Create subaccount request
628
+ */
629
+ interface CreateSubaccountRequest {
630
+ /** Label for the subaccount */
631
+ label: string;
632
+ }
633
+ /**
634
+ * Transfer between accounts request
635
+ */
636
+ interface TransferRequest {
637
+ /** Currency to transfer */
638
+ currency: CurrencyCode;
639
+ /** Amount to transfer */
640
+ amount: string;
641
+ /** Source subaccount ID (undefined for primary account) */
642
+ fromId?: SubaccountId;
643
+ /** Destination subaccount ID (undefined for primary account) */
644
+ toId?: SubaccountId;
645
+ }
646
+
647
+ /**
648
+ * Base order request fields
649
+ */
650
+ interface BaseOrderRequest {
651
+ /** Currency pair to trade */
652
+ pair: CurrencyPair;
653
+ /** Order side (BUY or SELL) */
654
+ side: OrderSide;
655
+ /** Optional customer order ID (max 50 chars, alphanumeric + underscore/hyphen) */
656
+ customerOrderId?: CustomerOrderId;
657
+ }
658
+ /**
659
+ * Limit order request (v1)
660
+ */
661
+ interface LimitOrderRequest extends BaseOrderRequest {
662
+ /** Quantity in base currency */
663
+ quantity: string;
664
+ /** Price per unit */
665
+ price: string;
666
+ /** Post-only behavior */
667
+ postOnly?: PostOnly;
668
+ /** Time in force */
669
+ timeInForce?: TimeInForce;
670
+ }
671
+ /**
672
+ * Limit order request (v2)
673
+ */
674
+ interface LimitOrderRequestV2 extends BaseOrderRequest {
675
+ /** Quantity in base currency */
676
+ baseAmount?: string;
677
+ /** Quantity in quote currency */
678
+ quoteAmount?: string;
679
+ /** Price per unit */
680
+ price: string;
681
+ /** Post-only behavior */
682
+ postOnly?: PostOnly;
683
+ /** Time in force */
684
+ timeInForce?: TimeInForce;
685
+ }
686
+ /**
687
+ * Market order request (v1)
688
+ */
689
+ interface MarketOrderRequest extends BaseOrderRequest {
690
+ /** Base amount (optional, either baseAmount or quoteAmount required) */
691
+ baseAmount?: string;
692
+ /** Quote amount (optional, either baseAmount or quoteAmount required) */
693
+ quoteAmount?: string;
694
+ }
695
+ /**
696
+ * Market order request (v2)
697
+ */
698
+ interface MarketOrderRequestV2 extends MarketOrderRequest {
699
+ }
700
+ /**
701
+ * Stop-limit order request (v1)
702
+ */
703
+ interface StopLimitOrderRequest extends LimitOrderRequest {
704
+ /** Stop price that triggers the order */
705
+ stopPrice: string;
706
+ }
707
+ /**
708
+ * Stop-limit order request (v2)
709
+ */
710
+ interface StopLimitOrderRequestV2 extends LimitOrderRequestV2 {
711
+ /** Stop price that triggers the order */
712
+ stopPrice: string;
713
+ }
714
+ /**
715
+ * Simple buy/sell quote request
716
+ */
717
+ interface SimpleQuoteRequest {
718
+ /** Currency pair */
719
+ pair: CurrencyPair;
720
+ /** Pay-in currency code */
721
+ payInCurrency: string;
722
+ /** Pay-in amount */
723
+ payAmount: string;
724
+ /** Order side (BUY or SELL) */
725
+ side: OrderSide;
726
+ }
727
+ /**
728
+ * Simple buy/sell quote response
729
+ */
730
+ interface SimpleQuoteResponse {
731
+ /** Currency pair */
732
+ currencyPair: CurrencyPair;
733
+ /** Pay currency */
734
+ payInCurrency: string;
735
+ /** Pay amount */
736
+ payAmount: string;
737
+ /** Receive currency */
738
+ receiveAmount: string;
739
+ /** Fee amount */
740
+ feeAmount: string;
741
+ /** Fee currency */
742
+ feeCurrency: string;
743
+ /** Quote ID (use within 5 seconds) */
744
+ id: string;
745
+ /** When quote was created */
746
+ createdAt: ISOTimestamp;
747
+ /** When quote expires */
748
+ expiresAt: ISOTimestamp;
749
+ }
750
+ /**
751
+ * Simple buy/sell order request
752
+ */
753
+ interface SimpleOrderRequest {
754
+ /** Currency pair */
755
+ pair: CurrencyPair;
756
+ /** Quote ID from quote request */
757
+ quoteId: string;
758
+ }
759
+ /**
760
+ * Order response
761
+ */
762
+ interface OrderResponse {
763
+ /** Internal order ID */
764
+ id: OrderId;
765
+ /** Customer order ID if provided */
766
+ customerOrderId?: CustomerOrderId;
767
+ /** HTTP status indicator */
768
+ success?: boolean;
769
+ /** Message */
770
+ message?: string;
771
+ }
772
+ /**
773
+ * Batch order request
774
+ */
775
+ interface BatchOrderRequest {
776
+ /** List of order requests */
777
+ requests: (LimitOrderRequest | MarketOrderRequest)[];
778
+ }
779
+ /**
780
+ * Batch order response item
781
+ */
782
+ interface BatchOrderResponseItem {
783
+ /** Whether order was accepted */
784
+ status: BatchOrderStatus;
785
+ /** Order ID if accepted */
786
+ id?: OrderId;
787
+ /** Customer order ID if provided */
788
+ customerOrderId?: CustomerOrderId;
789
+ /** Error message if failed */
790
+ message?: string;
791
+ }
792
+ /**
793
+ * Batch order response
794
+ */
795
+ type BatchOrderResponse = BatchOrderResponseItem[];
796
+ /**
797
+ * Order status summary
798
+ */
799
+ interface OrderStatusSummary {
800
+ /** Order ID */
801
+ orderId: OrderId;
802
+ /** Order type */
803
+ orderType: OrderType;
804
+ /** Currency pair */
805
+ currencyPair: CurrencyPair;
806
+ /** Average price */
807
+ averagePrice: string;
808
+ /** Original price */
809
+ originalPrice: string;
810
+ /** Remaining quantity */
811
+ remainingQuantity: string;
812
+ /** Original quantity */
813
+ originalQuantity: string;
814
+ /** Total filled */
815
+ total: string;
816
+ /** Total fee */
817
+ totalFee: string;
818
+ /** Fee currency */
819
+ feeCurrency: string;
820
+ /** Order status */
821
+ orderStatus: OrderStatus;
822
+ /** Order side */
823
+ orderSide: OrderSide;
824
+ /** When order was created */
825
+ orderCreatedAt: ISOTimestamp;
826
+ /** When order was updated */
827
+ orderUpdatedAt: ISOTimestamp;
828
+ /** When order expires (for GTD orders) */
829
+ orderExpiresAt?: ISOTimestamp;
830
+ /** Customer order ID if provided */
831
+ customerOrderId?: CustomerOrderId;
832
+ /** Time in force */
833
+ timeInForce?: TimeInForce;
834
+ /** Stop price (for stop-limit orders) */
835
+ stopPrice?: string;
836
+ }
837
+ /**
838
+ * Order status detail (includes individual trades)
839
+ */
840
+ interface OrderStatusDetail extends OrderStatusSummary {
841
+ /** Order trades */
842
+ orderTrades: OrderTrade[];
843
+ }
844
+ /**
845
+ * Individual trade within an order
846
+ */
847
+ interface OrderTrade {
848
+ /** Trade price */
849
+ price: string;
850
+ /** Trade quantity */
851
+ quantity: string;
852
+ /** Currency pair */
853
+ currencyPair: CurrencyPair;
854
+ /** When trade occurred */
855
+ tradedAt: ISOTimestamp;
856
+ /** Taker or maker */
857
+ takerOrMaker: 'TAKER' | 'MAKER';
858
+ /** Trade ID */
859
+ id: string;
860
+ /** Sequence ID */
861
+ sequenceId: number;
862
+ /** Quote volume */
863
+ quoteVolume: string;
864
+ }
865
+ /**
866
+ * Open order
867
+ */
868
+ interface OpenOrder {
869
+ /** Order ID */
870
+ orderId: OrderId;
871
+ /** Order side */
872
+ side: OrderSide;
873
+ /** Remaining quantity */
874
+ remainingQuantity: string;
875
+ /** Original price */
876
+ originalPrice: string;
877
+ /** Currency pair */
878
+ currencyPair: CurrencyPair;
879
+ /** When created */
880
+ createdAt: ISOTimestamp;
881
+ /** Original quantity */
882
+ originalQuantity: string;
883
+ /** Filled percentage */
884
+ filledPercentage: string;
885
+ /** Customer order ID if provided */
886
+ customerOrderId?: CustomerOrderId;
887
+ /** Order type */
888
+ orderType: OrderType;
889
+ /** Stop price (for stop-limit orders) */
890
+ stopPrice?: string;
891
+ /** Time in force */
892
+ timeInForce?: TimeInForce;
893
+ /** Order status */
894
+ status?: OrderStatus;
895
+ }
896
+ /**
897
+ * Conditional order request
898
+ */
899
+ interface ConditionalOrderRequest {
900
+ /** Currency pair */
901
+ pair: CurrencyPair;
902
+ /** Order side */
903
+ side: OrderSide;
904
+ /** Conditional order type */
905
+ type: ConditionalOrderType;
906
+ /** Trigger price */
907
+ triggerPrice: string;
908
+ /** Trigger type */
909
+ triggerType?: ConditionalOrderTriggerType;
910
+ /** Quantity */
911
+ quantity: string;
912
+ /** Limit price (for limit orders) */
913
+ price?: string;
914
+ /** Time in force */
915
+ timeInForce?: TimeInForce;
916
+ /** Customer order ID */
917
+ customerOrderId?: CustomerOrderId;
918
+ }
919
+ /**
920
+ * Conditional order response
921
+ */
922
+ interface ConditionalOrderResponse {
923
+ /** Conditional order ID */
924
+ id: string;
925
+ /** Customer order ID if provided */
926
+ customerOrderId?: CustomerOrderId;
927
+ }
928
+ /**
929
+ * Conditional order status
930
+ */
931
+ interface ConditionalOrderStatus {
932
+ /** Conditional order ID */
933
+ id: string;
934
+ /** Currency pair */
935
+ currencyPair: CurrencyPair;
936
+ /** Order side */
937
+ side: OrderSide;
938
+ /** Conditional order type */
939
+ type: ConditionalOrderType;
940
+ /** Trigger price */
941
+ triggerPrice: string;
942
+ /** Trigger type */
943
+ triggerType: ConditionalOrderTriggerType;
944
+ /** Quantity */
945
+ quantity: string;
946
+ /** Limit price (if limit order) */
947
+ price?: string;
948
+ /** Status */
949
+ status: 'PENDING' | 'TRIGGERED' | 'CANCELLED' | 'FAILED';
950
+ /** When created */
951
+ createdAt: ISOTimestamp;
952
+ /** When updated */
953
+ updatedAt: ISOTimestamp;
954
+ /** Customer order ID if provided */
955
+ customerOrderId?: CustomerOrderId;
956
+ /** Triggered order ID (if triggered) */
957
+ triggeredOrderId?: OrderId;
958
+ }
959
+ /**
960
+ * Modify order request
961
+ */
962
+ interface ModifyOrderRequest {
963
+ /** Order ID or customer order ID */
964
+ orderId?: OrderId;
965
+ /** Customer order ID */
966
+ customerOrderId?: CustomerOrderId;
967
+ /** Currency pair */
968
+ pair: CurrencyPair;
969
+ /** New quantity (optional) */
970
+ quantity?: string;
971
+ /** New price (optional) */
972
+ price?: string;
973
+ }
974
+ /**
975
+ * Modify order request (v2)
976
+ */
977
+ interface ModifyOrderRequestV2 {
978
+ /** Order ID or customer order ID */
979
+ orderId?: OrderId;
980
+ /** Customer order ID */
981
+ customerOrderId?: CustomerOrderId;
982
+ /** Currency pair */
983
+ pair: CurrencyPair;
984
+ /** New base amount (optional) */
985
+ baseAmount?: string;
986
+ /** New quote amount (optional) */
987
+ quoteAmount?: string;
988
+ /** New price (optional) */
989
+ price?: string;
990
+ }
991
+ /**
992
+ * Cancel order request
993
+ */
994
+ interface CancelOrderRequest {
995
+ /** Order ID */
996
+ orderId?: OrderId;
997
+ /** Customer order ID */
998
+ customerOrderId?: CustomerOrderId;
999
+ /** Currency pair */
1000
+ pair: CurrencyPair;
1001
+ }
1002
+ /**
1003
+ * Cancel order request (v2)
1004
+ */
1005
+ interface CancelOrderRequestV2 extends CancelOrderRequest {
1006
+ }
1007
+ /**
1008
+ * Order history query parameters
1009
+ */
1010
+ interface OrderHistoryParams extends PaginationParams {
1011
+ /** Filter by order statuses */
1012
+ statuses?: OrderStatus[];
1013
+ /** Filter by currency pairs */
1014
+ currencyPair?: CurrencyPair | CurrencyPair[];
1015
+ /** Start time filter */
1016
+ startTime?: ISOTimestamp;
1017
+ /** End time filter */
1018
+ endTime?: ISOTimestamp;
1019
+ }
1020
+ /**
1021
+ * Historical order summary
1022
+ */
1023
+ interface HistoricalOrderSummary extends OrderStatusSummary {
1024
+ }
1025
+ /**
1026
+ * Historical order detail
1027
+ */
1028
+ interface HistoricalOrderDetail extends OrderStatusDetail {
1029
+ }
1030
+
1031
+ /**
1032
+ * Crypto deposit address
1033
+ */
1034
+ interface DepositAddress {
1035
+ /** Currency code */
1036
+ currency: CurrencyCode;
1037
+ /** Deposit address */
1038
+ address: CryptoAddress;
1039
+ /** Network type */
1040
+ networkType?: NetworkType;
1041
+ /** Additional deposit info (e.g., memo, tag) */
1042
+ additionalInfo?: {
1043
+ paymentReference?: string;
1044
+ memo?: string;
1045
+ destinationTag?: string;
1046
+ };
1047
+ }
1048
+ /**
1049
+ * Crypto withdrawal request
1050
+ */
1051
+ interface CryptoWithdrawalRequest {
1052
+ /** Currency to withdraw */
1053
+ currency: CurrencyCode;
1054
+ /** Amount to withdraw */
1055
+ amount: string;
1056
+ /** Destination address */
1057
+ address: CryptoAddress;
1058
+ /** Network type (optional) */
1059
+ networkType?: NetworkType;
1060
+ /** Payment reference/memo/tag (optional) */
1061
+ paymentReference?: string;
1062
+ }
1063
+ /**
1064
+ * Crypto withdrawal response
1065
+ */
1066
+ interface CryptoWithdrawalResponse {
1067
+ /** Withdrawal ID */
1068
+ id: string;
1069
+ /** Currency */
1070
+ currency: CurrencyCode;
1071
+ /** Amount */
1072
+ amount: string;
1073
+ /** Fee */
1074
+ fee: string;
1075
+ /** Destination address */
1076
+ address: CryptoAddress;
1077
+ /** Transaction hash (once broadcast) */
1078
+ transactionHash?: string;
1079
+ /** Confirmations */
1080
+ confirmations?: number;
1081
+ /** Status */
1082
+ status: 'PENDING' | 'PROCESSING' | 'CONFIRMED' | 'FAILED' | 'CANCELLED';
1083
+ /** Created timestamp */
1084
+ createdAt: ISOTimestamp;
1085
+ }
1086
+ /**
1087
+ * Crypto withdrawal status
1088
+ */
1089
+ interface CryptoWithdrawalStatus extends CryptoWithdrawalResponse {
1090
+ }
1091
+ /**
1092
+ * Crypto withdrawal history parameters
1093
+ */
1094
+ interface CryptoWithdrawalHistoryParams extends PaginationParams {
1095
+ /** Filter by currency */
1096
+ currency?: CurrencyCode;
1097
+ }
1098
+ /**
1099
+ * Fiat bank account
1100
+ */
1101
+ interface BankAccount {
1102
+ /** Bank account ID */
1103
+ id: string;
1104
+ /** Bank name */
1105
+ bank: string;
1106
+ /** Account holder name */
1107
+ accountHolder: string;
1108
+ /** Account number (masked) */
1109
+ accountNumber: string;
1110
+ /** Branch code */
1111
+ branchCode?: string;
1112
+ /** Account type */
1113
+ accountType?: string;
1114
+ /** Verified status */
1115
+ verified: boolean;
1116
+ }
1117
+ /**
1118
+ * Link bank account request
1119
+ */
1120
+ interface LinkBankAccountRequest {
1121
+ /** Bank name */
1122
+ bank: string;
1123
+ /** Account holder name */
1124
+ accountHolder: string;
1125
+ /** Account number */
1126
+ accountNumber: string;
1127
+ /** Branch code */
1128
+ branchCode?: string;
1129
+ /** Account type */
1130
+ accountType?: string;
1131
+ }
1132
+ /**
1133
+ * Fiat withdrawal request
1134
+ */
1135
+ interface FiatWithdrawalRequest {
1136
+ /** Currency (e.g., ZAR) */
1137
+ currency: CurrencyCode;
1138
+ /** Amount to withdraw */
1139
+ amount: string;
1140
+ /** Bank account ID (from linked accounts) */
1141
+ beneficiaryId: string;
1142
+ /** Whether this is a fast withdrawal */
1143
+ fast?: boolean;
1144
+ }
1145
+ /**
1146
+ * Fiat withdrawal response
1147
+ */
1148
+ interface FiatWithdrawalResponse {
1149
+ /** Withdrawal ID */
1150
+ id: string;
1151
+ /** Currency */
1152
+ currency: CurrencyCode;
1153
+ /** Amount */
1154
+ amount: string;
1155
+ /** Fee */
1156
+ fee: string;
1157
+ /** Bank account ID */
1158
+ beneficiaryId: string;
1159
+ /** Status */
1160
+ status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
1161
+ /** Created timestamp */
1162
+ createdAt: ISOTimestamp;
1163
+ }
1164
+ /**
1165
+ * Fiat deposit reference
1166
+ */
1167
+ interface FiatDepositReference {
1168
+ /** Unique payment reference */
1169
+ paymentReference: string;
1170
+ /** Bank account details for deposit */
1171
+ bankAccountDetails: {
1172
+ bank: string;
1173
+ accountHolder: string;
1174
+ accountNumber: string;
1175
+ branchCode?: string;
1176
+ };
1177
+ }
1178
+
1179
+ /**
1180
+ * Futures position
1181
+ */
1182
+ interface FuturesPosition {
1183
+ /** Currency pair */
1184
+ currencyPair: CurrencyPair;
1185
+ /** Position side (LONG or SHORT) */
1186
+ side: 'LONG' | 'SHORT';
1187
+ /** Position quantity */
1188
+ quantity: string;
1189
+ /** Average entry price */
1190
+ entryPrice: string;
1191
+ /** Mark price */
1192
+ markPrice: string;
1193
+ /** Liquidation price */
1194
+ liquidationPrice: string;
1195
+ /** Unrealized PnL */
1196
+ unrealizedPnl: string;
1197
+ /** Realized PnL */
1198
+ realizedPnl: string;
1199
+ /** Margin */
1200
+ margin: string;
1201
+ /** Leverage */
1202
+ leverage: number;
1203
+ /** Auto-close enabled */
1204
+ autoClose: boolean;
1205
+ /** When position was opened */
1206
+ openedAt: ISOTimestamp;
1207
+ }
1208
+ /**
1209
+ * Closed futures position summary
1210
+ */
1211
+ interface ClosedPositionSummary {
1212
+ /** Currency pair */
1213
+ currencyPair: CurrencyPair;
1214
+ /** Realized PnL */
1215
+ realizedPnl: string;
1216
+ /** Total funding */
1217
+ totalFunding: string;
1218
+ /** Number of positions closed */
1219
+ positionCount: number;
1220
+ }
1221
+ /**
1222
+ * Closed futures position
1223
+ */
1224
+ interface ClosedPosition {
1225
+ /** Currency pair */
1226
+ currencyPair: CurrencyPair;
1227
+ /** Position side */
1228
+ side: 'LONG' | 'SHORT';
1229
+ /** Entry price */
1230
+ entryPrice: string;
1231
+ /** Exit price */
1232
+ exitPrice: string;
1233
+ /** Quantity */
1234
+ quantity: string;
1235
+ /** Realized PnL */
1236
+ realizedPnl: string;
1237
+ /** When opened */
1238
+ openedAt: ISOTimestamp;
1239
+ /** When closed */
1240
+ closedAt: ISOTimestamp;
1241
+ }
1242
+ /**
1243
+ * Funding payment
1244
+ */
1245
+ interface FundingPayment {
1246
+ /** Currency pair */
1247
+ currencyPair: CurrencyPair;
1248
+ /** Funding rate */
1249
+ fundingRate: string;
1250
+ /** Funding amount paid/received */
1251
+ fundingAmount: string;
1252
+ /** Position size at funding time */
1253
+ positionSize: string;
1254
+ /** When funding occurred */
1255
+ fundingTime: ISOTimestamp;
1256
+ }
1257
+ /**
1258
+ * Leverage information for a currency pair
1259
+ */
1260
+ interface LeverageInfo {
1261
+ /** Currency pair */
1262
+ currencyPair: CurrencyPair;
1263
+ /** Current leverage multiple */
1264
+ leverageMultiple: number;
1265
+ /** Maximum available leverage */
1266
+ maxLeverageMultiple: number;
1267
+ }
1268
+ /**
1269
+ * Update leverage request
1270
+ */
1271
+ interface UpdateLeverageRequest {
1272
+ /** New leverage multiple (1-10) */
1273
+ leverageMultiple: number;
1274
+ }
1275
+ /**
1276
+ * Futures position history params
1277
+ */
1278
+ interface PositionHistoryParams extends PaginationParams {
1279
+ /** Filter by currency pair */
1280
+ currencyPair?: CurrencyPair;
1281
+ }
1282
+ /**
1283
+ * Funding history params
1284
+ */
1285
+ interface FundingHistoryParams extends PaginationParams {
1286
+ /** Filter by currency pair */
1287
+ currencyPair?: CurrencyPair;
1288
+ }
1289
+
1290
+ /**
1291
+ * Margin account status
1292
+ */
1293
+ interface MarginStatus {
1294
+ /** Whether margin trading is enabled */
1295
+ enabled: boolean;
1296
+ /** Total equity (collateral value) */
1297
+ totalEquity: string;
1298
+ /** Total borrowed */
1299
+ totalBorrowed: string;
1300
+ /** Available margin */
1301
+ availableMargin: string;
1302
+ /** Margin used */
1303
+ marginUsed: string;
1304
+ /** Margin ratio (equity / borrowed) */
1305
+ marginRatio: string;
1306
+ /** Whether account is in margin call */
1307
+ marginCall: boolean;
1308
+ /** Liquidation risk level */
1309
+ liquidationRisk?: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
1310
+ }
1311
+ /**
1312
+ * Enable margin trading request
1313
+ */
1314
+ interface EnableMarginRequest {
1315
+ /** Accept terms and conditions */
1316
+ acceptTerms: boolean;
1317
+ }
1318
+ /**
1319
+ * Currency leverage settings
1320
+ */
1321
+ interface CurrencyLeverageSettings {
1322
+ /** Currency pair */
1323
+ currencyPair: CurrencyPair;
1324
+ /** Leverage multiple */
1325
+ leverageMultiple: number;
1326
+ }
1327
+
1328
+ /**
1329
+ * Loan rate information
1330
+ */
1331
+ interface LoanRate {
1332
+ /** Currency symbol */
1333
+ currency: CurrencyCode;
1334
+ /** Interest rate applied during the most recent interest auction */
1335
+ previousFundingRate: number;
1336
+ /** Estimated rate of interest for the next funding period */
1337
+ estimatedNextRate: number;
1338
+ /** Estimated interest rate that will be charged to borrowers in the next funding round */
1339
+ estimatedNextBorrowRate: string;
1340
+ }
1341
+ /**
1342
+ * Open loan
1343
+ */
1344
+ interface OpenLoan {
1345
+ /** Loan ID */
1346
+ loanId: string;
1347
+ /** Currency symbol */
1348
+ currency: CurrencyCode;
1349
+ /** Total loan amount */
1350
+ totalAmount: string;
1351
+ /** Amount of the loan that has been used */
1352
+ usedAmount: string;
1353
+ /** Hourly interest rate */
1354
+ hourlyRate: string;
1355
+ /** When the loan was created */
1356
+ createdAt: ISOTimestamp;
1357
+ /** When the loan was last updated */
1358
+ updatedAt: ISOTimestamp;
1359
+ }
1360
+ /**
1361
+ * Create loan request
1362
+ */
1363
+ interface CreateLoanRequest {
1364
+ /** Currency symbol to borrow */
1365
+ currencySymbol: CurrencyCode;
1366
+ /** Hourly interest rate */
1367
+ hourlyRate: string;
1368
+ /** Amount to borrow */
1369
+ amount: string;
1370
+ }
1371
+ /**
1372
+ * Loan credit history item
1373
+ */
1374
+ interface LoanCreditHistoryItem {
1375
+ /** Currency symbol */
1376
+ currency: CurrencyCode;
1377
+ /** Interest amount charged */
1378
+ interestAmount: string;
1379
+ /** Loan quantity/amount */
1380
+ quantity: string;
1381
+ /** When this credit entry was created */
1382
+ createdAt: ISOTimestamp;
1383
+ }
1384
+ /**
1385
+ * Increase loan amount request
1386
+ */
1387
+ interface IncreaseLoanRequest {
1388
+ /** Currency symbol */
1389
+ currencySymbol: CurrencyCode;
1390
+ /** Amount to increase the loan by */
1391
+ increaseLoanAmountBy: string;
1392
+ /** Loan ID */
1393
+ loanId: string;
1394
+ }
1395
+ /**
1396
+ * Change loan rate request
1397
+ */
1398
+ interface ChangeLoanRateRequest {
1399
+ /** Currency symbol */
1400
+ currencySymbol: CurrencyCode;
1401
+ /** New hourly rate */
1402
+ hourlyRate: string;
1403
+ /** Loan ID */
1404
+ loanId: string;
1405
+ }
1406
+ /**
1407
+ * Request unlock request
1408
+ */
1409
+ interface RequestUnlockRequest {
1410
+ /** Currency symbol */
1411
+ currencySymbol: CurrencyCode;
1412
+ /** Amount to unlock */
1413
+ unlockAmount: string;
1414
+ /** Loan ID */
1415
+ loanId: string;
1416
+ }
1417
+ /**
1418
+ * Borrow history item
1419
+ */
1420
+ interface BorrowHistoryItem {
1421
+ /** Currency symbol */
1422
+ currency: CurrencyCode;
1423
+ /** Borrow amount */
1424
+ amount: string;
1425
+ /** Interest rate */
1426
+ rate: string;
1427
+ /** When the borrow occurred */
1428
+ createdAt: ISOTimestamp;
1429
+ }
1430
+
1431
+ /**
1432
+ * Earn type - STAKE or LEND
1433
+ */
1434
+ type EarnType = 'STAKE' | 'LEND';
1435
+ /**
1436
+ * Stake/Lock request
1437
+ */
1438
+ interface StakeRequest {
1439
+ /** Currency symbol to stake */
1440
+ currencySymbol: CurrencyCode;
1441
+ /** Amount to stake */
1442
+ amount: string;
1443
+ /** Earn type (STAKE or LEND) */
1444
+ earnType: EarnType;
1445
+ }
1446
+ /**
1447
+ * Unstake/Unlock request
1448
+ */
1449
+ interface UnstakeRequest {
1450
+ /** Currency symbol to unstake */
1451
+ currencySymbol: CurrencyCode;
1452
+ /** Amount to unstake */
1453
+ amount: string;
1454
+ /** Earn type (STAKE or LEND) */
1455
+ earnType: EarnType;
1456
+ }
1457
+ /**
1458
+ * Earn balance information
1459
+ */
1460
+ interface EarnBalance {
1461
+ /** Currency symbol */
1462
+ currencySymbol: CurrencyCode;
1463
+ /** Current staked/lent amount */
1464
+ amount: string;
1465
+ /** Earn type */
1466
+ earnType: string;
1467
+ /** Last updated timestamp */
1468
+ lastUpdated: ISOTimestamp;
1469
+ }
1470
+ /**
1471
+ * Earn rate information
1472
+ */
1473
+ interface EarnRate {
1474
+ /** Currency symbol */
1475
+ currencySymbol: CurrencyCode;
1476
+ /** Earning rate per period */
1477
+ rate: string;
1478
+ /** Period interval in minutes */
1479
+ periodIntervalMinutes: number;
1480
+ /** Minimum amount required to stake */
1481
+ minimumStakeAmount: string;
1482
+ /** Earn type */
1483
+ earnType: string;
1484
+ }
1485
+ /**
1486
+ * Earn reward information
1487
+ */
1488
+ interface EarnReward {
1489
+ /** Reward period timestamp */
1490
+ period: ISOTimestamp;
1491
+ /** Reward amount earned */
1492
+ rewardAmount: string;
1493
+ /** Rate for this period */
1494
+ rate: string;
1495
+ /** Annualized rate (percentage) */
1496
+ ratePerYear: string;
1497
+ /** Currency symbol */
1498
+ currencySymbol: CurrencyCode;
1499
+ /** Earn type */
1500
+ earnType: string;
1501
+ }
1502
+ /**
1503
+ * Earn history transaction type
1504
+ */
1505
+ type EarnHistoryType = 'STAKE' | 'UNSTAKE';
1506
+ /**
1507
+ * Earn history item
1508
+ */
1509
+ interface EarnHistoryItem {
1510
+ /** Transaction type (STAKE or UNSTAKE) */
1511
+ type: EarnHistoryType;
1512
+ /** Currency symbol */
1513
+ currencySymbol: CurrencyCode;
1514
+ /** Amount staked or unstaked */
1515
+ amount: string;
1516
+ /** Earn type */
1517
+ earnType: string;
1518
+ /** Completion timestamp */
1519
+ completedAt: ISOTimestamp;
1520
+ }
1521
+ /**
1522
+ * Parameters for earn balances query
1523
+ */
1524
+ interface EarnBalancesParams {
1525
+ /** Earn type filter (optional, default: STAKE) */
1526
+ earnType?: EarnType;
1527
+ }
1528
+ /**
1529
+ * Parameters for earn rates query
1530
+ */
1531
+ interface EarnRatesParams {
1532
+ /** Earn type filter (optional, default: STAKE) */
1533
+ earnType?: EarnType;
1534
+ }
1535
+ /**
1536
+ * Parameters for earn rewards query
1537
+ */
1538
+ interface EarnRewardsParams {
1539
+ /** Currency symbol to query */
1540
+ currencySymbol: CurrencyCode;
1541
+ /** Earn type filter (optional, default: STAKE) */
1542
+ earnType?: EarnType;
1543
+ /** Number of items to skip (pagination) */
1544
+ skip?: number;
1545
+ /** Maximum number of items to return (max: 100) */
1546
+ limit?: number;
1547
+ }
1548
+ /**
1549
+ * Parameters for earn history query
1550
+ */
1551
+ interface EarnHistoryParams {
1552
+ /** Currency symbol to query */
1553
+ currencySymbol: CurrencyCode;
1554
+ /** Earn type filter (optional, default: STAKE) */
1555
+ earnType?: EarnType;
1556
+ /** Number of items to skip (pagination) */
1557
+ skip?: number;
1558
+ /** Maximum number of items to return (max: 100) */
1559
+ limit?: number;
1560
+ }
1561
+
1562
+ /**
1563
+ * Payment request
1564
+ */
1565
+ interface CreatePaymentRequest {
1566
+ /** Merchant ID */
1567
+ merchantId: string;
1568
+ /** Currency */
1569
+ currency: CurrencyCode;
1570
+ /** Amount */
1571
+ amount: string;
1572
+ /** Description */
1573
+ description?: string;
1574
+ /** Return URL after payment */
1575
+ returnUrl?: string;
1576
+ /** Callback URL for payment notifications */
1577
+ callbackUrl?: string;
1578
+ }
1579
+ /**
1580
+ * Payment
1581
+ */
1582
+ interface Payment {
1583
+ /** Payment ID */
1584
+ id: string;
1585
+ /** Merchant ID */
1586
+ merchantId: string;
1587
+ /** Currency */
1588
+ currency: CurrencyCode;
1589
+ /** Amount */
1590
+ amount: string;
1591
+ /** Payment status */
1592
+ status: 'PENDING' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED';
1593
+ /** Payment URL */
1594
+ paymentUrl: string;
1595
+ /** When created */
1596
+ createdAt: ISOTimestamp;
1597
+ /** When expires */
1598
+ expiresAt: ISOTimestamp;
1599
+ /** When completed */
1600
+ completedAt?: ISOTimestamp;
1601
+ }
1602
+ /**
1603
+ * Payment status
1604
+ */
1605
+ interface PaymentStatus extends Payment {
1606
+ }
1607
+
1608
+ /**
1609
+ * Bundle (basket of currencies)
1610
+ */
1611
+ interface Bundle {
1612
+ /** Bundle ID */
1613
+ id: string;
1614
+ /** Bundle name */
1615
+ name: string;
1616
+ /** Bundle description */
1617
+ description: string;
1618
+ /** Currencies and their weights */
1619
+ composition: BundleComposition[];
1620
+ /** Whether bundle is available */
1621
+ available: boolean;
1622
+ }
1623
+ /**
1624
+ * Bundle composition (currency weight)
1625
+ */
1626
+ interface BundleComposition {
1627
+ /** Currency */
1628
+ currency: CurrencyCode;
1629
+ /** Weight/percentage in bundle */
1630
+ weight: string;
1631
+ }
1632
+ /**
1633
+ * Buy bundle request
1634
+ */
1635
+ interface BuyBundleRequest {
1636
+ /** Bundle ID */
1637
+ bundleId: string;
1638
+ /** Amount to invest (in quote currency) */
1639
+ amount: string;
1640
+ /** Quote currency */
1641
+ quoteCurrency: CurrencyCode;
1642
+ }
1643
+ /**
1644
+ * Bundle order
1645
+ */
1646
+ interface BundleOrder {
1647
+ /** Order ID */
1648
+ id: string;
1649
+ /** Bundle ID */
1650
+ bundleId: string;
1651
+ /** Amount invested */
1652
+ amount: string;
1653
+ /** Status */
1654
+ status: 'PENDING' | 'COMPLETED' | 'FAILED';
1655
+ /** When created */
1656
+ createdAt: ISOTimestamp;
1657
+ }
1658
+
1659
+ /**
1660
+ * WebSocket message type
1661
+ */
1662
+ type WebSocketMessageType = 'AUTHENTICATED' | 'SUBSCRIBED' | 'UNSUBSCRIBED' | 'AGGREGATED_ORDERBOOK_UPDATE' | 'FULL_ORDERBOOK_UPDATE' | 'MARKET_SUMMARY_UPDATE' | 'NEW_TRADE' | 'NEW_TRADE_BUCKET' | 'INSTANT_ORDER_COMPLETED' | 'ORDER_PROCESSED' | 'ORDER_STATUS_UPDATE' | 'BALANCE_UPDATE' | 'NEW_ACCOUNT_TRADE' | 'OPEN_ORDERS_UPDATE' | 'NEW_PENDING_RECEIVE' | 'SEND_STATUS_UPDATE' | 'FAILED_CANCEL_ORDER' | 'PONG';
1663
+ /**
1664
+ * Base WebSocket message
1665
+ */
1666
+ interface BaseWebSocketMessage {
1667
+ /** Message type */
1668
+ type: WebSocketMessageType;
1669
+ }
1670
+ /**
1671
+ * Subscription request
1672
+ */
1673
+ interface SubscriptionRequest {
1674
+ /** Subscription type */
1675
+ type: 'SUBSCRIBE' | 'UNSUBSCRIBE';
1676
+ /** Subscriptions */
1677
+ subscriptions: Subscription[];
1678
+ }
1679
+ /**
1680
+ * Subscription
1681
+ */
1682
+ interface Subscription {
1683
+ /** Event type */
1684
+ event: string;
1685
+ /** Currency pairs (optional) */
1686
+ pairs?: CurrencyPair[];
1687
+ }
1688
+ /**
1689
+ * Order book update (WebSocket)
1690
+ */
1691
+ interface OrderBookUpdate extends BaseWebSocketMessage {
1692
+ type: 'AGGREGATED_ORDERBOOK_UPDATE' | 'FULL_ORDERBOOK_UPDATE';
1693
+ /** Currency pair */
1694
+ currencyPairSymbol: CurrencyPair;
1695
+ /** Ask orders */
1696
+ Asks: Array<{
1697
+ side: 'sell';
1698
+ quantity: string;
1699
+ price: string;
1700
+ currencyPair: CurrencyPair;
1701
+ orderCount: number;
1702
+ }>;
1703
+ /** Bid orders */
1704
+ Bids: Array<{
1705
+ side: 'buy';
1706
+ quantity: string;
1707
+ price: string;
1708
+ currencyPair: CurrencyPair;
1709
+ orderCount: number;
1710
+ }>;
1711
+ /** Last change sequence */
1712
+ LastChange?: string;
1713
+ /** Checksum */
1714
+ Checksum?: number;
1715
+ }
1716
+ /**
1717
+ * Market summary update (WebSocket)
1718
+ */
1719
+ interface MarketSummaryUpdate extends BaseWebSocketMessage {
1720
+ type: 'MARKET_SUMMARY_UPDATE';
1721
+ /** Currency pair */
1722
+ currencyPairSymbol: CurrencyPair;
1723
+ /** Ask price */
1724
+ askPrice: string;
1725
+ /** Bid price */
1726
+ bidPrice: string;
1727
+ /** Last traded price */
1728
+ lastTradedPrice: string;
1729
+ /** Previous close price */
1730
+ previousClosePrice: string;
1731
+ /** Base volume */
1732
+ baseVolume: string;
1733
+ /** Quote volume */
1734
+ quoteVolume: string;
1735
+ /** High price */
1736
+ highPrice: string;
1737
+ /** Low price */
1738
+ lowPrice: string;
1739
+ /** Change from previous */
1740
+ changeFromPrevious: string;
1741
+ /** Created timestamp */
1742
+ created: ISOTimestamp;
1743
+ }
1744
+ /**
1745
+ * New trade (WebSocket)
1746
+ */
1747
+ interface NewTrade extends BaseWebSocketMessage {
1748
+ type: 'NEW_TRADE';
1749
+ /** Currency pair */
1750
+ currencyPairSymbol: CurrencyPair;
1751
+ /** Trade price */
1752
+ price: string;
1753
+ /** Trade quantity */
1754
+ quantity: string;
1755
+ /** Taker side */
1756
+ takerSide: OrderSide;
1757
+ /** Traded at */
1758
+ tradedAt: ISOTimestamp;
1759
+ /** Sequence ID */
1760
+ sequenceId: number;
1761
+ /** Trade ID */
1762
+ id: string;
1763
+ }
1764
+ /**
1765
+ * Order processed (WebSocket)
1766
+ */
1767
+ interface OrderProcessed extends BaseWebSocketMessage {
1768
+ type: 'ORDER_PROCESSED';
1769
+ /** Order ID */
1770
+ orderId: OrderId;
1771
+ /** Success flag */
1772
+ success: boolean;
1773
+ /** Failure reason (if failed) */
1774
+ failureReason?: string;
1775
+ }
1776
+ /**
1777
+ * Order status update (WebSocket)
1778
+ */
1779
+ interface OrderStatusUpdate extends BaseWebSocketMessage {
1780
+ type: 'ORDER_STATUS_UPDATE';
1781
+ /** Order ID */
1782
+ orderId: OrderId;
1783
+ /** Order status */
1784
+ orderStatus: OrderStatus;
1785
+ /** Currency pair */
1786
+ currencyPair: CurrencyPair;
1787
+ /** Remaining quantity */
1788
+ remainingQuantity: string;
1789
+ /** Original quantity */
1790
+ originalQuantity: string;
1791
+ /** Customer order ID */
1792
+ customerOrderId?: CustomerOrderId;
1793
+ }
1794
+ /**
1795
+ * Balance update (WebSocket)
1796
+ */
1797
+ interface BalanceUpdate extends BaseWebSocketMessage {
1798
+ type: 'BALANCE_UPDATE';
1799
+ /** Currency */
1800
+ currency: string;
1801
+ /** Available balance */
1802
+ available: string;
1803
+ /** Reserved balance */
1804
+ reserved: string;
1805
+ /** Total balance */
1806
+ total: string;
1807
+ }
1808
+ /**
1809
+ * Account trade (WebSocket)
1810
+ */
1811
+ interface AccountTrade extends BaseWebSocketMessage {
1812
+ type: 'NEW_ACCOUNT_TRADE';
1813
+ /** Currency pair */
1814
+ currencyPair: CurrencyPair;
1815
+ /** Price */
1816
+ price: string;
1817
+ /** Quantity */
1818
+ quantity: string;
1819
+ /** Side */
1820
+ side: OrderSide;
1821
+ /** Order ID */
1822
+ orderId: OrderId;
1823
+ /** Trade ID */
1824
+ id: string;
1825
+ /** Traded at */
1826
+ tradedAt: ISOTimestamp;
1827
+ }
1828
+ /**
1829
+ * Union of all WebSocket message types
1830
+ */
1831
+ type WebSocketMessage = BaseWebSocketMessage | OrderBookUpdate | MarketSummaryUpdate | NewTrade | OrderProcessed | OrderStatusUpdate | BalanceUpdate | AccountTrade;
1832
+
1833
+ /**
1834
+ * Public API methods (no authentication required)
1835
+ */
1836
+ declare class PublicAPI {
1837
+ private http;
1838
+ constructor(http: HttpClient);
1839
+ /**
1840
+ * Get server time
1841
+ * GET /v1/public/time
1842
+ *
1843
+ * @returns Server time with Unix epoch and ISO timestamp
1844
+ */
1845
+ getServerTime(): Promise<ServerTime>;
1846
+ /**
1847
+ * Get VALR API status
1848
+ * GET /v1/public/status
1849
+ *
1850
+ * @returns Current API status
1851
+ */
1852
+ getStatus(): Promise<ValrStatus>;
1853
+ /**
1854
+ * Get list of currencies supported by VALR
1855
+ * GET /v1/public/currencies
1856
+ *
1857
+ * @returns Array of currency information
1858
+ */
1859
+ getCurrencies(): Promise<Currency[]>;
1860
+ /**
1861
+ * Get list of all currency pairs
1862
+ * GET /v1/public/pairs
1863
+ *
1864
+ * @returns Array of currency pair information
1865
+ */
1866
+ getCurrencyPairs(): Promise<CurrencyPairInfo[]>;
1867
+ /**
1868
+ * Get currency pairs by type (SPOT or FUTURES)
1869
+ * GET /v1/public/pairs/:type
1870
+ *
1871
+ * @param type - Pair type (SPOT or FUTURES)
1872
+ * @returns Array of currency pair information
1873
+ */
1874
+ getCurrencyPairsByType(type: PairType): Promise<CurrencyPairInfo[]>;
1875
+ /**
1876
+ * Get market summary for all pairs
1877
+ * GET /v1/public/marketsummary
1878
+ *
1879
+ * @returns Array of market summaries
1880
+ */
1881
+ getMarketSummary(): Promise<MarketSummary[]>;
1882
+ /**
1883
+ * Get market summary for a specific currency pair
1884
+ * GET /v1/public/:currencyPair/marketsummary
1885
+ *
1886
+ * @param pair - Currency pair (e.g., 'BTCZAR', 'ETHUSDC')
1887
+ * @returns Market summary for the pair
1888
+ */
1889
+ getMarketSummaryForPair(pair: CurrencyPair): Promise<MarketSummary>;
1890
+ /**
1891
+ * Get aggregated order book for a currency pair
1892
+ * GET /v1/public/:currencyPair/orderbook
1893
+ *
1894
+ * @param pair - Currency pair
1895
+ * @returns Aggregated order book
1896
+ */
1897
+ getOrderBook(pair: CurrencyPair): Promise<OrderBook>;
1898
+ /**
1899
+ * Get full (non-aggregated) order book for a currency pair
1900
+ * GET /v1/public/:currencyPair/orderbook/full
1901
+ *
1902
+ * @param pair - Currency pair
1903
+ * @returns Full order book with individual orders
1904
+ */
1905
+ getFullOrderBook(pair: CurrencyPair): Promise<OrderBook>;
1906
+ /**
1907
+ * Get recent trades for a currency pair
1908
+ * GET /v1/public/:currencyPair/trades
1909
+ *
1910
+ * @param pair - Currency pair
1911
+ * @param params - Query parameters (skip, limit, startTime, endTime, beforeId)
1912
+ * @returns Array of trades
1913
+ */
1914
+ getTradeHistory(pair: CurrencyPair, params?: TradeHistoryParams): Promise<Trade[]>;
1915
+ /**
1916
+ * Get supported order types for all currency pairs
1917
+ * GET /v1/public/ordertypes
1918
+ *
1919
+ * @param params - Query parameters (includeInactivePairs)
1920
+ * @returns Array of currency pairs with their supported order types
1921
+ */
1922
+ getOrderTypes(params?: OrderTypesParams): Promise<CurrencyPairOrderTypes[]>;
1923
+ /**
1924
+ * Get supported order types for a specific currency pair
1925
+ * GET /v1/public/:currencyPair/ordertypes
1926
+ *
1927
+ * @param pair - Currency pair
1928
+ * @returns Array of supported order type strings
1929
+ */
1930
+ getOrderTypesForPair(pair: CurrencyPair): Promise<string[]>;
1931
+ /**
1932
+ * Get OHLC price buckets for a currency pair
1933
+ * GET /v1/public/:currencyPair/buckets
1934
+ *
1935
+ * @param pair - Currency pair
1936
+ * @param params - Query parameters (periodSeconds, startTime, endTime, skip, limit, includeEmpty)
1937
+ * @returns Array of price buckets (OHLC data)
1938
+ */
1939
+ getPriceBuckets(pair: CurrencyPair, params: PriceBucketsParams): Promise<PriceBucket[]>;
1940
+ /**
1941
+ * Get mark price buckets for a futures currency pair
1942
+ * GET /v1/public/:currencyPair/markprice/buckets
1943
+ *
1944
+ * @param pair - Currency pair (futures)
1945
+ * @param params - Query parameters (periodSeconds, startTime, endTime, skip, limit, includeEmpty)
1946
+ * @returns Array of mark price buckets
1947
+ */
1948
+ getMarkPriceBuckets(pair: CurrencyPair, params: PriceBucketsParams): Promise<PriceBucket[]>;
1949
+ /**
1950
+ * Get futures contracts information
1951
+ * GET /v1/public/futures/info
1952
+ *
1953
+ * @returns Array of futures contract information
1954
+ */
1955
+ getFuturesInfo(): Promise<FuturesInfo[]>;
1956
+ /**
1957
+ * Get funding rate history for a futures pair
1958
+ * GET /v1/public/futures/funding/history
1959
+ *
1960
+ * @param pair - Futures currency pair
1961
+ * @returns Array of funding rate history
1962
+ */
1963
+ getFundingRateHistory(pair: CurrencyPair): Promise<FundingRateHistory[]>;
1964
+ /**
1965
+ * Get loan information for all currencies
1966
+ * GET /v1/public/loans/info
1967
+ *
1968
+ * @returns Array of loan information
1969
+ */
1970
+ getLoanInfo(): Promise<LoanInfo[]>;
1971
+ /**
1972
+ * Get available leverage options for a currency pair
1973
+ * GET /v1/public/risklimit/:currencypair
1974
+ *
1975
+ * @param pair - Currency pair
1976
+ * @returns Array of leverage options with risk limits
1977
+ */
1978
+ getAvailableLeverageOptions(pair: CurrencyPair): Promise<LeverageOption[]>;
1979
+ }
1980
+
1981
+ /**
1982
+ * Account API methods (requires authentication)
1983
+ */
1984
+ declare class AccountAPI {
1985
+ private http;
1986
+ constructor(http: HttpClient);
1987
+ /**
1988
+ * Get account balances for all currencies
1989
+ * GET /v1/account/balances
1990
+ *
1991
+ * @param params - Query parameters (excludeZeroBalances)
1992
+ * @returns Array of currency balances
1993
+ */
1994
+ getBalances(params?: BalancesParams): Promise<Balance[]>;
1995
+ /**
1996
+ * Get transaction history
1997
+ * GET /v1/account/transactionhistory
1998
+ *
1999
+ * @param params - Query parameters (skip, limit, beforeId, transactionTypes, currency, startTime, endTime)
2000
+ * @returns Array of transactions
2001
+ */
2002
+ getTransactionHistory(params?: TransactionHistoryParams): Promise<Transaction[]>;
2003
+ /**
2004
+ * Get trade history for all currency pairs
2005
+ * GET /v1/account/tradehistory
2006
+ *
2007
+ * @param params - Query parameters (skip, limit)
2008
+ * @returns Array of account trades
2009
+ */
2010
+ getTradeHistory(params?: TradeHistoryParams): Promise<AccountTrade$1[]>;
2011
+ /**
2012
+ * Get trade history for a specific currency pair
2013
+ * GET /v1/account/:currencyPair/tradehistory
2014
+ *
2015
+ * @param pair - Currency pair
2016
+ * @param params - Query parameters (skip, limit)
2017
+ * @returns Array of account trades for the pair
2018
+ */
2019
+ getTradeHistoryForPair(pair: CurrencyPair, params?: TradeHistoryParams): Promise<AccountTrade$1[]>;
2020
+ /**
2021
+ * Get trading fees for all currency pairs
2022
+ * GET /v1/account/fees/trade
2023
+ *
2024
+ * @returns Array of trading fees per currency pair
2025
+ */
2026
+ getTradeFees(): Promise<TradeFee[]>;
2027
+ /**
2028
+ * Get list of subaccounts
2029
+ * GET /v1/account/subaccounts
2030
+ *
2031
+ * @returns Array of subaccounts
2032
+ */
2033
+ getSubaccounts(): Promise<Subaccount[]>;
2034
+ /**
2035
+ * Create a new subaccount
2036
+ * POST /v1/account/subaccount
2037
+ *
2038
+ * @param request - Subaccount creation request
2039
+ * @returns Created subaccount
2040
+ */
2041
+ createSubaccount(request: CreateSubaccountRequest): Promise<Subaccount>;
2042
+ /**
2043
+ * Transfer funds between primary account and subaccounts
2044
+ * POST /v1/account/subaccount/transfer
2045
+ *
2046
+ * @param request - Transfer request
2047
+ * @returns Transfer confirmation
2048
+ */
2049
+ transferBetweenAccounts(request: TransferRequest): Promise<{
2050
+ success: boolean;
2051
+ }>;
2052
+ /**
2053
+ * Get list of API keys
2054
+ * GET /v1/account/api-keys
2055
+ *
2056
+ * @returns Array of API keys
2057
+ */
2058
+ getApiKeys(): Promise<ApiKey[]>;
2059
+ /**
2060
+ * Create a new API key
2061
+ * POST /v1/account/api-keys
2062
+ *
2063
+ * @param request - API key creation request
2064
+ * @returns Created API key with secret (SAVE THE SECRET - only returned once!)
2065
+ */
2066
+ createApiKey(request: CreateApiKeyRequest): Promise<CreateApiKeyResponse>;
2067
+ /**
2068
+ * Delete an API key
2069
+ * DELETE /v1/account/api-keys/:keyId
2070
+ *
2071
+ * @param keyId - API key ID to delete
2072
+ * @returns Deletion confirmation
2073
+ */
2074
+ deleteApiKey(keyId: string): Promise<{
2075
+ success: boolean;
2076
+ }>;
2077
+ }
2078
+
2079
+ /**
2080
+ * Trading API methods (requires authentication with trade permission)
2081
+ */
2082
+ declare class TradingAPI {
2083
+ private http;
2084
+ constructor(http: HttpClient);
2085
+ /**
2086
+ * Place a limit order (v1)
2087
+ * POST /v1/orders/limit
2088
+ *
2089
+ * @param request - Limit order request
2090
+ * @returns Order response with order ID
2091
+ */
2092
+ placeLimitOrder(request: LimitOrderRequest): Promise<OrderResponse>;
2093
+ /**
2094
+ * Place a limit order (v2) - supports baseAmount or quoteAmount
2095
+ * POST /v2/orders/limit
2096
+ *
2097
+ * @param request - Limit order request (v2)
2098
+ * @returns Order response with order ID
2099
+ */
2100
+ placeLimitOrderV2(request: LimitOrderRequestV2): Promise<OrderResponse>;
2101
+ /**
2102
+ * Place a market order (v1)
2103
+ * POST /v1/orders/market
2104
+ *
2105
+ * @param request - Market order request
2106
+ * @returns Order response with order ID
2107
+ */
2108
+ placeMarketOrder(request: MarketOrderRequest): Promise<OrderResponse>;
2109
+ /**
2110
+ * Place a market order (v2)
2111
+ * POST /v2/orders/market
2112
+ *
2113
+ * @param request - Market order request (v2)
2114
+ * @returns Order response with order ID
2115
+ */
2116
+ placeMarketOrderV2(request: MarketOrderRequestV2): Promise<OrderResponse>;
2117
+ /**
2118
+ * Place a stop-limit order (v1)
2119
+ * POST /v1/orders/stop/limit
2120
+ *
2121
+ * @param request - Stop-limit order request
2122
+ * @returns Order response with order ID
2123
+ */
2124
+ placeStopLimitOrder(request: StopLimitOrderRequest): Promise<OrderResponse>;
2125
+ /**
2126
+ * Place a stop-limit order (v2)
2127
+ * POST /v2/orders/stop/limit
2128
+ *
2129
+ * @param request - Stop-limit order request (v2)
2130
+ * @returns Order response with order ID
2131
+ */
2132
+ placeStopLimitOrderV2(request: StopLimitOrderRequestV2): Promise<OrderResponse>;
2133
+ /**
2134
+ * Place batch orders (up to 10 orders in a single request)
2135
+ * POST /v1/batch/orders
2136
+ *
2137
+ * @param request - Batch order request
2138
+ * @returns Array of order responses
2139
+ */
2140
+ placeBatchOrders(request: BatchOrderRequest): Promise<BatchOrderResponse>;
2141
+ /**
2142
+ * Place a conditional order (stop-loss or take-profit)
2143
+ * POST /v1/orders/conditionals
2144
+ *
2145
+ * @param request - Conditional order request
2146
+ * @returns Conditional order response
2147
+ */
2148
+ placeConditionalOrder(request: ConditionalOrderRequest): Promise<ConditionalOrderResponse>;
2149
+ /**
2150
+ * Get all conditional orders
2151
+ * GET /v1/orders/conditionals
2152
+ *
2153
+ * @returns Array of conditional orders
2154
+ */
2155
+ getAllConditionalOrders(): Promise<ConditionalOrderStatus[]>;
2156
+ /**
2157
+ * Get conditional order status by ID
2158
+ * GET /v1/orders/conditionals/conditional/:currencyPair/orderid/:orderId
2159
+ *
2160
+ * @param pair - Currency pair
2161
+ * @param orderId - Conditional order ID
2162
+ * @returns Conditional order status
2163
+ */
2164
+ getConditionalOrderStatus(pair: CurrencyPair, orderId: string): Promise<ConditionalOrderStatus>;
2165
+ /**
2166
+ * Get conditional order history for a currency pair
2167
+ * GET /v1/orders/conditionals/:currencyPair/history
2168
+ *
2169
+ * @param pair - Currency pair
2170
+ * @returns Array of historical conditional orders
2171
+ */
2172
+ getConditionalOrderHistory(pair: CurrencyPair): Promise<ConditionalOrderStatus[]>;
2173
+ /**
2174
+ * Modify a conditional order
2175
+ * PUT /v1/orders/conditionals/modify
2176
+ *
2177
+ * @param request - Conditional order modification request
2178
+ * @returns Updated conditional order
2179
+ */
2180
+ modifyConditionalOrder(request: ConditionalOrderRequest & {
2181
+ id: string;
2182
+ }): Promise<ConditionalOrderResponse>;
2183
+ /**
2184
+ * Get a quote for simple buy/sell
2185
+ * POST /v1/simple/:currencyPair/quote
2186
+ *
2187
+ * @param pair - Currency pair
2188
+ * @param request - Quote request
2189
+ * @returns Quote with ID (valid for 5 seconds)
2190
+ */
2191
+ getSimpleQuote(pair: CurrencyPair, request: SimpleQuoteRequest): Promise<SimpleQuoteResponse>;
2192
+ /**
2193
+ * Place a simple buy/sell order using a quote
2194
+ * POST /v1/simple/:currencyPair/order
2195
+ *
2196
+ * @param pair - Currency pair
2197
+ * @param request - Simple order request with quote ID
2198
+ * @returns Order response
2199
+ */
2200
+ placeSimpleOrder(pair: CurrencyPair, request: SimpleOrderRequest): Promise<OrderResponse>;
2201
+ /**
2202
+ * Get simple order status
2203
+ * GET /v1/simple/:currencyPair/order/:orderId
2204
+ *
2205
+ * @param pair - Currency pair
2206
+ * @param orderId - Order ID
2207
+ * @returns Order status
2208
+ */
2209
+ getSimpleOrderStatus(pair: CurrencyPair, orderId: OrderId): Promise<OrderStatusSummary>;
2210
+ /**
2211
+ * Get order status by order ID
2212
+ * GET /v1/orders/:currencyPair/orderid/:orderId
2213
+ *
2214
+ * @param pair - Currency pair
2215
+ * @param orderId - Order ID
2216
+ * @returns Order status summary
2217
+ */
2218
+ getOrderStatus(pair: CurrencyPair, orderId: OrderId): Promise<OrderStatusSummary>;
2219
+ /**
2220
+ * Get order status by customer order ID
2221
+ * GET /v1/orders/:currencyPair/customerorderid/:customerOrderId
2222
+ *
2223
+ * @param pair - Currency pair
2224
+ * @param customerOrderId - Customer order ID
2225
+ * @returns Order status summary
2226
+ */
2227
+ getOrderStatusByCustomerId(pair: CurrencyPair, customerOrderId: CustomerOrderId): Promise<OrderStatusSummary>;
2228
+ /**
2229
+ * Get all open orders
2230
+ * GET /v1/orders/open
2231
+ *
2232
+ * @returns Array of open orders
2233
+ */
2234
+ getAllOpenOrders(): Promise<OpenOrder[]>;
2235
+ /**
2236
+ * Get order history
2237
+ * GET /v1/orders/history
2238
+ *
2239
+ * @param params - Query parameters (skip, limit, statuses, currencyPair, startTime, endTime)
2240
+ * @returns Array of historical order summaries
2241
+ */
2242
+ getOrderHistory(params?: OrderHistoryParams): Promise<HistoricalOrderSummary[]>;
2243
+ /**
2244
+ * Get order history summary by order ID
2245
+ * GET /v1/orders/history/summary/orderid/:orderId
2246
+ *
2247
+ * @param orderId - Order ID
2248
+ * @returns Order history summary
2249
+ */
2250
+ getOrderHistorySummary(orderId: OrderId): Promise<HistoricalOrderSummary>;
2251
+ /**
2252
+ * Get order history summary by customer order ID
2253
+ * GET /v1/orders/history/summary/customerorderid/:customerOrderId
2254
+ *
2255
+ * @param customerOrderId - Customer order ID
2256
+ * @returns Order history summary
2257
+ */
2258
+ getOrderHistorySummaryByCustomerId(customerOrderId: CustomerOrderId): Promise<HistoricalOrderSummary>;
2259
+ /**
2260
+ * Get order history detail by order ID (includes all trades)
2261
+ * GET /v1/orders/history/detail/orderid/:orderId
2262
+ *
2263
+ * @param orderId - Order ID
2264
+ * @returns Order history detail with trades
2265
+ */
2266
+ getOrderHistoryDetail(orderId: OrderId): Promise<HistoricalOrderDetail>;
2267
+ /**
2268
+ * Get order history detail by customer order ID
2269
+ * GET /v1/orders/history/detail/customerorderid/:customerOrderId
2270
+ *
2271
+ * @param customerOrderId - Customer order ID
2272
+ * @returns Order history detail with trades
2273
+ */
2274
+ getOrderHistoryDetailByCustomerId(customerOrderId: CustomerOrderId): Promise<HistoricalOrderDetail>;
2275
+ /**
2276
+ * Modify an existing order (v1)
2277
+ * PUT /v1/orders/modify
2278
+ *
2279
+ * @param request - Modify order request
2280
+ * @returns Updated order response
2281
+ */
2282
+ modifyOrder(request: ModifyOrderRequest): Promise<OrderResponse>;
2283
+ /**
2284
+ * Modify an existing order (v2)
2285
+ * PUT /v2/orders/modify
2286
+ *
2287
+ * @param request - Modify order request (v2)
2288
+ * @returns Updated order response
2289
+ */
2290
+ modifyOrderV2(request: ModifyOrderRequestV2): Promise<OrderResponse>;
2291
+ /**
2292
+ * Cancel a single order (v1)
2293
+ * DELETE /v1/orders/order
2294
+ *
2295
+ * @param request - Cancel order request
2296
+ * @returns Cancellation confirmation
2297
+ */
2298
+ cancelOrder(request: CancelOrderRequest): Promise<OrderResponse>;
2299
+ /**
2300
+ * Cancel a single order (v2)
2301
+ * DELETE /v2/orders/order
2302
+ *
2303
+ * @param request - Cancel order request (v2)
2304
+ * @returns Cancellation confirmation
2305
+ */
2306
+ cancelOrderV2(request: CancelOrderRequestV2): Promise<OrderResponse>;
2307
+ /**
2308
+ * Cancel all conditional orders
2309
+ * DELETE /v1/orders/conditionals
2310
+ *
2311
+ * @returns Cancellation confirmation
2312
+ */
2313
+ cancelAllConditionalOrders(): Promise<{
2314
+ message: string;
2315
+ }>;
2316
+ /**
2317
+ * Cancel all conditional orders for a currency pair
2318
+ * DELETE /v1/orders/conditionals/:currencypair
2319
+ *
2320
+ * @param pair - Currency pair
2321
+ * @returns Cancellation confirmation
2322
+ */
2323
+ cancelConditionalOrdersForPair(pair: CurrencyPair): Promise<{
2324
+ message: string;
2325
+ }>;
2326
+ /**
2327
+ * Cancel a specific conditional order
2328
+ * DELETE /v1/orders/conditionals/conditional
2329
+ *
2330
+ * @param request - Contains orderId and currencyPair
2331
+ * @returns Cancellation confirmation
2332
+ */
2333
+ cancelConditionalOrder(request: {
2334
+ orderId: string;
2335
+ pair: CurrencyPair;
2336
+ }): Promise<{
2337
+ message: string;
2338
+ }>;
2339
+ /**
2340
+ * Cancel all orders for all currency pairs
2341
+ * DELETE /v1/orders
2342
+ *
2343
+ * @returns Cancellation confirmation
2344
+ */
2345
+ cancelAllOrders(): Promise<{
2346
+ message: string;
2347
+ }>;
2348
+ /**
2349
+ * Cancel all orders for a specific currency pair
2350
+ * DELETE /v1/orders/:currencyPair
2351
+ *
2352
+ * @param pair - Currency pair
2353
+ * @returns Cancellation confirmation
2354
+ */
2355
+ cancelAllOrdersForPair(pair: CurrencyPair): Promise<{
2356
+ message: string;
2357
+ }>;
2358
+ }
2359
+
2360
+ /**
2361
+ * Wallets API methods (requires authentication)
2362
+ */
2363
+ declare class WalletsAPI {
2364
+ private http;
2365
+ constructor(http: HttpClient);
2366
+ getCryptoDepositAddress(currency: CurrencyCode, networkType?: string): Promise<DepositAddress>;
2367
+ withdrawCrypto(request: CryptoWithdrawalRequest): Promise<CryptoWithdrawalResponse>;
2368
+ getCryptoWithdrawalStatus(currency: CurrencyCode, withdrawalId: string): Promise<CryptoWithdrawalStatus>;
2369
+ getBankAccounts(currency: CurrencyCode): Promise<BankAccount[]>;
2370
+ linkBankAccount(currency: CurrencyCode, request: LinkBankAccountRequest): Promise<BankAccount>;
2371
+ withdrawFiat(request: FiatWithdrawalRequest): Promise<FiatWithdrawalResponse>;
2372
+ getFiatDepositReference(currency: CurrencyCode): Promise<FiatDepositReference>;
2373
+ }
2374
+
2375
+ /**
2376
+ * Futures API methods (requires authentication)
2377
+ */
2378
+ declare class FuturesAPI {
2379
+ private http;
2380
+ constructor(http: HttpClient);
2381
+ getOpenPositions(): Promise<FuturesPosition[]>;
2382
+ getClosedPositionsSummary(): Promise<ClosedPositionSummary[]>;
2383
+ getClosedPositions(pair: CurrencyPair): Promise<ClosedPosition[]>;
2384
+ getPositionHistory(params: PositionHistoryParams): Promise<FuturesPosition[]>;
2385
+ getFundingHistory(params: FundingHistoryParams): Promise<FundingPayment[]>;
2386
+ getLeverageInfo(pair: CurrencyPair): Promise<LeverageInfo>;
2387
+ updateLeverage(pair: CurrencyPair, request: UpdateLeverageRequest): Promise<LeverageInfo>;
2388
+ }
2389
+
2390
+ /**
2391
+ * Margin API methods (requires authentication)
2392
+ */
2393
+ declare class MarginAPI {
2394
+ private http;
2395
+ constructor(http: HttpClient);
2396
+ getMarginStatus(): Promise<MarginStatus>;
2397
+ enableMargin(request: EnableMarginRequest): Promise<MarginStatus>;
2398
+ }
2399
+
2400
+ /**
2401
+ * Loans API methods (requires authentication)
2402
+ *
2403
+ * VALR's lending platform allows users to lend crypto and earn interest.
2404
+ * Interest rates are determined through an hourly auction system.
2405
+ */
2406
+ declare class LoansAPI {
2407
+ private http;
2408
+ constructor(http: HttpClient);
2409
+ /**
2410
+ * Get current loan rates for all currencies
2411
+ *
2412
+ * Returns interest rate information including:
2413
+ * - Previous funding rate from the most recent interest auction
2414
+ * - Estimated rate for the next funding period
2415
+ * - Estimated borrow rate for the next funding round
2416
+ *
2417
+ * @returns Promise resolving to array of loan rates
2418
+ *
2419
+ * @example
2420
+ * ```typescript
2421
+ * const rates = await client.loans.getRates();
2422
+ * rates.forEach(rate => {
2423
+ * console.log(`${rate.currency}: ${rate.estimatedNextRate}`);
2424
+ * });
2425
+ * ```
2426
+ */
2427
+ getRates(): Promise<LoanRate[]>;
2428
+ /**
2429
+ * Get historical loan rates
2430
+ *
2431
+ * @returns Promise resolving to array of historical loan rates
2432
+ *
2433
+ * @example
2434
+ * ```typescript
2435
+ * const history = await client.loans.getRatesHistory();
2436
+ * ```
2437
+ */
2438
+ getRatesHistory(): Promise<LoanRate[]>;
2439
+ /**
2440
+ * Get all open loans
2441
+ *
2442
+ * @returns Promise resolving to array of open loans
2443
+ *
2444
+ * @example
2445
+ * ```typescript
2446
+ * const openLoans = await client.loans.getOpenLoans();
2447
+ * openLoans.forEach(loan => {
2448
+ * console.log(`${loan.currency}: ${loan.totalAmount} at ${loan.hourlyRate}/hr`);
2449
+ * });
2450
+ * ```
2451
+ */
2452
+ getOpenLoans(): Promise<OpenLoan[]>;
2453
+ /**
2454
+ * Create a new loan
2455
+ *
2456
+ * Opens a new lending position at the specified hourly rate.
2457
+ *
2458
+ * @param request - Loan creation parameters
2459
+ * @returns Promise that resolves when loan is created
2460
+ *
2461
+ * @example
2462
+ * ```typescript
2463
+ * await client.loans.createLoan({
2464
+ * currencySymbol: 'USDC',
2465
+ * hourlyRate: '0.00001255',
2466
+ * amount: '100'
2467
+ * });
2468
+ * ```
2469
+ */
2470
+ createLoan(request: CreateLoanRequest): Promise<void>;
2471
+ /**
2472
+ * Get loan credit history
2473
+ *
2474
+ * Returns history of interest entries as calculated during margin interest auction runs.
2475
+ *
2476
+ * @returns Promise resolving to array of credit history items
2477
+ *
2478
+ * @example
2479
+ * ```typescript
2480
+ * const history = await client.loans.getCreditHistory();
2481
+ * history.forEach(item => {
2482
+ * console.log(`${item.currency}: earned ${item.interestAmount}`);
2483
+ * });
2484
+ * ```
2485
+ */
2486
+ getCreditHistory(): Promise<LoanCreditHistoryItem[]>;
2487
+ /**
2488
+ * Increase loan amount
2489
+ *
2490
+ * Increases the total amount of an existing loan.
2491
+ *
2492
+ * @param request - Increase loan parameters
2493
+ * @returns Promise that resolves when loan is increased
2494
+ *
2495
+ * @example
2496
+ * ```typescript
2497
+ * await client.loans.increaseLoan({
2498
+ * currencySymbol: 'USDC',
2499
+ * increaseLoanAmountBy: '20',
2500
+ * loanId: '1289055810346737664'
2501
+ * });
2502
+ * ```
2503
+ */
2504
+ increaseLoan(request: IncreaseLoanRequest): Promise<void>;
2505
+ /**
2506
+ * Change loan rate
2507
+ *
2508
+ * Updates the hourly interest rate for an existing loan.
2509
+ *
2510
+ * @param request - Change rate parameters
2511
+ * @returns Promise that resolves when rate is changed
2512
+ *
2513
+ * @example
2514
+ * ```typescript
2515
+ * await client.loans.changeRate({
2516
+ * currencySymbol: 'USDC',
2517
+ * hourlyRate: '0.0000126',
2518
+ * loanId: '1289055810346737664'
2519
+ * });
2520
+ * ```
2521
+ */
2522
+ changeRate(request: ChangeLoanRateRequest): Promise<void>;
2523
+ /**
2524
+ * Get loan update history
2525
+ *
2526
+ * Returns history of loan modifications (rate changes, amount increases, etc).
2527
+ *
2528
+ * @returns Promise resolving to array of loan updates
2529
+ *
2530
+ * @example
2531
+ * ```typescript
2532
+ * const updates = await client.loans.getUpdateHistory();
2533
+ * ```
2534
+ */
2535
+ getUpdateHistory(): Promise<any[]>;
2536
+ /**
2537
+ * Request to unlock loan funds
2538
+ *
2539
+ * Requests to unlock a portion of a loan to make it available for withdrawal.
2540
+ *
2541
+ * @param request - Unlock request parameters
2542
+ * @returns Promise that resolves when unlock is requested
2543
+ *
2544
+ * @example
2545
+ * ```typescript
2546
+ * await client.loans.requestUnlock({
2547
+ * currencySymbol: 'USDC',
2548
+ * unlockAmount: '50',
2549
+ * loanId: '1289055810346737664'
2550
+ * });
2551
+ * ```
2552
+ */
2553
+ requestUnlock(request: RequestUnlockRequest): Promise<void>;
2554
+ /**
2555
+ * Cancel unlock request
2556
+ *
2557
+ * Cancels a pending unlock request for loan funds.
2558
+ *
2559
+ * @returns Promise that resolves when unlock request is cancelled
2560
+ *
2561
+ * @example
2562
+ * ```typescript
2563
+ * await client.loans.cancelUnlock();
2564
+ * ```
2565
+ */
2566
+ cancelUnlock(): Promise<void>;
2567
+ /**
2568
+ * Get borrow history for a specific currency
2569
+ *
2570
+ * @param currencySymbol - Currency symbol to get borrow history for
2571
+ * @returns Promise resolving to array of borrow history items
2572
+ *
2573
+ * @example
2574
+ * ```typescript
2575
+ * const history = await client.loans.getBorrowHistory('USDC');
2576
+ * ```
2577
+ */
2578
+ getBorrowHistory(currencySymbol: CurrencyCode): Promise<BorrowHistoryItem[]>;
2579
+ }
2580
+
2581
+ /**
2582
+ * Staking API methods - Staking and Lending (requires authentication)
2583
+ *
2584
+ * VALR offers two types of earning opportunities:
2585
+ * - STAKE: Lock crypto to earn rewards
2586
+ * - LEND: Lend crypto to earn interest
2587
+ */
2588
+ declare class StakeAPI {
2589
+ private http;
2590
+ constructor(http: HttpClient);
2591
+ /**
2592
+ * Stake/Lock cryptocurrency to earn rewards
2593
+ *
2594
+ * @param request - Stake request with currency, amount, and earn type
2595
+ * @returns Promise that resolves when stake is successful
2596
+ *
2597
+ * @example
2598
+ * ```typescript
2599
+ * await client.stake.stake({
2600
+ * currencySymbol: 'ETH',
2601
+ * amount: '1.5',
2602
+ * earnType: 'STAKE'
2603
+ * });
2604
+ * ```
2605
+ */
2606
+ stake(request: StakeRequest): Promise<void>;
2607
+ /**
2608
+ * Unstake/Unlock cryptocurrency
2609
+ *
2610
+ * @param request - Unstake request with currency, amount, and earn type
2611
+ * @returns Promise that resolves when unstake is successful
2612
+ *
2613
+ * @example
2614
+ * ```typescript
2615
+ * await client.stake.unstake({
2616
+ * currencySymbol: 'ETH',
2617
+ * amount: '1.5',
2618
+ * earnType: 'STAKE'
2619
+ * });
2620
+ * ```
2621
+ */
2622
+ unstake(request: UnstakeRequest): Promise<void>;
2623
+ /**
2624
+ * Get earn balances for a specific earn type
2625
+ *
2626
+ * @param params - Optional parameters (earnType filter)
2627
+ * @returns Promise resolving to array of earn balances
2628
+ *
2629
+ * @example
2630
+ * ```typescript
2631
+ * // Get staking balances
2632
+ * const stakingBalances = await client.stake.getBalances({ earnType: 'STAKE' });
2633
+ *
2634
+ * // Get lending balances
2635
+ * const lendingBalances = await client.stake.getBalances({ earnType: 'LEND' });
2636
+ * ```
2637
+ */
2638
+ getBalances(params?: EarnBalancesParams): Promise<EarnBalance[]>;
2639
+ /**
2640
+ * Get all earn balances
2641
+ *
2642
+ * @param params - Optional parameters (earnType filter)
2643
+ * @returns Promise resolving to array of all earn balances
2644
+ *
2645
+ * @example
2646
+ * ```typescript
2647
+ * const allBalances = await client.stake.getAllBalances({ earnType: 'LEND' });
2648
+ * ```
2649
+ */
2650
+ getAllBalances(params?: EarnBalancesParams): Promise<EarnBalance[]>;
2651
+ /**
2652
+ * Get current earning rates for available currencies
2653
+ *
2654
+ * @param params - Optional parameters (earnType filter)
2655
+ * @returns Promise resolving to array of earn rates
2656
+ *
2657
+ * @example
2658
+ * ```typescript
2659
+ * // Get staking rates
2660
+ * const stakingRates = await client.stake.getRates({ earnType: 'STAKE' });
2661
+ *
2662
+ * // Get lending rates
2663
+ * const lendingRates = await client.stake.getRates({ earnType: 'LEND' });
2664
+ * ```
2665
+ */
2666
+ getRates(params?: EarnRatesParams): Promise<EarnRate[]>;
2667
+ /**
2668
+ * Get earn rewards history for a specific currency
2669
+ *
2670
+ * @param params - Query parameters including currency symbol
2671
+ * @returns Promise resolving to array of earn rewards
2672
+ *
2673
+ * @example
2674
+ * ```typescript
2675
+ * const rewards = await client.stake.getRewards({
2676
+ * currencySymbol: 'ETH',
2677
+ * earnType: 'LEND',
2678
+ * skip: 0,
2679
+ * limit: 100
2680
+ * });
2681
+ * ```
2682
+ */
2683
+ getRewards(params: EarnRewardsParams): Promise<EarnReward[]>;
2684
+ /**
2685
+ * Get earn transaction history (stakes and unstakes)
2686
+ *
2687
+ * @param params - Query parameters including currency symbol
2688
+ * @returns Promise resolving to array of earn history items
2689
+ *
2690
+ * @example
2691
+ * ```typescript
2692
+ * const history = await client.stake.getHistory({
2693
+ * currencySymbol: 'ETH',
2694
+ * earnType: 'STAKE',
2695
+ * skip: 0,
2696
+ * limit: 100
2697
+ * });
2698
+ * ```
2699
+ */
2700
+ getHistory(params: EarnHistoryParams): Promise<EarnHistoryItem[]>;
2701
+ }
2702
+
2703
+ /**
2704
+ * Pay API methods (requires authentication)
2705
+ */
2706
+ declare class PayAPI {
2707
+ private http;
2708
+ constructor(http: HttpClient);
2709
+ createPayment(request: CreatePaymentRequest): Promise<Payment>;
2710
+ getPaymentStatus(paymentId: string): Promise<PaymentStatus>;
2711
+ }
2712
+
2713
+ /**
2714
+ * Bundles API methods (requires authentication)
2715
+ */
2716
+ declare class BundlesAPI {
2717
+ private http;
2718
+ constructor(http: HttpClient);
2719
+ getBundles(): Promise<Bundle[]>;
2720
+ buyBundle(request: BuyBundleRequest): Promise<BundleOrder>;
2721
+ }
2722
+
2723
+ /**
2724
+ * Health API methods
2725
+ */
2726
+ declare class HealthAPI {
2727
+ private http;
2728
+ constructor(http: HttpClient);
2729
+ getHealth(): Promise<ValrStatus>;
2730
+ }
2731
+
2732
+ /**
2733
+ * Configuration for ValrClient
2734
+ */
2735
+ interface ValrClientConfig {
2736
+ /**
2737
+ * API key (required for authenticated endpoints)
2738
+ */
2739
+ apiKey?: string;
2740
+ /**
2741
+ * API secret (required for authenticated endpoints)
2742
+ */
2743
+ apiSecret?: string;
2744
+ /**
2745
+ * Base URL for API (defaults to https://api.valr.com)
2746
+ */
2747
+ baseURL?: string;
2748
+ /**
2749
+ * Request timeout in milliseconds (defaults to 30000)
2750
+ */
2751
+ timeout?: number;
2752
+ /**
2753
+ * Subaccount ID for impersonating a subaccount (optional)
2754
+ */
2755
+ subaccountId?: string;
2756
+ }
2757
+ /**
2758
+ * Main VALR API client
2759
+ *
2760
+ * @example
2761
+ * ```typescript
2762
+ * // For public endpoints only (no authentication)
2763
+ * const client = new ValrClient();
2764
+ * const time = await client.public.getServerTime();
2765
+ *
2766
+ * // For authenticated endpoints
2767
+ * const client = new ValrClient({
2768
+ * apiKey: 'your-api-key',
2769
+ * apiSecret: 'your-api-secret',
2770
+ * });
2771
+ * const balances = await client.account.getBalances();
2772
+ * ```
2773
+ */
2774
+ declare class ValrClient {
2775
+ private http;
2776
+ private apiKey?;
2777
+ private apiSecret?;
2778
+ private subaccountId?;
2779
+ /**
2780
+ * Public API methods (no authentication required)
2781
+ */
2782
+ readonly public: PublicAPI;
2783
+ /**
2784
+ * Account API methods (requires authentication)
2785
+ */
2786
+ readonly account: AccountAPI;
2787
+ /**
2788
+ * Trading API methods (requires authentication with trade permission)
2789
+ */
2790
+ readonly trading: TradingAPI;
2791
+ /**
2792
+ * Wallets API methods (requires authentication)
2793
+ */
2794
+ readonly wallets: WalletsAPI;
2795
+ /**
2796
+ * Futures API methods (requires authentication)
2797
+ */
2798
+ readonly futures: FuturesAPI;
2799
+ /**
2800
+ * Margin API methods (requires authentication)
2801
+ */
2802
+ readonly margin: MarginAPI;
2803
+ /**
2804
+ * Loans API methods (requires authentication)
2805
+ */
2806
+ readonly loans: LoansAPI;
2807
+ /**
2808
+ * Staking/Earn API methods (requires authentication)
2809
+ */
2810
+ readonly stake: StakeAPI;
2811
+ /**
2812
+ * Pay API methods (requires authentication)
2813
+ */
2814
+ readonly pay: PayAPI;
2815
+ /**
2816
+ * Bundles API methods (requires authentication)
2817
+ */
2818
+ readonly bundles: BundlesAPI;
2819
+ /**
2820
+ * Health API methods
2821
+ */
2822
+ readonly health: HealthAPI;
2823
+ /**
2824
+ * Create a new VALR API client
2825
+ *
2826
+ * @param config - Client configuration
2827
+ */
2828
+ constructor(config?: ValrClientConfig);
2829
+ /**
2830
+ * Update subaccount ID for impersonation
2831
+ *
2832
+ * @param subaccountId - Subaccount ID (or undefined to clear)
2833
+ */
2834
+ setSubaccountId(subaccountId?: string): void;
2835
+ /**
2836
+ * Get current subaccount ID
2837
+ *
2838
+ * @returns Current subaccount ID or undefined
2839
+ */
2840
+ getSubaccountId(): string | undefined;
2841
+ }
2842
+
2843
+ /**
2844
+ * WebSocket client configuration
2845
+ */
2846
+ interface WebSocketClientConfig {
2847
+ /** API key (required for authenticated endpoints) */
2848
+ apiKey?: string;
2849
+ /** API secret (required for authenticated endpoints) */
2850
+ apiSecret?: string;
2851
+ /** Subaccount ID for impersonation */
2852
+ subaccountId?: string;
2853
+ /** Auto-reconnect on disconnect (default: true) */
2854
+ autoReconnect?: boolean;
2855
+ /** Reconnect delay in milliseconds (default: 5000) */
2856
+ reconnectDelay?: number;
2857
+ /** Maximum reconnect attempts (default: Infinity) */
2858
+ maxReconnectAttempts?: number;
2859
+ }
2860
+ /**
2861
+ * WebSocket event types
2862
+ */
2863
+ interface WebSocketEvents {
2864
+ connected: () => void;
2865
+ authenticated: () => void;
2866
+ message: (message: WebSocketMessage) => void;
2867
+ error: (error: Error) => void;
2868
+ close: (code: number, reason: string) => void;
2869
+ disconnected: () => void;
2870
+ reconnecting: (attempt: number) => void;
2871
+ }
2872
+ /**
2873
+ * Base WebSocket client for VALR API
2874
+ */
2875
+ declare abstract class ValrWebSocketClient<TEvents extends WebSocketEvents = WebSocketEvents> extends EventEmitter<TEvents> {
2876
+ protected ws?: WebSocket;
2877
+ protected url: string;
2878
+ protected config: Required<WebSocketClientConfig>;
2879
+ protected reconnectAttempts: number;
2880
+ protected reconnectTimer?: NodeJS.Timeout;
2881
+ protected isIntentionalClose: boolean;
2882
+ protected isConnected: boolean;
2883
+ protected isAuthenticated: boolean;
2884
+ constructor(url: string, config?: WebSocketClientConfig);
2885
+ /**
2886
+ * Connect to WebSocket
2887
+ */
2888
+ connect(): void;
2889
+ /**
2890
+ * Disconnect from WebSocket
2891
+ */
2892
+ disconnect(): void;
2893
+ /**
2894
+ * Check if connected
2895
+ */
2896
+ isOpen(): boolean;
2897
+ /**
2898
+ * Send a message to WebSocket
2899
+ */
2900
+ protected send(message: any): void;
2901
+ /**
2902
+ * Handle WebSocket open event
2903
+ */
2904
+ protected handleOpen(): void;
2905
+ /**
2906
+ * Authenticate WebSocket connection
2907
+ */
2908
+ protected authenticate(): void;
2909
+ /**
2910
+ * Handle incoming WebSocket message
2911
+ */
2912
+ protected handleMessage(data: WebSocket.Data): void;
2913
+ /**
2914
+ * Handle WebSocket error
2915
+ */
2916
+ protected handleError(error: Error): void;
2917
+ /**
2918
+ * Handle WebSocket close event
2919
+ */
2920
+ protected handleClose(code: number, reason: string): void;
2921
+ /**
2922
+ * Attempt to reconnect
2923
+ */
2924
+ protected attemptReconnect(): void;
2925
+ /**
2926
+ * Override this method to handle authenticated event
2927
+ */
2928
+ protected onAuthenticated(): void;
2929
+ /**
2930
+ * Override this method to handle messages
2931
+ */
2932
+ protected abstract onMessage(message: WebSocketMessage): void;
2933
+ }
2934
+
2935
+ /**
2936
+ * Account WebSocket events (in addition to base events)
2937
+ */
2938
+ interface AccountWebSocketEvents {
2939
+ 'order:processed': (data: OrderProcessed) => void;
2940
+ 'order:statusUpdate': (data: OrderStatusUpdate) => void;
2941
+ 'balance:update': (data: BalanceUpdate) => void;
2942
+ 'trade:new': (data: AccountTrade) => void;
2943
+ }
2944
+ /**
2945
+ * Combined event types for AccountWebSocket
2946
+ */
2947
+ type AccountWebSocketEventMap = WebSocketEvents & AccountWebSocketEvents;
2948
+ /**
2949
+ * Account WebSocket client for real-time account updates
2950
+ *
2951
+ * Receives:
2952
+ * - Order processing results
2953
+ * - Order status updates
2954
+ * - Balance changes
2955
+ * - Account trades
2956
+ *
2957
+ * @example
2958
+ * ```typescript
2959
+ * const wsClient = new AccountWebSocket({
2960
+ * apiKey: 'your-api-key',
2961
+ * apiSecret: 'your-api-secret',
2962
+ * });
2963
+ *
2964
+ * wsClient.on('connected', () => {
2965
+ * console.log('Connected to account WebSocket');
2966
+ * });
2967
+ *
2968
+ * wsClient.on('authenticated', () => {
2969
+ * console.log('Authenticated');
2970
+ * });
2971
+ *
2972
+ * wsClient.on('balance:update', (update) => {
2973
+ * console.log('Balance updated:', update);
2974
+ * });
2975
+ *
2976
+ * wsClient.on('order:processed', (result) => {
2977
+ * console.log('Order processed:', result);
2978
+ * });
2979
+ *
2980
+ * wsClient.connect();
2981
+ * ```
2982
+ */
2983
+ declare class AccountWebSocket extends ValrWebSocketClient<AccountWebSocketEventMap> {
2984
+ constructor(config: WebSocketClientConfig);
2985
+ /**
2986
+ * Subscribe to specific events
2987
+ *
2988
+ * @param subscriptions - Array of subscription objects
2989
+ */
2990
+ subscribe(subscriptions: Subscription[]): void;
2991
+ /**
2992
+ * Unsubscribe from specific events
2993
+ *
2994
+ * @param subscriptions - Array of subscription objects
2995
+ */
2996
+ unsubscribe(subscriptions: Subscription[]): void;
2997
+ /**
2998
+ * Handle authenticated event
2999
+ */
3000
+ protected onAuthenticated(): void;
3001
+ /**
3002
+ * Handle incoming messages
3003
+ */
3004
+ protected onMessage(message: WebSocketMessage): void;
3005
+ }
3006
+
3007
+ /**
3008
+ * Trade WebSocket events (in addition to base events)
3009
+ */
3010
+ interface TradeWebSocketEvents {
3011
+ 'orderbook:update': (data: OrderBookUpdate) => void;
3012
+ 'market:summary': (data: MarketSummaryUpdate) => void;
3013
+ 'trade:new': (data: NewTrade) => void;
3014
+ }
3015
+ /**
3016
+ * Combined event types for TradeWebSocket
3017
+ */
3018
+ type TradeWebSocketEventMap = WebSocketEvents & TradeWebSocketEvents;
3019
+ /**
3020
+ * Trade WebSocket client for real-time market data
3021
+ *
3022
+ * Receives:
3023
+ * - Order book updates (aggregated and full)
3024
+ * - Market summary updates
3025
+ * - New trades
3026
+ * - Price bucket updates
3027
+ *
3028
+ * @example
3029
+ * ```typescript
3030
+ * // Public trade WebSocket (no auth required)
3031
+ * const wsClient = new TradeWebSocket();
3032
+ *
3033
+ * wsClient.on('connected', () => {
3034
+ * console.log('Connected to trade WebSocket');
3035
+ * wsClient.subscribeToOrderBook(['BTCZAR', 'ETHZAR']);
3036
+ * wsClient.subscribeToTrades(['BTCZAR']);
3037
+ * });
3038
+ *
3039
+ * wsClient.on('orderbook:update', (update) => {
3040
+ * console.log('Order book update:', update);
3041
+ * });
3042
+ *
3043
+ * wsClient.on('trade:new', (trade) => {
3044
+ * console.log('New trade:', trade);
3045
+ * });
3046
+ *
3047
+ * wsClient.connect();
3048
+ * ```
3049
+ */
3050
+ declare class TradeWebSocket extends ValrWebSocketClient<TradeWebSocketEventMap> {
3051
+ constructor(config?: WebSocketClientConfig);
3052
+ /**
3053
+ * Subscribe to aggregated order book updates for currency pairs
3054
+ *
3055
+ * @param pairs - Array of currency pairs (e.g., ['BTCZAR', 'ETHZAR'])
3056
+ */
3057
+ subscribeToOrderBook(pairs: CurrencyPair[]): void;
3058
+ /**
3059
+ * Subscribe to full (non-aggregated) order book updates
3060
+ *
3061
+ * @param pairs - Array of currency pairs
3062
+ */
3063
+ subscribeToFullOrderBook(pairs: CurrencyPair[]): void;
3064
+ /**
3065
+ * Subscribe to market summary updates
3066
+ *
3067
+ * @param pairs - Array of currency pairs
3068
+ */
3069
+ subscribeToMarketSummary(pairs: CurrencyPair[]): void;
3070
+ /**
3071
+ * Subscribe to new trades
3072
+ *
3073
+ * @param pairs - Array of currency pairs
3074
+ */
3075
+ subscribeToTrades(pairs: CurrencyPair[]): void;
3076
+ /**
3077
+ * Subscribe to price bucket updates
3078
+ *
3079
+ * @param pairs - Array of currency pairs
3080
+ */
3081
+ subscribeToPriceBuckets(pairs: CurrencyPair[]): void;
3082
+ /**
3083
+ * Subscribe to specific events
3084
+ *
3085
+ * @param subscriptions - Array of subscription objects
3086
+ */
3087
+ subscribe(subscriptions: Subscription[]): void;
3088
+ /**
3089
+ * Unsubscribe from specific events
3090
+ *
3091
+ * @param subscriptions - Array of subscription objects
3092
+ */
3093
+ unsubscribe(subscriptions: Subscription[]): void;
3094
+ /**
3095
+ * Handle authenticated event (optional for trade WebSocket)
3096
+ */
3097
+ protected onAuthenticated(): void;
3098
+ /**
3099
+ * Handle incoming messages
3100
+ */
3101
+ protected onMessage(message: WebSocketMessage): void;
3102
+ }
3103
+
3104
+ /**
3105
+ * Base error class for all VALR API errors
3106
+ */
3107
+ declare class ValrError extends Error {
3108
+ constructor(message: string);
3109
+ }
3110
+ /**
3111
+ * Error thrown when API authentication fails
3112
+ */
3113
+ declare class ValrAuthenticationError extends ValrError {
3114
+ constructor(message?: string);
3115
+ }
3116
+ /**
3117
+ * Error thrown when API rate limit is exceeded
3118
+ */
3119
+ declare class ValrRateLimitError extends ValrError {
3120
+ constructor(message?: string);
3121
+ }
3122
+ /**
3123
+ * Error thrown when API request validation fails
3124
+ */
3125
+ declare class ValrValidationError extends ValrError {
3126
+ readonly errors?: Record<string, string[]>;
3127
+ constructor(message: string, errors?: Record<string, string[]>);
3128
+ }
3129
+ /**
3130
+ * Error thrown when API request fails due to network or server error
3131
+ */
3132
+ declare class ValrApiError extends ValrError {
3133
+ readonly statusCode?: number;
3134
+ readonly response?: unknown;
3135
+ constructor(message: string, statusCode?: number, response?: unknown);
3136
+ }
3137
+ /**
3138
+ * Error thrown when WebSocket connection fails
3139
+ */
3140
+ declare class ValrWebSocketError extends ValrError {
3141
+ constructor(message: string);
3142
+ }
3143
+ /**
3144
+ * Error thrown when required configuration is missing
3145
+ */
3146
+ declare class ValrConfigurationError extends ValrError {
3147
+ constructor(message: string);
3148
+ }
3149
+
3150
+ /**
3151
+ * Request signing configuration
3152
+ */
3153
+ interface SignRequestParams {
3154
+ /** API secret key for HMAC signing */
3155
+ apiSecret: string;
3156
+ /** Unix timestamp in milliseconds */
3157
+ timestamp: number;
3158
+ /** HTTP verb (GET, POST, PUT, DELETE, etc.) */
3159
+ verb: string;
3160
+ /** Request path (including query string, excluding host) */
3161
+ path: string;
3162
+ /** Request body as string (optional, empty string if no body) */
3163
+ body?: string;
3164
+ /** Subaccount ID (optional, for subaccount impersonation) */
3165
+ subaccountId?: string;
3166
+ }
3167
+ /**
3168
+ * Request signer for VALR API authentication
3169
+ * Implements HMAC SHA512 signature generation as per VALR API specification
3170
+ */
3171
+ declare class RequestSigner {
3172
+ /**
3173
+ * Generate HMAC SHA512 signature for VALR API request
3174
+ *
3175
+ * Signature is computed from concatenation of:
3176
+ * timestamp + verb + path + body + subaccountId
3177
+ *
3178
+ * @param params - Request signing parameters
3179
+ * @returns Hex-encoded HMAC SHA512 signature
3180
+ *
3181
+ * @example
3182
+ * ```typescript
3183
+ * const signature = RequestSigner.signRequest({
3184
+ * apiSecret: 'your-api-secret',
3185
+ * timestamp: Date.now(),
3186
+ * verb: 'GET',
3187
+ * path: '/v1/account/balances',
3188
+ * });
3189
+ * ```
3190
+ */
3191
+ static signRequest(params: SignRequestParams): string;
3192
+ /**
3193
+ * Get current timestamp in milliseconds
3194
+ *
3195
+ * @returns Unix timestamp in milliseconds
3196
+ */
3197
+ static getTimestamp(): number;
3198
+ /**
3199
+ * Validate API credentials
3200
+ *
3201
+ * @param apiKey - API key
3202
+ * @param apiSecret - API secret
3203
+ * @throws Error if credentials are invalid
3204
+ */
3205
+ static validateCredentials(apiKey: string, apiSecret: string): void;
3206
+ }
3207
+
3208
+ /**
3209
+ * VALR API constants
3210
+ */
3211
+ /**
3212
+ * Base URL for VALR API
3213
+ */
3214
+ declare const API_BASE_URL = "https://api.valr.com";
3215
+ /**
3216
+ * WebSocket URLs
3217
+ */
3218
+ declare const WS_ACCOUNT_URL = "wss://api.valr.com/ws/account";
3219
+ declare const WS_TRADE_URL = "wss://api.valr.com/ws/trade";
3220
+ /**
3221
+ * API rate limits
3222
+ */
3223
+ declare const RATE_LIMITS: {
3224
+ /** Global rate limit per API key */
3225
+ readonly PER_KEY_PER_MINUTE: 2000;
3226
+ /** Global rate limit per IP */
3227
+ readonly PER_IP_PER_MINUTE: 1200;
3228
+ /** WebSocket new connections per minute */
3229
+ readonly WS_CONNECTIONS_PER_MINUTE: 60;
3230
+ /** Specific endpoint limits (per second) */
3231
+ readonly ENDPOINTS: {
3232
+ readonly PUBLIC_TIME: 20;
3233
+ readonly PUBLIC_STATUS: 20;
3234
+ readonly PUBLIC_BUCKETS: 20;
3235
+ readonly BATCH_ORDERS: 400;
3236
+ readonly DELETE_ORDERS: 450;
3237
+ readonly POST_ORDERS: 400;
3238
+ readonly MODIFY_ORDERS: 400;
3239
+ readonly LOANS: 1;
3240
+ readonly CREATE_SUBACCOUNT: 1;
3241
+ readonly SUBACCOUNT_TRANSFER: 20;
3242
+ };
3243
+ };
3244
+ /**
3245
+ * HTTP request headers
3246
+ */
3247
+ declare const HEADERS: {
3248
+ readonly API_KEY: "X-VALR-API-KEY";
3249
+ readonly SIGNATURE: "X-VALR-SIGNATURE";
3250
+ readonly TIMESTAMP: "X-VALR-TIMESTAMP";
3251
+ readonly SUB_ACCOUNT_ID: "X-VALR-SUB-ACCOUNT-ID";
3252
+ readonly CONTENT_TYPE: "Content-Type";
3253
+ readonly RATE_LIMITED: "x-valr-ratelimited";
3254
+ };
3255
+
3256
+ export { API_BASE_URL, AccountAPI, type AccountTrade$1 as AccountTrade, AccountWebSocket, type ApiKey, type Balance, type BalanceUpdate, type BalancesParams, type BankAccount, type BaseOrderRequest, type BaseWebSocketMessage, type BatchOrderRequest, type BatchOrderResponse, type BatchOrderResponseItem, type BatchOrderStatus, type BorrowHistoryItem, type Bundle, type BundleComposition, type BundleOrder, BundlesAPI, type BuyBundleRequest, type CancelOrderRequest, type CancelOrderRequestV2, type ChangeLoanRateRequest, type ClosedPosition, type ClosedPositionSummary, type ConditionalOrderRequest, type ConditionalOrderResponse, type ConditionalOrderStatus, type ConditionalOrderTriggerType, type ConditionalOrderType, type CreateApiKeyRequest, type CreateApiKeyResponse, type CreateLoanRequest, type CreatePaymentRequest, type CreateSubaccountRequest, type CryptoAddress, type CryptoWithdrawalHistoryParams, type CryptoWithdrawalRequest, type CryptoWithdrawalResponse, type CryptoWithdrawalStatus, type Currency, type CurrencyCode, type CurrencyLeverageSettings, type CurrencyPair, type CurrencyPairInfo, type CurrencyPairOrderTypes, type CursorPaginationParams, type CustomerOrderId, type DepositAddress, type EarnBalance, type EarnBalancesParams, type EarnHistoryItem, type EarnHistoryParams, type EarnHistoryType, type EarnRate, type EarnRatesParams, type EarnReward, type EarnRewardsParams, type EarnType, type EnableMarginRequest, type FiatDepositReference, type FiatWithdrawalRequest, type FiatWithdrawalResponse, type FundingHistoryParams, type FundingPayment, type FundingRateHistory, FuturesAPI, type FuturesInfo, type FuturesPosition, HEADERS, HealthAPI, type HistoricalOrderDetail, type HistoricalOrderSummary, type ISOTimestamp, type IncreaseLoanRequest, type LeverageInfo, type LeverageOption, type LimitOrderRequest, type LimitOrderRequestV2, type LinkBankAccountRequest, type LoanCreditHistoryItem, type LoanInfo, type LoanRate, LoansAPI, MarginAPI, type MarginStatus, type MarketOrderRequest, type MarketOrderRequestV2, type MarketSummary, type MarketSummaryUpdate, type ModifyOrderRequest, type ModifyOrderRequestV2, type NetworkType, type NewTrade, type OpenLoan, type OpenOrder, type OrderBook, type OrderBookEntry$1 as OrderBookEntry, type OrderBookUpdate, type OrderHistoryParams, type OrderId, type OrderProcessed, type OrderResponse, type OrderSide, type OrderStatus, type OrderStatusDetail, type OrderStatusSummary, type OrderStatusUpdate, type OrderTrade, type OrderType, type OrderTypesParams, type PaginationParams, type PairType, PayAPI, type Payment, type PaymentStatus, type PositionHistoryParams, type PostOnly, type PriceBucket, type PriceBucketsParams, type PriceQuantity, PublicAPI, RATE_LIMITS, RequestSigner, type RequestUnlockRequest, type ServerTime, type SimpleOrderRequest, type SimpleQuoteRequest, type SimpleQuoteResponse, StakeAPI, type StakeRequest, type StopLimitOrderRequest, type StopLimitOrderRequestV2, type Subaccount, type SubaccountId, type Subscription, type SubscriptionRequest, type TimeInForce, type TimeRangeParams, type Trade, type TradeFee, type TradeHistoryParams, TradeWebSocket, TradingAPI, type Transaction, type TransactionHistoryParams, type TransactionType, type TransferRequest, type UnstakeRequest, type UpdateLeverageRequest, ValrApiError, ValrAuthenticationError, ValrClient, type ValrClientConfig, ValrConfigurationError, ValrError, ValrRateLimitError, type ValrStatus, ValrValidationError, ValrWebSocketError, WS_ACCOUNT_URL, WS_TRADE_URL, WalletsAPI, type AccountTrade as WebSocketAccountTrade, type WebSocketClientConfig, type WebSocketMessage, type WebSocketMessageType };