@arca-network/sdk 1.1.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.
- package/LICENSE +91 -0
- package/README.md +65 -0
- package/dist/admin.d.ts +159 -0
- package/dist/admin.d.ts.map +1 -0
- package/dist/admin.js +399 -0
- package/dist/admin.js.map +1 -0
- package/dist/arca.d.ts +1343 -0
- package/dist/arca.d.ts.map +1 -0
- package/dist/arca.js +3454 -0
- package/dist/arca.js.map +1 -0
- package/dist/cache.d.ts +29 -0
- package/dist/cache.d.ts.map +1 -0
- package/dist/cache.js +74 -0
- package/dist/cache.js.map +1 -0
- package/dist/candle-cdn.d.ts +17 -0
- package/dist/candle-cdn.d.ts.map +1 -0
- package/dist/candle-cdn.js +138 -0
- package/dist/candle-cdn.js.map +1 -0
- package/dist/client.d.ts +98 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +225 -0
- package/dist/client.js.map +1 -0
- package/dist/errors.d.ts +153 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +243 -0
- package/dist/errors.js.map +1 -0
- package/dist/events.d.ts +2 -0
- package/dist/events.d.ts.map +1 -0
- package/dist/events.js +6 -0
- package/dist/events.js.map +1 -0
- package/dist/index.d.ts +21 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +71 -0
- package/dist/index.js.map +1 -0
- package/dist/ladder.d.ts +40 -0
- package/dist/ladder.d.ts.map +1 -0
- package/dist/ladder.js +145 -0
- package/dist/ladder.js.map +1 -0
- package/dist/ladder.test.d.ts +2 -0
- package/dist/ladder.test.d.ts.map +1 -0
- package/dist/ladder.test.js +112 -0
- package/dist/ladder.test.js.map +1 -0
- package/dist/operation-handle.d.ts +88 -0
- package/dist/operation-handle.d.ts.map +1 -0
- package/dist/operation-handle.js +262 -0
- package/dist/operation-handle.js.map +1 -0
- package/dist/recovery.d.ts +20 -0
- package/dist/recovery.d.ts.map +1 -0
- package/dist/recovery.js +91 -0
- package/dist/recovery.js.map +1 -0
- package/dist/revalue.d.ts +22 -0
- package/dist/revalue.d.ts.map +1 -0
- package/dist/revalue.js +153 -0
- package/dist/revalue.js.map +1 -0
- package/dist/streams.d.ts +661 -0
- package/dist/streams.d.ts.map +1 -0
- package/dist/streams.js +2272 -0
- package/dist/streams.js.map +1 -0
- package/dist/types.d.ts +2814 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +118 -0
- package/dist/types.js.map +1 -0
- package/dist/websocket.d.ts +240 -0
- package/dist/websocket.d.ts.map +1 -0
- package/dist/websocket.js +1288 -0
- package/dist/websocket.js.map +1 -0
- package/package.json +48 -0
package/dist/arca.d.ts
ADDED
|
@@ -0,0 +1,1343 @@
|
|
|
1
|
+
import { OperationHandle, OrderHandle } from './operation-handle';
|
|
2
|
+
import type { AuthErrorListener, TokenProvider } from './types';
|
|
3
|
+
import { ArcaConfig, ArcaObject, ArcaObjectBrowseResponse, ArcaObjectDetailResponse, ArcaObjectListResponse, ArcaObjectVersionsResponse, ArcaBalance, AggregationSourceDto, BrowseObjectsOptions, CreateIsolationZoneOptions, EnsureArcaObjectResponse, EnsureArcaOptions, EnsureDenominatedArcaOptions, EnsureInfoOptions, CreateWatchResponse, UpdateLabelsOptions, DeleteArcaObjectResponse, FundAccountOptions, EnsureDeletedOptions, DefundAccountOptions, DefundAccountResponse, EventDetailResponse, ExportOperationEvidenceOptions, ExplorerSummary, FundAccountResponse, GetOperationOptions, ListObjectsOptions, ListEventsOptions, ListOperationsOptions, EventListResponse, NonceResponse, Operation, OperationDetailResponse, OperationEvidenceExportResponse, OperationListResponse, OrderOperationResponse, PathAggregation, PnlResponse, PnlHistoryResponse, EquityHistoryResponse, ReconciliationStateListResponse, SnapshotBalancesResponse, StateDeltaListResponse, TransferOptions, TransferResponse, CancelOrderOptions, ClosePositionOptions, CreatePerpsExchangeOptions, PlaceOrderOptions, SetPositionTriggerOptions, SetPositionTpslOptions, SetPositionTpslResult, ClearPositionTpslOptions, UpdateLeverageOptions, UpdateLeverageResponse, UpdateIsolatedMarginOptions, UpdateIsolatedMarginResponse, SetMarginModeOptions, SetMarginModeResponse, LeverageSetting, ExchangeState, ObjectValuation, SimOrder, SimOrderWithFills, SimPosition, Market, SimMetaResponse, SimMidsResponse, MarketTickersResponse, SimBookResponse, InvariantCheckResponse, ActiveAssetData, AssetFeeEntry, OrderBreakdownOptions, OrderBreakdown, CandleInterval, CandlesResponse, SparklinesResponse, CreatePaymentLinkOptions, CreatePaymentLinkResponse, ListPaymentLinksOptions, PaymentLinkListResponse, FeeEstimateParams, FeeEstimate, FillListResponse, ListFillsOptions, TradeSummaryResponse, TradeSummaryOptions, OrderLimits, PlaceTwapOptions, TwapOperationResponse, Twap, TwapLimits, CustodyStatus, CustodyBoundary, CustodyExchangeArca, RegisterRecoveryKeyOptions, RegisterRecoveryKeyResponse, PreparedCustodyTransaction, GeneratedRecoveryKey, IsolationZone, FolderLabelsResponse, UpdateFolderLabelsRequest } from './types';
|
|
4
|
+
import { WebSocketManager } from './websocket';
|
|
5
|
+
import { OperationWatchStream, BalanceWatchStream, ObjectWatchStream, ObjectsWatchStream, AggregationWatchStream, EquityChartStream, PnlChartStream, MaxOrderSizeWatchStream, PriceWatchStream, CandleWatchStream, CandleChartStream, TradeWatchStream, ExchangeWatchStream, FillWatchStream, FundingWatchStream, TwapWatchStream } from './streams';
|
|
6
|
+
import type { MaxOrderSizeWatchOptions } from './streams';
|
|
7
|
+
export { OperationWatchStream, BalanceWatchStream, ObjectWatchStream, ObjectsWatchStream, AggregationWatchStream, EquityChartStream, PnlChartStream, MaxOrderSizeWatchStream, PriceWatchStream, CandleWatchStream, CandleChartStream, TradeWatchStream, ExchangeWatchStream, FillWatchStream, FundingWatchStream, TwapWatchStream } from './streams';
|
|
8
|
+
export type { InitialHistoryState, OperationUpdate, BalanceSnapshot, BalanceUpdate, EquityChartUpdate, PnlChartUpdate, MaxOrderSizeUpdate, MaxOrderSizeWatchOptions, FillUpdate, FundingUpdate, TwapUpdate } from './streams';
|
|
9
|
+
/** @deprecated Use {@link PriceWatchStream} instead. */
|
|
10
|
+
export type MarketPriceStream = PriceWatchStream;
|
|
11
|
+
export type PnlHistoryAnchor = 'zero' | 'equity';
|
|
12
|
+
/**
|
|
13
|
+
* Scope options shared by the equity/P&L history methods.
|
|
14
|
+
*
|
|
15
|
+
* Default (`kind: 'path'`) aggregates across every object under the path
|
|
16
|
+
* prefix. `kind: 'object'` charts a single object by id and lets the
|
|
17
|
+
* server skip enumerating the prefix's objects — a meaningful saving for
|
|
18
|
+
* a single-object (e.g. one exchange account) chart. `objectId` is
|
|
19
|
+
* required when `kind` is `'object'`.
|
|
20
|
+
*/
|
|
21
|
+
export interface HistoryScopeOptions {
|
|
22
|
+
kind?: 'path' | 'object';
|
|
23
|
+
objectId?: string;
|
|
24
|
+
}
|
|
25
|
+
export interface PnlHistoryOptions extends HistoryScopeOptions {
|
|
26
|
+
/**
|
|
27
|
+
* `zero` returns a standard P&L series. `equity` also returns valueUsd,
|
|
28
|
+
* which shifts P&L by total external flows so deposits/transfers adjust the
|
|
29
|
+
* baseline instead of drawing timeline jumps.
|
|
30
|
+
*/
|
|
31
|
+
anchor?: PnlHistoryAnchor;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Options for {@link Arca.watchPrices}.
|
|
35
|
+
*/
|
|
36
|
+
export interface WatchPricesOptions {
|
|
37
|
+
/** Exchange identifier. Default: `"sim"`. */
|
|
38
|
+
exchange?: string;
|
|
39
|
+
/**
|
|
40
|
+
* Canonical market IDs to narrow the subscription (e.g. `["hl:0:BTC"]`).
|
|
41
|
+
* Omit or pass an empty array to subscribe to all assets.
|
|
42
|
+
*/
|
|
43
|
+
coins?: string[];
|
|
44
|
+
/**
|
|
45
|
+
* Max time to wait for the initial snapshot, in milliseconds. If the
|
|
46
|
+
* stream does not reach `connected` within this window, `watchPrices`
|
|
47
|
+
* rejects with {@link WatchStreamReadyTimeoutError} and tears down the
|
|
48
|
+
* underlying subscription. Omit (the default) to wait forever.
|
|
49
|
+
*/
|
|
50
|
+
readyTimeoutMs?: number;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Range presets accepted by `watchEquityChartLive` / `watchPnlChartLive`
|
|
54
|
+
* and by {@link computeChartRange}. These match the chart range pickers
|
|
55
|
+
* used by the portal and other Arca surfaces.
|
|
56
|
+
*/
|
|
57
|
+
export type ChartRangePreset = '1h' | '24h' | '7d' | '30d' | '3m' | '1y' | 'ytd' | 'all';
|
|
58
|
+
/**
|
|
59
|
+
* Compute `from`/`to` ISO timestamps for a chart range preset, anchored
|
|
60
|
+
* to the current wall clock. Used by `watchEquityChartLive` /
|
|
61
|
+
* `watchPnlChartLive`. Exposed as a public helper so builders building
|
|
62
|
+
* custom React/Swift/Vue UIs can derive the same windows the SDK uses.
|
|
63
|
+
*/
|
|
64
|
+
export declare function computeChartRange(range: ChartRangePreset): {
|
|
65
|
+
from: string;
|
|
66
|
+
to: string;
|
|
67
|
+
};
|
|
68
|
+
export declare class Arca {
|
|
69
|
+
static fees: {
|
|
70
|
+
readonly exchangeTransfer: "0.05";
|
|
71
|
+
};
|
|
72
|
+
/**
|
|
73
|
+
* Pure calculator that converts between spend (gross), notional (net), and
|
|
74
|
+
* token representations of an order. All inputs come from `ActiveAssetData`
|
|
75
|
+
* or `watchMaxOrderSize`. No network call.
|
|
76
|
+
*
|
|
77
|
+
* `tokens` in the result is the committed quantity submitted to the exchange.
|
|
78
|
+
* Dollar values are estimates at the provided `price`. For limit orders
|
|
79
|
+
* (where `price` is the limit), the breakdown is exact contingent on fill.
|
|
80
|
+
* For market orders (where `price` is mark), actual fill price may differ.
|
|
81
|
+
*/
|
|
82
|
+
static orderBreakdown(opts: OrderBreakdownOptions): OrderBreakdown;
|
|
83
|
+
private readonly client;
|
|
84
|
+
private readonly realmInput;
|
|
85
|
+
private resolvedRealmId;
|
|
86
|
+
private initPromise;
|
|
87
|
+
private readonly candleCdnBaseUrl;
|
|
88
|
+
private readonly tokenProvider;
|
|
89
|
+
private pendingRefresh;
|
|
90
|
+
private refreshTimer;
|
|
91
|
+
private tokenFetchPromise;
|
|
92
|
+
private authErrorListeners;
|
|
93
|
+
private metaCache;
|
|
94
|
+
private metaPromise;
|
|
95
|
+
private twapLimitsCache;
|
|
96
|
+
/** WebSocket manager for real-time events. */
|
|
97
|
+
readonly ws: WebSocketManager;
|
|
98
|
+
private readonly historyCache;
|
|
99
|
+
constructor(config: ArcaConfig);
|
|
100
|
+
/**
|
|
101
|
+
* Create an Arca instance from a scoped JWT token.
|
|
102
|
+
* The realm is extracted from the token claims automatically.
|
|
103
|
+
*
|
|
104
|
+
* @param token - Scoped JWT issued by POST /auth/token
|
|
105
|
+
* @param opts - Optional overrides (baseUrl, realm)
|
|
106
|
+
*/
|
|
107
|
+
static fromToken(token: string, opts?: {
|
|
108
|
+
baseUrl?: string;
|
|
109
|
+
realm?: string;
|
|
110
|
+
tokenProvider?: TokenProvider;
|
|
111
|
+
}): Arca;
|
|
112
|
+
/**
|
|
113
|
+
* Create an Arca instance with automatic token management.
|
|
114
|
+
* The provider is called immediately to get the first token and
|
|
115
|
+
* then automatically before each expiry.
|
|
116
|
+
*
|
|
117
|
+
* @param tokenProvider - Async function returning a fresh scoped JWT
|
|
118
|
+
* @param opts - Optional overrides (baseUrl, realm, initial token)
|
|
119
|
+
*/
|
|
120
|
+
static fromTokenProvider(tokenProvider: TokenProvider, opts?: {
|
|
121
|
+
baseUrl?: string;
|
|
122
|
+
realm?: string;
|
|
123
|
+
token?: string;
|
|
124
|
+
}): Arca;
|
|
125
|
+
/**
|
|
126
|
+
* Replace the scoped JWT token used for HTTP requests and WebSocket
|
|
127
|
+
* authentication. The new token takes effect immediately for HTTP;
|
|
128
|
+
* the WebSocket reconnects immediately if it's currently disconnected.
|
|
129
|
+
*
|
|
130
|
+
* @param token - A fresh scoped JWT issued by POST /auth/token
|
|
131
|
+
*/
|
|
132
|
+
updateToken(token: string): void;
|
|
133
|
+
/**
|
|
134
|
+
* Register or clear the handler invoked when a request fails with
|
|
135
|
+
* HTTP 412 `STEP_UP_REQUIRED`. The handler is responsible for
|
|
136
|
+
* interactively obtaining a single-use step-up JWT (typically by
|
|
137
|
+
* showing an in-app confirmation modal that creates and approves a
|
|
138
|
+
* step-up request); the SDK retries the original request once with
|
|
139
|
+
* that token and restores the original credential afterward.
|
|
140
|
+
*
|
|
141
|
+
* Pass `undefined` to clear a previously-registered handler.
|
|
142
|
+
*
|
|
143
|
+
* See `.cursor/rules/step-up-auth.mdc` for the full step-up contract.
|
|
144
|
+
*/
|
|
145
|
+
setStepUpHandler(handler?: import('./client').StepUpHandler): void;
|
|
146
|
+
/**
|
|
147
|
+
* Register a listener for unrecoverable authentication errors.
|
|
148
|
+
* Fires when:
|
|
149
|
+
* - HTTP 401 is received and no tokenProvider is configured
|
|
150
|
+
* - The tokenProvider itself throws (refresh failed)
|
|
151
|
+
*
|
|
152
|
+
* Use this to show a "session expired" UI or prompt re-authentication.
|
|
153
|
+
* Returns an unsubscribe function.
|
|
154
|
+
*/
|
|
155
|
+
onAuthError(listener: AuthErrorListener): () => void;
|
|
156
|
+
/**
|
|
157
|
+
* Clear the in-memory cache of historical data responses
|
|
158
|
+
* (equity history, PnL history, candles).
|
|
159
|
+
*/
|
|
160
|
+
clearHistoryCache(): void;
|
|
161
|
+
/**
|
|
162
|
+
* Initialize the SDK by resolving the realm slug to an ID.
|
|
163
|
+
* This is called automatically on the first API call, but can be
|
|
164
|
+
* called explicitly for eager initialization.
|
|
165
|
+
*/
|
|
166
|
+
ready(): Promise<void>;
|
|
167
|
+
/**
|
|
168
|
+
* Create a user account (denominated Arca object) at the given path.
|
|
169
|
+
*
|
|
170
|
+
* Idempotent: creates the account if it doesn't exist, returns the
|
|
171
|
+
* existing one if it does. Safe to call on every request.
|
|
172
|
+
*
|
|
173
|
+
* @example
|
|
174
|
+
* // Create a user wallet
|
|
175
|
+
* const wallet = await arca.ensureDenominatedArca({
|
|
176
|
+
* ref: '/users/alice/wallet',
|
|
177
|
+
* });
|
|
178
|
+
*
|
|
179
|
+
* `await` resolves when the object is active (immediate for existing
|
|
180
|
+
* objects, waits for creation workflow otherwise).
|
|
181
|
+
* Use `.submitted` to access the HTTP response before the operation settles.
|
|
182
|
+
*/
|
|
183
|
+
ensureDenominatedArca(opts: EnsureDenominatedArcaOptions): OperationHandle<EnsureArcaObjectResponse>;
|
|
184
|
+
/**
|
|
185
|
+
* Ensure an Arca object of any type exists at the given path.
|
|
186
|
+
* Creates it if it doesn't exist; returns the existing one if it does
|
|
187
|
+
* (matching type). Safe to call on every request.
|
|
188
|
+
*
|
|
189
|
+
* `await` resolves when the object is active (immediate for existing
|
|
190
|
+
* objects, waits for creation workflow otherwise).
|
|
191
|
+
* Use `.submitted` to access the HTTP response before the operation settles.
|
|
192
|
+
*/
|
|
193
|
+
ensureArca(opts: EnsureArcaOptions): OperationHandle<EnsureArcaObjectResponse>;
|
|
194
|
+
/**
|
|
195
|
+
* Ensure an info object exists at the given directory path.
|
|
196
|
+
* Info objects store labels (key-value metadata) but cannot hold balances.
|
|
197
|
+
* Appends `/.info` to the path if not already present.
|
|
198
|
+
*
|
|
199
|
+
* `await` resolves when the object is active.
|
|
200
|
+
* Use `.submitted` to access the HTTP response before the operation settles.
|
|
201
|
+
*/
|
|
202
|
+
ensureInfo(opts: EnsureInfoOptions): OperationHandle<EnsureArcaObjectResponse>;
|
|
203
|
+
/**
|
|
204
|
+
* Delete an Arca object by path. If sweepTo is provided, remaining funds
|
|
205
|
+
* are transferred to that Arca before deletion.
|
|
206
|
+
*
|
|
207
|
+
* If the object is already deleted, returns the existing state.
|
|
208
|
+
*/
|
|
209
|
+
ensureDeleted(opts: EnsureDeletedOptions): OperationHandle<DeleteArcaObjectResponse>;
|
|
210
|
+
/**
|
|
211
|
+
* Get an Arca object by path.
|
|
212
|
+
*/
|
|
213
|
+
getObject(path: string): Promise<ArcaObject>;
|
|
214
|
+
/**
|
|
215
|
+
* Get an Arca object's full detail (operations, events, deltas, balances) by ID.
|
|
216
|
+
*/
|
|
217
|
+
getObjectDetail(objectId: string): Promise<ArcaObjectDetailResponse>;
|
|
218
|
+
/**
|
|
219
|
+
* List Arca objects, optionally filtered by path.
|
|
220
|
+
*
|
|
221
|
+
* @param opts.path - Object path or path prefix to filter by.
|
|
222
|
+
* Exact path (no trailing slash): returns the single matching object.
|
|
223
|
+
* Path prefix (trailing slash): returns all objects under that prefix.
|
|
224
|
+
* Examples: '/users/alice/main' (single), '/users/alice/' (subtree)
|
|
225
|
+
*/
|
|
226
|
+
listObjects(opts?: ListObjectsOptions): Promise<ArcaObjectListResponse>;
|
|
227
|
+
/**
|
|
228
|
+
* Get balances for an Arca object by ID.
|
|
229
|
+
*/
|
|
230
|
+
getBalances(objectId: string): Promise<ArcaBalance[]>;
|
|
231
|
+
/**
|
|
232
|
+
* Get balances for an Arca object by path.
|
|
233
|
+
* Resolves the path to an object ID, then fetches balances.
|
|
234
|
+
*/
|
|
235
|
+
getBalancesByPath(path: string): Promise<ArcaBalance[]>;
|
|
236
|
+
/**
|
|
237
|
+
* Browse Arca objects in a folder-like structure.
|
|
238
|
+
* Returns folders (path segments) and objects at the given path.
|
|
239
|
+
*
|
|
240
|
+
* @param opts.path - Path prefix to browse (default: '/'). Must end with '/'.
|
|
241
|
+
*/
|
|
242
|
+
browseObjects(opts?: BrowseObjectsOptions): Promise<ArcaObjectBrowseResponse>;
|
|
243
|
+
/**
|
|
244
|
+
* Declare a path as an isolation zone before adding objects beneath it.
|
|
245
|
+
* Returns the existing declaration when the same path was already created.
|
|
246
|
+
*/
|
|
247
|
+
createIsolationZone(opts: CreateIsolationZoneOptions): Promise<IsolationZone>;
|
|
248
|
+
/**
|
|
249
|
+
* Update labels on an Arca object.
|
|
250
|
+
* Pass null as a label value to remove that key.
|
|
251
|
+
*/
|
|
252
|
+
updateLabels(opts: UpdateLabelsOptions): Promise<ArcaObject>;
|
|
253
|
+
/**
|
|
254
|
+
* Read folder-level labels for a path. Folders are virtual
|
|
255
|
+
* aggregations of arca paths; labels live in their own table and
|
|
256
|
+
* are surfaced inline on `browseObjects()` rows so the portal can
|
|
257
|
+
* disambiguate visually-identical folders.
|
|
258
|
+
*
|
|
259
|
+
* Returns `{ labels: {} }` when no labels are set on the folder.
|
|
260
|
+
*/
|
|
261
|
+
getFolderLabels(path: string): Promise<FolderLabelsResponse>;
|
|
262
|
+
/**
|
|
263
|
+
* Replace the label set on a folder path. The `labels` field is a
|
|
264
|
+
* full overwrite — pass the desired final state, not a delta. Pass
|
|
265
|
+
* `{}` to remove all labels on the folder.
|
|
266
|
+
*
|
|
267
|
+
* Validation matches leaf-arca labels: 32 keys max, key pattern
|
|
268
|
+
* `^[a-zA-Z][a-zA-Z0-9._-]*$`, `arca.` and `_` reserved prefixes,
|
|
269
|
+
* value ≤ 256 chars.
|
|
270
|
+
*/
|
|
271
|
+
updateFolderLabels(opts: Omit<UpdateFolderLabelsRequest, 'realmId'>): Promise<FolderLabelsResponse>;
|
|
272
|
+
/**
|
|
273
|
+
* Get version history for an Arca object.
|
|
274
|
+
*/
|
|
275
|
+
getObjectVersions(objectId: string): Promise<ArcaObjectVersionsResponse>;
|
|
276
|
+
/**
|
|
277
|
+
* Get snapshot balances for an Arca object at a specific point in time.
|
|
278
|
+
*/
|
|
279
|
+
getSnapshotBalances(objectId: string, asOf: string): Promise<SnapshotBalancesResponse>;
|
|
280
|
+
/**
|
|
281
|
+
* Execute a transfer between two Arca objects.
|
|
282
|
+
* Settlement is immediate for denominated targets (await resolves instantly),
|
|
283
|
+
* or async for exchange targets (await waits for settlement).
|
|
284
|
+
* The operation path serves as the idempotency key.
|
|
285
|
+
*/
|
|
286
|
+
transfer(opts: TransferOptions): OperationHandle<TransferResponse>;
|
|
287
|
+
/**
|
|
288
|
+
* Estimate the fee for a transfer or order operation.
|
|
289
|
+
*/
|
|
290
|
+
estimateFee(params: FeeEstimateParams): Promise<FeeEstimate>;
|
|
291
|
+
/**
|
|
292
|
+
* Programmatically fund an Arca object. This is a developer tool for
|
|
293
|
+
* development realm use (competitions, programmatic account seeding).
|
|
294
|
+
* For production deposit flows, use `createPaymentLink({ type: 'deposit' })`.
|
|
295
|
+
*
|
|
296
|
+
* `await` waits for settlement. Use `.submitted` to access
|
|
297
|
+
* the poolAddress and other response data before settlement.
|
|
298
|
+
*/
|
|
299
|
+
fundAccount(opts: FundAccountOptions): OperationHandle<FundAccountResponse>;
|
|
300
|
+
/**
|
|
301
|
+
* Programmatically withdraw from an Arca object. This is a developer/test tool
|
|
302
|
+
* for non-production use. For production withdrawal flows, use
|
|
303
|
+
* `createPaymentLink({ type: 'withdrawal' })`.
|
|
304
|
+
*/
|
|
305
|
+
defundAccount(opts: DefundAccountOptions): OperationHandle<DefundAccountResponse>;
|
|
306
|
+
/**
|
|
307
|
+
* Create a hosted deposit or withdrawal page for an end user.
|
|
308
|
+
*
|
|
309
|
+
* Returns a URL that the user can visit to deposit into (or withdraw from)
|
|
310
|
+
* the specified Arca object. Use this instead of `fundAccount()`/`defundAccount()`
|
|
311
|
+
* in production.
|
|
312
|
+
*
|
|
313
|
+
* @example
|
|
314
|
+
* const link = await arca.createPaymentLink({
|
|
315
|
+
* objectId: walletId,
|
|
316
|
+
* direction: 'deposit',
|
|
317
|
+
* amount: '100',
|
|
318
|
+
* returnUrl: 'https://myapp.com/dashboard',
|
|
319
|
+
* });
|
|
320
|
+
* // Redirect user to link.url
|
|
321
|
+
*/
|
|
322
|
+
createPaymentLink(opts: CreatePaymentLinkOptions): OperationHandle<CreatePaymentLinkResponse>;
|
|
323
|
+
/**
|
|
324
|
+
* List payment links for this realm, optionally filtered by type or status.
|
|
325
|
+
*/
|
|
326
|
+
listPaymentLinks(opts?: ListPaymentLinksOptions): Promise<PaymentLinkListResponse>;
|
|
327
|
+
/**
|
|
328
|
+
* Get operation detail by ID (includes correlated events and deltas).
|
|
329
|
+
*/
|
|
330
|
+
getOperation(operationId: string, options?: GetOperationOptions): Promise<OperationDetailResponse>;
|
|
331
|
+
/**
|
|
332
|
+
* List operations in the realm.
|
|
333
|
+
*/
|
|
334
|
+
listOperations(opts?: ListOperationsOptions): Promise<OperationListResponse>;
|
|
335
|
+
/**
|
|
336
|
+
* Export realm-scoped operation audit evidence over a time range.
|
|
337
|
+
*/
|
|
338
|
+
exportOperationEvidence(opts: ExportOperationEvidenceOptions): Promise<OperationEvidenceExportResponse>;
|
|
339
|
+
/**
|
|
340
|
+
* List events in the realm.
|
|
341
|
+
*/
|
|
342
|
+
listEvents(opts?: ListEventsOptions): Promise<EventListResponse>;
|
|
343
|
+
/**
|
|
344
|
+
* Get event detail by ID (includes the parent operation and correlated deltas).
|
|
345
|
+
*/
|
|
346
|
+
getEventDetail(eventId: string): Promise<EventDetailResponse>;
|
|
347
|
+
/**
|
|
348
|
+
* List balance change records (state deltas) for a given path.
|
|
349
|
+
*
|
|
350
|
+
* Each delta is an immutable record of a balance change — who changed,
|
|
351
|
+
* how much, and which operation caused it. Useful for building
|
|
352
|
+
* transaction history views.
|
|
353
|
+
*/
|
|
354
|
+
listDeltas(arcaPath: string): Promise<StateDeltaListResponse>;
|
|
355
|
+
/**
|
|
356
|
+
* Get the next unique nonce for a path prefix.
|
|
357
|
+
* Useful for constructing unique idempotent operation paths.
|
|
358
|
+
*
|
|
359
|
+
* **Important:** Reserve the nonce *before* the operation and store the
|
|
360
|
+
* resulting path. Reuse the stored path on retry — never call `nonce()`
|
|
361
|
+
* inline inside an operation call, as each invocation produces a new
|
|
362
|
+
* unique path and defeats idempotency.
|
|
363
|
+
*
|
|
364
|
+
* @param path - Path prefix for nonce generation (e.g. '/op/transfer/fund').
|
|
365
|
+
* Always used as a prefix — the nonce number is appended.
|
|
366
|
+
* @param separator - Override separator between path and nonce number.
|
|
367
|
+
* Default: '/' if path ends with '/', otherwise '-'.
|
|
368
|
+
* Use ':' for operation nonces (e.g. '/op/create/wallets/main:1').
|
|
369
|
+
*/
|
|
370
|
+
nonce(path: string, separator?: string): Promise<NonceResponse>;
|
|
371
|
+
/**
|
|
372
|
+
* Get aggregate counts and statistics for the realm: total objects,
|
|
373
|
+
* operations, events, and active watches.
|
|
374
|
+
*/
|
|
375
|
+
summary(): Promise<ExplorerSummary>;
|
|
376
|
+
/**
|
|
377
|
+
* Get aggregated valuation for objects at a path.
|
|
378
|
+
*
|
|
379
|
+
* @param path - Object path or path prefix.
|
|
380
|
+
* Exact path (no trailing slash): returns valuation for a single object.
|
|
381
|
+
* Path prefix (trailing slash): returns aggregated valuation for all objects under that prefix.
|
|
382
|
+
* Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
|
|
383
|
+
* @param options.asOf - ISO timestamp for historical aggregation.
|
|
384
|
+
*/
|
|
385
|
+
getPathAggregation(path: string, options?: {
|
|
386
|
+
asOf?: string;
|
|
387
|
+
}): Promise<PathAggregation>;
|
|
388
|
+
/**
|
|
389
|
+
* Get P&L (profit and loss) for objects at a path over a time range.
|
|
390
|
+
*
|
|
391
|
+
* @param path - Object path or path prefix.
|
|
392
|
+
* Exact path (no trailing slash): returns P&L for a single object.
|
|
393
|
+
* Path prefix (trailing slash): returns aggregated P&L for all objects under that prefix.
|
|
394
|
+
* Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
|
|
395
|
+
* @param from - ISO timestamp for the start of the range.
|
|
396
|
+
* @param to - ISO timestamp for the end of the range.
|
|
397
|
+
*/
|
|
398
|
+
getPnl(path: string, from: string, to: string): Promise<PnlResponse>;
|
|
399
|
+
/**
|
|
400
|
+
* Get P&L history (time-series) for objects at a path.
|
|
401
|
+
*
|
|
402
|
+
* @param path - Object path or path prefix.
|
|
403
|
+
* Exact path (no trailing slash): returns P&L history for a single object.
|
|
404
|
+
* Path prefix (trailing slash): returns aggregated P&L history for all objects under that prefix.
|
|
405
|
+
* Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
|
|
406
|
+
* @param from - ISO timestamp for the start of the range.
|
|
407
|
+
* @param to - ISO timestamp for the end of the range.
|
|
408
|
+
* @param points - Number of samples (default 1000, max 1000). The backend
|
|
409
|
+
* ladder picks the finest resolution whose bucket count fits within
|
|
410
|
+
* `points`, so the default targets `5m` for 24h, `1h` for 1M, and `4h`
|
|
411
|
+
* for 3M ranges.
|
|
412
|
+
*/
|
|
413
|
+
getPnlHistory(path: string, from: string, to: string, points?: number, options?: PnlHistoryOptions): Promise<PnlHistoryResponse>;
|
|
414
|
+
/**
|
|
415
|
+
* Get equity history (time-series) for objects at a path.
|
|
416
|
+
*
|
|
417
|
+
* @param path - Object path or path prefix.
|
|
418
|
+
* Exact path (no trailing slash): returns equity history for a single object.
|
|
419
|
+
* Path prefix (trailing slash): returns aggregated equity history for all objects under that prefix.
|
|
420
|
+
* Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
|
|
421
|
+
* @param from - ISO timestamp for the start of the range.
|
|
422
|
+
* @param to - ISO timestamp for the end of the range.
|
|
423
|
+
* @param points - Number of samples (default 1000, max 1000). The backend
|
|
424
|
+
* ladder picks the finest resolution whose bucket count fits within
|
|
425
|
+
* `points`, so the default targets `5m` for 24h, `1h` for 1M, and `4h`
|
|
426
|
+
* for 3M ranges.
|
|
427
|
+
*/
|
|
428
|
+
getEquityHistory(path: string, from: string, to: string, points?: number, options?: HistoryScopeOptions): Promise<EquityHistoryResponse>;
|
|
429
|
+
/**
|
|
430
|
+
* Create a live equity chart that merges historical data with real-time
|
|
431
|
+
* aggregation updates. The last point reflects the current live equity;
|
|
432
|
+
* when the interval boundary crosses, the live point is promoted to
|
|
433
|
+
* historical and a new live point starts.
|
|
434
|
+
*
|
|
435
|
+
* @param path - Object path or path prefix.
|
|
436
|
+
* Exact path (no trailing slash): chart for a single object.
|
|
437
|
+
* Path prefix (trailing slash): chart aggregated across all objects under that prefix.
|
|
438
|
+
* Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
|
|
439
|
+
*/
|
|
440
|
+
watchEquityChart(path: string, from: string, to: string, points?: number, options?: {
|
|
441
|
+
exchange?: string;
|
|
442
|
+
} & HistoryScopeOptions): Promise<EquityChartStream>;
|
|
443
|
+
/**
|
|
444
|
+
* Create a live P&L chart that merges historical P&L data with real-time
|
|
445
|
+
* aggregation updates and operation events. The rightmost point updates on
|
|
446
|
+
* each aggregation event. Operation events (deposits/transfers) update
|
|
447
|
+
* cumulative flows client-side — zero additional server reads.
|
|
448
|
+
*
|
|
449
|
+
* @param path - Object path or path prefix.
|
|
450
|
+
* Exact path (no trailing slash): P&L chart for a single object.
|
|
451
|
+
* Path prefix (trailing slash): P&L chart aggregated across all objects under that prefix.
|
|
452
|
+
* Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
|
|
453
|
+
* @param options.anchor - `'zero'` (default): standard P&L chart starting at 0.
|
|
454
|
+
* `'equity'`: each point includes `valueUsd` — the P&L shifted so the live
|
|
455
|
+
* (rightmost) value equals the current account equity. The chart shape is
|
|
456
|
+
* identical to the P&L chart; only the y-axis is translated.
|
|
457
|
+
*/
|
|
458
|
+
watchPnlChart(path: string, from: string, to: string, points?: number, options?: {
|
|
459
|
+
exchange?: string;
|
|
460
|
+
anchor?: 'zero' | 'equity';
|
|
461
|
+
} & HistoryScopeOptions): Promise<PnlChartStream>;
|
|
462
|
+
/**
|
|
463
|
+
* Convenience: open a live equity chart for a sliding range preset
|
|
464
|
+
* (`'1h'`, `'24h'`, `'7d'`, ...). Computes `from`/`to` from the current
|
|
465
|
+
* wall clock and delegates to {@link watchEquityChart}, which handles
|
|
466
|
+
* sliding the window forward on every refresh and self-healing across
|
|
467
|
+
* tab idle. Equivalent to:
|
|
468
|
+
*
|
|
469
|
+
* ```ts
|
|
470
|
+
* const { from, to } = computeChartRange('1h');
|
|
471
|
+
* const stream = await arca.watchEquityChart(path, from, to, points);
|
|
472
|
+
* ```
|
|
473
|
+
*/
|
|
474
|
+
watchEquityChartLive(path: string, options: {
|
|
475
|
+
range: ChartRangePreset;
|
|
476
|
+
points?: number;
|
|
477
|
+
exchange?: string;
|
|
478
|
+
}): Promise<EquityChartStream>;
|
|
479
|
+
/**
|
|
480
|
+
* Convenience: open a live P&L chart for a sliding range preset.
|
|
481
|
+
* See {@link watchEquityChartLive}.
|
|
482
|
+
*/
|
|
483
|
+
watchPnlChartLive(path: string, options: {
|
|
484
|
+
range: ChartRangePreset;
|
|
485
|
+
points?: number;
|
|
486
|
+
exchange?: string;
|
|
487
|
+
anchor?: 'zero' | 'equity';
|
|
488
|
+
}): Promise<PnlChartStream>;
|
|
489
|
+
/**
|
|
490
|
+
* Create an aggregation watch that tracks a set of sources.
|
|
491
|
+
* Returns the watch ID and the initial aggregation.
|
|
492
|
+
* When the underlying data changes, `aggregation.updated` events are
|
|
493
|
+
* pushed via WebSocket with the updated aggregation inline.
|
|
494
|
+
*/
|
|
495
|
+
createAggregationWatch(sources: AggregationSourceDto[]): Promise<CreateWatchResponse>;
|
|
496
|
+
/**
|
|
497
|
+
* Get the current aggregation for an existing watch.
|
|
498
|
+
*/
|
|
499
|
+
getWatchAggregation(watchId: string): Promise<PathAggregation>;
|
|
500
|
+
/**
|
|
501
|
+
* Destroy an aggregation watch. The server stops tracking and pushing updates.
|
|
502
|
+
*/
|
|
503
|
+
destroyAggregationWatch(watchId: string): Promise<void>;
|
|
504
|
+
/**
|
|
505
|
+
* Subscribe to real-time aggregation updates for a set of sources.
|
|
506
|
+
* Automatically handles server-side watch creation, structural change events,
|
|
507
|
+
* and client-side revaluation from mid prices. Call `.close()` when done.
|
|
508
|
+
*/
|
|
509
|
+
watchAggregation(sources: AggregationSourceDto[], options?: {
|
|
510
|
+
exchange?: string;
|
|
511
|
+
flowsSince?: string;
|
|
512
|
+
}): Promise<AggregationWatchStream>;
|
|
513
|
+
/**
|
|
514
|
+
* List reconciliation state entries for the realm.
|
|
515
|
+
*/
|
|
516
|
+
listReconciliationState(): Promise<ReconciliationStateListResponse>;
|
|
517
|
+
/**
|
|
518
|
+
* Ensure a Perps Exchange Arca object exists at the given path.
|
|
519
|
+
* Automatically sets type=exchange and the venue metadata.
|
|
520
|
+
*
|
|
521
|
+
* The `venue` decides routing: `'hl-sim'` (default) provisions a
|
|
522
|
+
* simulated Hyperliquid account; `'hl'` provisions a live one.
|
|
523
|
+
*
|
|
524
|
+
* Note: exchange account creation involves a synchronous gRPC call from
|
|
525
|
+
* the worker into sim-exchange (see `ExecuteCreateObject`), which has a
|
|
526
|
+
* worse worst-case latency than transfers. The default settlement wait
|
|
527
|
+
* is 60s rather than the SDK-wide 30s default. Override via
|
|
528
|
+
* `await handle.wait({ timeout })` when you need a tighter bound.
|
|
529
|
+
*/
|
|
530
|
+
ensurePerpsExchange(opts: CreatePerpsExchangeOptions): OperationHandle<EnsureArcaObjectResponse>;
|
|
531
|
+
/**
|
|
532
|
+
* Get exchange account state (equity, margin, positions, orders).
|
|
533
|
+
*/
|
|
534
|
+
getExchangeState(objectId: string): Promise<ExchangeState>;
|
|
535
|
+
/**
|
|
536
|
+
* Get active asset trading data for an exchange object: max trade sizes,
|
|
537
|
+
* available margin, mark price, and fee rate. Accounts for leverage,
|
|
538
|
+
* existing positions, and fees (including builder fee when provided).
|
|
539
|
+
*
|
|
540
|
+
* @param market - Coin in canonical format (e.g. "hl:0:BTC", "hl:1:SILVER")
|
|
541
|
+
* @param applicationFeeTenthsBps - Optional application fee in tenths of a basis point
|
|
542
|
+
* @param leverage - Optional leverage override. When provided, the server
|
|
543
|
+
* uses this value instead of the stored leverage setting. When omitted,
|
|
544
|
+
* the server reads the leverage from the account's per-market setting
|
|
545
|
+
* (defaulting to 1x if none has been set via `updateLeverage`).
|
|
546
|
+
*/
|
|
547
|
+
getActiveAssetData(objectId: string, market: string, applicationFeeTenthsBps?: number, leverage?: number): Promise<ActiveAssetData>;
|
|
548
|
+
/**
|
|
549
|
+
* Get the effective taker and maker fee rates for every tradeable asset on
|
|
550
|
+
* an exchange account. Rates include the account's volume tier, per-asset
|
|
551
|
+
* HIP-3 fee scale, platform fee, and optional builder fee.
|
|
552
|
+
*
|
|
553
|
+
* @param objectId - Exchange Arca object ID
|
|
554
|
+
* @param applicationFeeTenthsBps - Optional application fee in tenths of a basis point
|
|
555
|
+
*/
|
|
556
|
+
getAssetFees(objectId: string, applicationFeeTenthsBps?: number): Promise<AssetFeeEntry[]>;
|
|
557
|
+
/**
|
|
558
|
+
* Update leverage for a market on an exchange Arca object.
|
|
559
|
+
* Leverage is a per-market setting that applies to the entire position.
|
|
560
|
+
* Re-margins any existing position at the new leverage.
|
|
561
|
+
* Rejects if the account can't afford the increased margin when decreasing leverage.
|
|
562
|
+
*/
|
|
563
|
+
updateLeverage(opts: UpdateLeverageOptions): Promise<UpdateLeverageResponse>;
|
|
564
|
+
/**
|
|
565
|
+
* Get leverage settings for a market (or all coins) on an exchange Arca object.
|
|
566
|
+
*/
|
|
567
|
+
getLeverage(objectId: string, market?: string): Promise<LeverageSetting | LeverageSetting[]>;
|
|
568
|
+
/**
|
|
569
|
+
* Get all leverage settings for an exchange Arca object.
|
|
570
|
+
* Unlike getLeverage(), always returns an array.
|
|
571
|
+
*/
|
|
572
|
+
listLeverageSettings(objectId: string): Promise<LeverageSetting[]>;
|
|
573
|
+
/**
|
|
574
|
+
* Add or remove collateral from an isolated-margin position.
|
|
575
|
+
*
|
|
576
|
+
* Isolated positions carry their own dedicated collateral and are
|
|
577
|
+
* liquidated independently of the cross pool. A positive `amount` moves USD
|
|
578
|
+
* from the account's free balance into the position (lowering its
|
|
579
|
+
* liquidation price); a negative `amount` removes collateral (raising it).
|
|
580
|
+
* Removal is rejected if it would drop the position below its maintenance
|
|
581
|
+
* margin. Only valid on isolated positions.
|
|
582
|
+
*/
|
|
583
|
+
updateIsolatedMargin(opts: UpdateIsolatedMarginOptions): Promise<UpdateIsolatedMarginResponse>;
|
|
584
|
+
/**
|
|
585
|
+
* Switch an asset between cross and isolated margin for an exchange Arca
|
|
586
|
+
* object. Rejected on isolated-only (HIP-3) markets and while an open
|
|
587
|
+
* position exists for the asset — close the position first.
|
|
588
|
+
*/
|
|
589
|
+
setMarginMode(opts: SetMarginModeOptions): Promise<SetMarginModeResponse>;
|
|
590
|
+
/**
|
|
591
|
+
* Place an order on an exchange Arca object.
|
|
592
|
+
* The operation path serves as the idempotency key.
|
|
593
|
+
*
|
|
594
|
+
* Returns an OrderHandle: `await` waits for placement. Use `.filled()`,
|
|
595
|
+
* `.onFill()`, `.fills()` for fill lifecycle, and `.cancel()` to cancel.
|
|
596
|
+
*/
|
|
597
|
+
placeOrder(opts: PlaceOrderOptions): OrderHandle;
|
|
598
|
+
/**
|
|
599
|
+
* List orders for an exchange Arca object.
|
|
600
|
+
*/
|
|
601
|
+
listOrders(objectId: string, status?: string): Promise<SimOrder[]>;
|
|
602
|
+
/**
|
|
603
|
+
* Get a specific order with its fills.
|
|
604
|
+
*/
|
|
605
|
+
getOrder(objectId: string, orderId: string): Promise<SimOrderWithFills>;
|
|
606
|
+
/**
|
|
607
|
+
* Cancel an order on an exchange Arca object.
|
|
608
|
+
* The operation path serves as the idempotency key.
|
|
609
|
+
*/
|
|
610
|
+
cancelOrder(opts: CancelOrderOptions): OperationHandle<OrderOperationResponse>;
|
|
611
|
+
/**
|
|
612
|
+
* Attach a stop-loss to an open position.
|
|
613
|
+
*
|
|
614
|
+
* Places a position-attached trigger (`grouping: 'positionTpsl'`,
|
|
615
|
+
* `reduceOnly: true`) on the *closing* side inferred from the open position
|
|
616
|
+
* (`long` → sell, `short` → buy). The size tracks the position automatically:
|
|
617
|
+
* the venue fills it from the current position and resizes it as the
|
|
618
|
+
* position changes, cancelling it when the position closes or is liquidated.
|
|
619
|
+
* By default any existing stop-loss for the market is replaced (cancel + place).
|
|
620
|
+
*
|
|
621
|
+
* Requires an open position for `market` — throws `NotFoundError` otherwise.
|
|
622
|
+
*
|
|
623
|
+
* @example
|
|
624
|
+
* ```ts
|
|
625
|
+
* await arca.setStopLoss({
|
|
626
|
+
* path: "/wallets/main/tpsl/btc-sl",
|
|
627
|
+
* objectId,
|
|
628
|
+
* market: "hl:0:BTC",
|
|
629
|
+
* triggerPx: "58000",
|
|
630
|
+
* });
|
|
631
|
+
* ```
|
|
632
|
+
*/
|
|
633
|
+
setStopLoss(opts: SetPositionTriggerOptions): OrderHandle;
|
|
634
|
+
/**
|
|
635
|
+
* Attach a take-profit to an open position. The position-attached
|
|
636
|
+
* counterpart of {@link Arca.setStopLoss}; see it for lifecycle details.
|
|
637
|
+
*
|
|
638
|
+
* @example
|
|
639
|
+
* ```ts
|
|
640
|
+
* await arca.setTakeProfit({
|
|
641
|
+
* path: "/wallets/main/tpsl/btc-tp",
|
|
642
|
+
* objectId,
|
|
643
|
+
* market: "hl:0:BTC",
|
|
644
|
+
* triggerPx: "72000",
|
|
645
|
+
* });
|
|
646
|
+
* ```
|
|
647
|
+
*/
|
|
648
|
+
setTakeProfit(opts: SetPositionTriggerOptions): OrderHandle;
|
|
649
|
+
/**
|
|
650
|
+
* Attach a stop-loss and/or take-profit to an open position in one call.
|
|
651
|
+
* At least one of `stopLossPx` / `takeProfitPx` is required. Each leg is a
|
|
652
|
+
* `positionTpsl` order keyed off a derived sub-path (`<path>/sl`, `<path>/tp`).
|
|
653
|
+
* Legs are placed sequentially so a failed stop-loss surfaces before the
|
|
654
|
+
* take-profit is attempted.
|
|
655
|
+
*
|
|
656
|
+
* @example
|
|
657
|
+
* ```ts
|
|
658
|
+
* const { stopLoss, takeProfit } = await arca.setPositionTpsl({
|
|
659
|
+
* path: "/wallets/main/tpsl/btc",
|
|
660
|
+
* objectId,
|
|
661
|
+
* market: "hl:0:BTC",
|
|
662
|
+
* stopLossPx: "58000",
|
|
663
|
+
* takeProfitPx: "72000",
|
|
664
|
+
* });
|
|
665
|
+
* ```
|
|
666
|
+
*/
|
|
667
|
+
setPositionTpsl(opts: SetPositionTpslOptions): Promise<SetPositionTpslResult>;
|
|
668
|
+
/**
|
|
669
|
+
* Cancel resting position-attached (`positionTpsl`) TP/SL orders for a market.
|
|
670
|
+
* Pass `tpsl` to clear only the stop-loss or only the take-profit; omit it to
|
|
671
|
+
* clear both. Returns the orders that were cancelled (empty if none rest).
|
|
672
|
+
*
|
|
673
|
+
* @example
|
|
674
|
+
* ```ts
|
|
675
|
+
* await arca.clearPositionTpsl({ path: "/wallets/main/tpsl/btc-clear", objectId, market: "hl:0:BTC" });
|
|
676
|
+
* ```
|
|
677
|
+
*/
|
|
678
|
+
clearPositionTpsl(opts: ClearPositionTpslOptions): Promise<SimOrder[]>;
|
|
679
|
+
/** Internal: place one position-attached trigger (stop-loss or take-profit). */
|
|
680
|
+
private setPositionTrigger;
|
|
681
|
+
/**
|
|
682
|
+
* Internal: derive the closing side (and leverage / isolated) for a market
|
|
683
|
+
* from its open position. Mirrors the inference in {@link Arca.closePosition}.
|
|
684
|
+
* Throws `NotFoundError` when there is no open position.
|
|
685
|
+
*/
|
|
686
|
+
private inferPositionCloseParams;
|
|
687
|
+
/**
|
|
688
|
+
* Internal: list resting (WAITING_FOR_TRIGGER) `positionTpsl` orders for a
|
|
689
|
+
* market, optionally filtered to one TP/SL type.
|
|
690
|
+
*/
|
|
691
|
+
private findPositionTpslOrders;
|
|
692
|
+
/** Internal: the OrderHandle dependency bundle shared by order-placing methods. */
|
|
693
|
+
private orderHandleDeps;
|
|
694
|
+
/**
|
|
695
|
+
* Start a TWAP (Time-Weighted Average Price) order that executes a total size
|
|
696
|
+
* over a duration by placing market orders at regular intervals.
|
|
697
|
+
*
|
|
698
|
+
* @example
|
|
699
|
+
* ```ts
|
|
700
|
+
* const twap = await arca.placeTwap({
|
|
701
|
+
* exchangeId: "/exchanges/main",
|
|
702
|
+
* path: "/wallets/main/twap/btc-accumulate",
|
|
703
|
+
* market: "hl:0:BTC",
|
|
704
|
+
* side: "buy",
|
|
705
|
+
* totalSize: "10.0",
|
|
706
|
+
* durationMinutes: 120,
|
|
707
|
+
* intervalSeconds: 30,
|
|
708
|
+
* });
|
|
709
|
+
* console.log(twap.twap.status); // "active"
|
|
710
|
+
* ```
|
|
711
|
+
*/
|
|
712
|
+
placeTwap(opts: PlaceTwapOptions): OperationHandle<TwapOperationResponse>;
|
|
713
|
+
/**
|
|
714
|
+
* Cancel an active TWAP.
|
|
715
|
+
*/
|
|
716
|
+
cancelTwap(exchangeId: string, operationId: string): OperationHandle<TwapOperationResponse>;
|
|
717
|
+
/**
|
|
718
|
+
* Get TWAP status and progress by its parent operation ID.
|
|
719
|
+
*/
|
|
720
|
+
getTwap(exchangeId: string, operationId: string): Promise<TwapOperationResponse>;
|
|
721
|
+
/**
|
|
722
|
+
* List TWAPs for an exchange object.
|
|
723
|
+
* @param activeOnly - If true, only returns active TWAPs.
|
|
724
|
+
*/
|
|
725
|
+
listTwaps(exchangeId: string, activeOnly?: boolean): Promise<Twap[]>;
|
|
726
|
+
/**
|
|
727
|
+
* Watch a single TWAP by its parent operation ID. Returns a stream
|
|
728
|
+
* that emits the latest server-side {@link Twap} on every TWAP event
|
|
729
|
+
* targeting this operation (`twap.started`, `twap.progress`,
|
|
730
|
+
* `twap.completed`, `twap.cancelled`, `twap.failed`).
|
|
731
|
+
*
|
|
732
|
+
* The first snapshot is fetched eagerly via REST so `stream.twap` is
|
|
733
|
+
* populated immediately after `await stream.ready()`. Subsequent
|
|
734
|
+
* updates come from the WebSocket; if the connection drops the stream
|
|
735
|
+
* transitions to `reconnecting` and resumes once the socket
|
|
736
|
+
* reconnects. Closing the stream releases its filter listeners but
|
|
737
|
+
* does not close the underlying WebSocket.
|
|
738
|
+
*
|
|
739
|
+
* @example
|
|
740
|
+
* ```ts
|
|
741
|
+
* const stream = await arca.watchTwap(exchangeId, operationId);
|
|
742
|
+
* for await (const { twap } of stream) {
|
|
743
|
+
* console.log(`${twap.sliceCount}/${twap.expectedSliceCount}`,
|
|
744
|
+
* 'status:', twap.status);
|
|
745
|
+
* if (twap.status !== 'active') break;
|
|
746
|
+
* }
|
|
747
|
+
* ```
|
|
748
|
+
*/
|
|
749
|
+
watchTwap(exchangeId: string, operationId: string): Promise<TwapWatchStream>;
|
|
750
|
+
/**
|
|
751
|
+
* Get TWAP limits + recommendation curve from the server. The
|
|
752
|
+
* response is static for the process lifetime so the SDK caches it
|
|
753
|
+
* after the first call; bumping limits is a server-side change only.
|
|
754
|
+
* Use `getTwapLimits().recommendation.buckets` directly for custom
|
|
755
|
+
* pickers, or call {@link recommendedIntervalSeconds} for the
|
|
756
|
+
* one-shot helper that matches the iOS team's
|
|
757
|
+
* "5m/15m/1h" duration tiers.
|
|
758
|
+
*
|
|
759
|
+
* @example
|
|
760
|
+
* ```ts
|
|
761
|
+
* const { limits } = await arca.getTwapLimits();
|
|
762
|
+
* if (durationMinutes > limits.maxDurationMinutes) throw new Error('too long');
|
|
763
|
+
* ```
|
|
764
|
+
*/
|
|
765
|
+
getTwapLimits(): Promise<TwapLimits>;
|
|
766
|
+
/**
|
|
767
|
+
* Returns the recommended `intervalSeconds` for a given TWAP duration,
|
|
768
|
+
* picked from the server's recommendation curve. Use this to populate
|
|
769
|
+
* a default in your TWAP entry UI so retail-sized 1h TWAPs aren't
|
|
770
|
+
* sliced into 120 30-second orders.
|
|
771
|
+
*
|
|
772
|
+
* @example
|
|
773
|
+
* ```ts
|
|
774
|
+
* const intervalSeconds = await arca.recommendedIntervalSeconds(60); // 300 (5m)
|
|
775
|
+
* ```
|
|
776
|
+
*/
|
|
777
|
+
recommendedIntervalSeconds(durationMinutes: number): Promise<number>;
|
|
778
|
+
/**
|
|
779
|
+
* Get venue-wide order limits. Hyperliquid enforces a $10 minimum on
|
|
780
|
+
* `size * price` for every non-reduce-only order. Reduce-only orders and
|
|
781
|
+
* `positionTpsl` triggers are exempt so dust positions can always be
|
|
782
|
+
* closed. Use this to pre-validate {@link Arca.placeOrder} sizes.
|
|
783
|
+
*/
|
|
784
|
+
getOrderLimits(): OrderLimits;
|
|
785
|
+
/**
|
|
786
|
+
* List positions for an exchange Arca object.
|
|
787
|
+
*/
|
|
788
|
+
listPositions(objectId: string): Promise<SimPosition[]>;
|
|
789
|
+
/**
|
|
790
|
+
* Close an open position (fully or partially) with `reduceOnly` enforced.
|
|
791
|
+
*
|
|
792
|
+
* Looks up the current position for `opts.market`, infers the closing side,
|
|
793
|
+
* and places a market order sized to close the full position (or `opts.size`
|
|
794
|
+
* tokens if a partial close is desired). Always sets `reduceOnly: true` so
|
|
795
|
+
* the order can never accidentally open or increase a position.
|
|
796
|
+
*
|
|
797
|
+
* Automatically threads the position's `leverage` into the order body and
|
|
798
|
+
* sets `isolated: true` for isolated-only markets — those whose
|
|
799
|
+
* `marginModes` is `['isolated']` (equivalently the deprecated
|
|
800
|
+
* `onlyIsolated=true`), such as `hl:1:CL`. On Hyperliquid, isolated orders
|
|
801
|
+
* are bucketed by leverage — the matching engine refuses a close that
|
|
802
|
+
* doesn't identify the bucket. The iOS Quick Close fix proved this; we
|
|
803
|
+
* encode it once in the SDK so builders don't have to learn the rule. Pass
|
|
804
|
+
* `opts.isolated` or `opts.leverage` to override the auto-fill.
|
|
805
|
+
*
|
|
806
|
+
* Note: the margin mode is read from the asset's `marginModes`/`onlyIsolated`
|
|
807
|
+
* metadata, not from whether the market is HIP-3. HIP-3 is orthogonal — some
|
|
808
|
+
* HIP-3 markets (e.g. `hl:1:TSLA`) are cross-eligible.
|
|
809
|
+
*
|
|
810
|
+
* Returns an OrderHandle: `await` waits for placement. Use `.filled()`,
|
|
811
|
+
* `.onFill()`, `.fills()` for fill lifecycle, and `.cancel()` to cancel.
|
|
812
|
+
*/
|
|
813
|
+
closePosition(opts: ClosePositionOptions): OrderHandle;
|
|
814
|
+
/**
|
|
815
|
+
* List historical fills (trades) for an exchange Arca object.
|
|
816
|
+
* Returns paginated fill data with P&L, fees, and resulting position state.
|
|
817
|
+
*/
|
|
818
|
+
listFills(objectId: string, opts?: ListFillsOptions): Promise<FillListResponse>;
|
|
819
|
+
/**
|
|
820
|
+
* Watch fills (trade history) for an exchange Arca object.
|
|
821
|
+
* Resolves the object path from `objectId`, creates a path-scoped watch,
|
|
822
|
+
* then combines an initial REST snapshot with live `fill.previewed` and
|
|
823
|
+
* `fill.recorded` WebSocket events. Each update contains a platform-level
|
|
824
|
+
* `Fill` with P&L, fee breakdown, direction, and resulting position.
|
|
825
|
+
*
|
|
826
|
+
* For an activity-feed UI, read the already-merged `stream.fills` array.
|
|
827
|
+
* Subscribe via `stream.onUpdate(...)` only when you need the raw
|
|
828
|
+
* preview→recorded transition (e.g. an order-confirmation animation) — that
|
|
829
|
+
* stream emits both phases as separate events, and deduping by `Fill.id`
|
|
830
|
+
* does not work because the preview and recorded events use different ids.
|
|
831
|
+
*
|
|
832
|
+
* ```ts
|
|
833
|
+
* const stream = await arca.watchFills('obj_...');
|
|
834
|
+
* console.log(stream.fills); // merged list — one row per fill
|
|
835
|
+
* stream.onUpdate(({ fill }) => console.log('preview or recorded:', fill));
|
|
836
|
+
* // later: stream.close();
|
|
837
|
+
* ```
|
|
838
|
+
*/
|
|
839
|
+
watchFills(objectId: string, opts?: ListFillsOptions): Promise<FillWatchStream>;
|
|
840
|
+
/**
|
|
841
|
+
* Watch real-time funding payment events for an exchange Arca object.
|
|
842
|
+
* Resolves the object path from `objectId`, creates a path-scoped watch,
|
|
843
|
+
* then streams `exchange.funding` events. Each update includes the
|
|
844
|
+
* `FundingPayment` and its `EventEnvelope` for correlation tracing.
|
|
845
|
+
*
|
|
846
|
+
* ```ts
|
|
847
|
+
* const stream = await arca.watchFunding('obj_...');
|
|
848
|
+
* stream.onUpdate(({ payment, envelope }) => {
|
|
849
|
+
* console.log('funding:', payment.market, payment.payment, envelope.correlationId);
|
|
850
|
+
* });
|
|
851
|
+
* // later: stream.close();
|
|
852
|
+
* ```
|
|
853
|
+
*/
|
|
854
|
+
watchFunding(objectId: string): Promise<FundingWatchStream>;
|
|
855
|
+
/**
|
|
856
|
+
* Get per-market P&L aggregation for an exchange Arca object.
|
|
857
|
+
* Summarizes realized P&L, total fees, trade count, and volume by market.
|
|
858
|
+
*/
|
|
859
|
+
tradeSummary(objectId: string, opts?: TradeSummaryOptions): Promise<TradeSummaryResponse>;
|
|
860
|
+
/**
|
|
861
|
+
* Get market metadata (supported assets).
|
|
862
|
+
*/
|
|
863
|
+
getMarketMeta(): Promise<SimMetaResponse>;
|
|
864
|
+
/**
|
|
865
|
+
* Look up a single market by its **exact canonical market ID**
|
|
866
|
+
* (e.g. `"hl:0:BTC"`, `"hl:1:TSLA"`).
|
|
867
|
+
*
|
|
868
|
+
* This is an exact-id lookup — pass the `name` field of a {@link Market},
|
|
869
|
+
* not a bare symbol like `"BTC"`. To go from a human symbol to its
|
|
870
|
+
* market(s), use {@link resolveMarkets} / {@link resolveMarketOrThrow}.
|
|
871
|
+
*
|
|
872
|
+
* Lazily fetches and caches market metadata on first call. Subsequent
|
|
873
|
+
* calls return from cache without a network request.
|
|
874
|
+
*
|
|
875
|
+
* @example
|
|
876
|
+
* ```ts
|
|
877
|
+
* const btc = await arca.market("hl:0:BTC");
|
|
878
|
+
* console.log(btc?.symbol); // "BTC"
|
|
879
|
+
* console.log(btc?.displayName); // undefined
|
|
880
|
+
* console.log(btc?.logoUrl); // "https://...-128.webp" (default 128px)
|
|
881
|
+
* console.log(btc?.logoSources); // [{ url: "...", width: 256, format: "webp" }, ...]
|
|
882
|
+
* ```
|
|
883
|
+
*
|
|
884
|
+
* @param id - Canonical market ID (the `name` field on {@link Market}).
|
|
885
|
+
* @returns The matching {@link Market}, or `undefined` if not found.
|
|
886
|
+
*/
|
|
887
|
+
market(id: string): Promise<Market | undefined>;
|
|
888
|
+
/**
|
|
889
|
+
* Resolve a human **symbol** (e.g. `"BTC"`, `"TSLA"`) to the market(s) that
|
|
890
|
+
* carry it, returning an **array** because one symbol can legitimately map
|
|
891
|
+
* to many markets across exchanges and HIP-3 dexes (e.g. a native `BTC` and
|
|
892
|
+
* a builder-deployed `BTC` on a different dex).
|
|
893
|
+
*
|
|
894
|
+
* This never fails silently: an empty array is an explicit "no market has
|
|
895
|
+
* this symbol", not a guess. Match is **exact and case-sensitive** on the
|
|
896
|
+
* {@link Market.symbol} field (`"kSHIB"` ≠ `"KSHIB"`). Narrow ambiguous
|
|
897
|
+
* symbols with the optional `exchange` / `dex` filters.
|
|
898
|
+
*
|
|
899
|
+
* For the "I expect exactly one" case, use {@link resolveMarketOrThrow}.
|
|
900
|
+
* If you already hold a canonical id, use {@link market} instead.
|
|
901
|
+
*
|
|
902
|
+
* @example
|
|
903
|
+
* ```ts
|
|
904
|
+
* const all = await arca.resolveMarkets("BTC"); // every BTC market
|
|
905
|
+
* const hlOnly = await arca.resolveMarkets("BTC", { exchange: "hl" });
|
|
906
|
+
* const tsla = await arca.resolveMarkets("TSLA", { dex: "xyz" });
|
|
907
|
+
* ```
|
|
908
|
+
*
|
|
909
|
+
* @param symbol - Display symbol to resolve (the `symbol` field on {@link Market}).
|
|
910
|
+
* @param opts - Optional `exchange` / `dex` filters.
|
|
911
|
+
* @returns All matching markets; an empty array when none match.
|
|
912
|
+
*/
|
|
913
|
+
resolveMarkets(symbol: string, opts?: {
|
|
914
|
+
exchange?: string;
|
|
915
|
+
dex?: string;
|
|
916
|
+
}): Promise<Market[]>;
|
|
917
|
+
/**
|
|
918
|
+
* Resolve a human **symbol** to the single market that carries it, throwing
|
|
919
|
+
* when the result is not exactly one.
|
|
920
|
+
*
|
|
921
|
+
* Use this when your code assumes a symbol is unambiguous (often after
|
|
922
|
+
* narrowing with `exchange` / `dex`). Throws a {@link ValidationError} when
|
|
923
|
+
* zero markets match (so a typo never silently no-ops) and when more than
|
|
924
|
+
* one matches (so an ambiguous symbol never silently picks the wrong one).
|
|
925
|
+
*
|
|
926
|
+
* @example
|
|
927
|
+
* ```ts
|
|
928
|
+
* const btc = await arca.resolveMarketOrThrow("BTC", { exchange: "hl" });
|
|
929
|
+
* await arca.placeOrder({ market: btc.name, ... });
|
|
930
|
+
* ```
|
|
931
|
+
*
|
|
932
|
+
* @param symbol - Display symbol to resolve (the `symbol` field on {@link Market}).
|
|
933
|
+
* @param opts - Optional `exchange` / `dex` filters.
|
|
934
|
+
* @returns The single matching {@link Market}.
|
|
935
|
+
* @throws {ValidationError} when zero or more than one market matches.
|
|
936
|
+
*/
|
|
937
|
+
resolveMarketOrThrow(symbol: string, opts?: {
|
|
938
|
+
exchange?: string;
|
|
939
|
+
dex?: string;
|
|
940
|
+
}): Promise<Market>;
|
|
941
|
+
/**
|
|
942
|
+
* Eagerly fetch and cache market metadata.
|
|
943
|
+
*
|
|
944
|
+
* Call at app startup to avoid latency on the first `market()` call.
|
|
945
|
+
* Safe to call multiple times — skips the fetch if already cached.
|
|
946
|
+
*/
|
|
947
|
+
preloadMarketMeta(): Promise<void>;
|
|
948
|
+
/**
|
|
949
|
+
* Force re-fetch market metadata, replacing the cache.
|
|
950
|
+
*
|
|
951
|
+
* Use after a new asset is listed or when metadata may have changed.
|
|
952
|
+
*/
|
|
953
|
+
refreshMarketMeta(): Promise<void>;
|
|
954
|
+
private ensureMetaLoaded;
|
|
955
|
+
/**
|
|
956
|
+
* Get current mid prices for all assets.
|
|
957
|
+
*/
|
|
958
|
+
getMarketMids(): Promise<SimMidsResponse>;
|
|
959
|
+
/**
|
|
960
|
+
* Get 24h ticker data for all assets (volume, price change, funding, delisted status).
|
|
961
|
+
*/
|
|
962
|
+
getMarketTickers(): Promise<MarketTickersResponse>;
|
|
963
|
+
/**
|
|
964
|
+
* Get L2 order book for a specific market.
|
|
965
|
+
*/
|
|
966
|
+
getOrderBook(market: string): Promise<SimBookResponse>;
|
|
967
|
+
/**
|
|
968
|
+
* Get OHLCV candle data for a specific market.
|
|
969
|
+
*
|
|
970
|
+
* When `candleCdnBaseUrl` is configured, finalized historical chunks are
|
|
971
|
+
* fetched directly from the CDN. The current (in-progress) period and any
|
|
972
|
+
* chunks not yet published fall back to the REST API transparently.
|
|
973
|
+
*
|
|
974
|
+
* `market` must be a canonical market id (e.g. `"hl:0:BTC"`, `"hl:1:TSLA"`) — not
|
|
975
|
+
* a bare symbol (`"TSLA"`), display name (`"Tesla"`), or Hyperliquid
|
|
976
|
+
* named-deployer id (`"xyz:TSLA"`). A non-canonical id matches no market and
|
|
977
|
+
* returns an empty array.
|
|
978
|
+
*/
|
|
979
|
+
getCandles(market: string, interval: CandleInterval, options?: {
|
|
980
|
+
startTime?: number;
|
|
981
|
+
endTime?: number;
|
|
982
|
+
skipBackfill?: boolean;
|
|
983
|
+
}): Promise<CandlesResponse>;
|
|
984
|
+
/**
|
|
985
|
+
* Get sparkline close-price arrays for all tracked coins in a single request.
|
|
986
|
+
* Returns a map of market name to an array of 24 hourly close prices.
|
|
987
|
+
* Sparkline data is pre-computed every ~5 minutes; for real-time prices
|
|
988
|
+
* use {@link watchPrices}.
|
|
989
|
+
*
|
|
990
|
+
* @param _interval - Ignored (sparklines always use 1h interval)
|
|
991
|
+
* @param _points - Ignored (sparklines always return 24 data points)
|
|
992
|
+
*/
|
|
993
|
+
getSparklines(_interval?: CandleInterval, _points?: number): Promise<SparklinesResponse>;
|
|
994
|
+
/**
|
|
995
|
+
* Subscribe to real-time mid prices.
|
|
996
|
+
*
|
|
997
|
+
* The typical pattern is: call once at app startup, then read
|
|
998
|
+
* `stream.get('hl:0:BTC')` (or `stream.prices['hl:0:BTC']`) any time you
|
|
999
|
+
* need the current price of an asset. The server pushes a snapshot on
|
|
1000
|
+
* subscribe (and again after any reconnect), so `.prices` is always
|
|
1001
|
+
* populated by the time the returned promise resolves.
|
|
1002
|
+
*
|
|
1003
|
+
* @example
|
|
1004
|
+
* // Read on demand — simplest usage
|
|
1005
|
+
* const prices = await arca.watchPrices();
|
|
1006
|
+
* const btc = prices.get('hl:0:BTC'); // decimal string, or undefined
|
|
1007
|
+
*
|
|
1008
|
+
* @example
|
|
1009
|
+
* // Narrow to specific assets to reduce bandwidth
|
|
1010
|
+
* const prices = await arca.watchPrices({ coins: ['hl:0:BTC', 'hl:0:ETH'] });
|
|
1011
|
+
*
|
|
1012
|
+
* @example
|
|
1013
|
+
* // React to every tick
|
|
1014
|
+
* const prices = await arca.watchPrices();
|
|
1015
|
+
* prices.onUpdate((next) => render(next));
|
|
1016
|
+
*
|
|
1017
|
+
* @example
|
|
1018
|
+
* // Bound the initial wait so startup doesn't hang if the backend is down
|
|
1019
|
+
* const prices = await arca.watchPrices({ readyTimeoutMs: 5000 });
|
|
1020
|
+
*
|
|
1021
|
+
* @param opts - Either an options object, or (legacy) an exchange string.
|
|
1022
|
+
* - `exchange` — Exchange identifier. Default: `"sim"`.
|
|
1023
|
+
* - `coins` — Optional canonical market IDs to narrow the subscription
|
|
1024
|
+
* (e.g. `["hl:0:BTC", "hl:0:ETH"]`). Omit for all assets.
|
|
1025
|
+
* - `readyTimeoutMs` — Max time to wait for the initial snapshot.
|
|
1026
|
+
* Throws `WatchStreamReadyTimeoutError` on timeout. The stream is
|
|
1027
|
+
* torn down on timeout; it will not keep trying in the background.
|
|
1028
|
+
*
|
|
1029
|
+
* @returns A {@link PriceWatchStream}. Call `.close()` when done.
|
|
1030
|
+
*/
|
|
1031
|
+
watchPrices(opts?: string | WatchPricesOptions): Promise<PriceWatchStream>;
|
|
1032
|
+
/**
|
|
1033
|
+
* Watch real-time operation events under a path prefix.
|
|
1034
|
+
* Creates a path-scoped watch; server sends a `watch_snapshot` with
|
|
1035
|
+
* recent operations, then streams `operation.created` / `operation.updated`.
|
|
1036
|
+
* Returns an {@link OperationWatchStream}. Call `.close()` when done.
|
|
1037
|
+
*
|
|
1038
|
+
* @param path - Arca path prefix to watch (default: "/" for all operations)
|
|
1039
|
+
* @param options.maxOperations - Maximum number of operations to keep in memory (default 500)
|
|
1040
|
+
*/
|
|
1041
|
+
watchOperations(path?: string, options?: {
|
|
1042
|
+
maxOperations?: number;
|
|
1043
|
+
}): Promise<OperationWatchStream>;
|
|
1044
|
+
/**
|
|
1045
|
+
* Watch real-time balance updates under a path prefix.
|
|
1046
|
+
* Creates a path-scoped watch; server sends a `watch_snapshot` with
|
|
1047
|
+
* current balances (four-bucket summary), then streams `balance.updated`.
|
|
1048
|
+
* Call `.close()` when done.
|
|
1049
|
+
*
|
|
1050
|
+
* @param path - Arca path prefix to watch (default: "/" for all balances)
|
|
1051
|
+
*/
|
|
1052
|
+
watchBalances(path?: string): Promise<BalanceWatchStream>;
|
|
1053
|
+
/**
|
|
1054
|
+
* Get the valuation for a single Arca object (Axiom 10: same computation
|
|
1055
|
+
* path as aggregation, ensuring perfect additivity).
|
|
1056
|
+
*/
|
|
1057
|
+
getObjectValuation(path: string): Promise<ObjectValuation>;
|
|
1058
|
+
/**
|
|
1059
|
+
* Watch real-time valuation updates for a single Arca object.
|
|
1060
|
+
* Creates a path-scoped watch with an aggregation watch for valuation;
|
|
1061
|
+
* server sends `watch_snapshot` with initial valuation, then streams
|
|
1062
|
+
* `object.valuation` events. Uses the same computation path as
|
|
1063
|
+
* aggregation watches (Axiom 10). Call `.close()` when done.
|
|
1064
|
+
*
|
|
1065
|
+
* @param path - Arca object path (e.g. "/users/alice/main")
|
|
1066
|
+
*/
|
|
1067
|
+
watchObject(path: string): Promise<ObjectWatchStream>;
|
|
1068
|
+
/**
|
|
1069
|
+
* Watch real-time valuations for multiple Arca objects simultaneously.
|
|
1070
|
+
* Each path gets its own ObjectWatchStream; updates from any object emit
|
|
1071
|
+
* a merged `Map<path, ObjectValuation>` to subscribers.
|
|
1072
|
+
* Call `.close()` to stop all watches.
|
|
1073
|
+
*
|
|
1074
|
+
* @param paths - Array of object paths (e.g. ["/users/alice/main", "/users/bob/main"])
|
|
1075
|
+
*/
|
|
1076
|
+
watchObjects(paths: string[]): Promise<ObjectsWatchStream>;
|
|
1077
|
+
/**
|
|
1078
|
+
* Subscribe to a live, SDK-derived max order size stream for a market/side.
|
|
1079
|
+
* Uses `getExchangeState` + `watchPrices` and recomputes on price changes;
|
|
1080
|
+
* submit/retry remains backend-authoritative.
|
|
1081
|
+
*
|
|
1082
|
+
* The per-asset `maintenanceMarginRate`, `marginTiers` (the laddered
|
|
1083
|
+
* initial-margin schedule the server enforces at placement), and the
|
|
1084
|
+
* top-of-book spread (`bidRatio`/`askRatio`) are auto-fetched once via
|
|
1085
|
+
* `getActiveAssetData` and fed into the stream, so the previewed max accounts
|
|
1086
|
+
* for tiered margin on assets like BTC and for the directional execution
|
|
1087
|
+
* price (buys at the ask, sells at the bid). Each input is resolved
|
|
1088
|
+
* independently; pass all four in `opts` to skip the lookup entirely.
|
|
1089
|
+
* Supplying only `maintenanceMarginRate` + `marginTiers` still fetches the
|
|
1090
|
+
* spread rather than silently sizing at the mid.
|
|
1091
|
+
*
|
|
1092
|
+
* `maxBuyUsd`/`maxSellUsd` are a best-effort estimate (fees + tiered margin +
|
|
1093
|
+
* a ~10 bps buffer), not a hard guarantee — mids move between preview and
|
|
1094
|
+
* submission. To place exactly the max, prefer `placeOrder({ useMax: true })`
|
|
1095
|
+
* or a small `sizeTolerance` so the server resolves the size atomically.
|
|
1096
|
+
*/
|
|
1097
|
+
watchMaxOrderSize(opts: MaxOrderSizeWatchOptions): Promise<MaxOrderSizeWatchStream>;
|
|
1098
|
+
/**
|
|
1099
|
+
* Subscribe to real-time candle updates.
|
|
1100
|
+
* Call `.close()` when done.
|
|
1101
|
+
*
|
|
1102
|
+
* @param coins - Coins in canonical format (e.g. ["hl:0:BTC", "hl:0:ETH"])
|
|
1103
|
+
* @param intervals - Candle intervals (e.g. ["1m", "5m"])
|
|
1104
|
+
*/
|
|
1105
|
+
watchCandles(coins: string[], intervals: CandleInterval[]): Promise<CandleWatchStream>;
|
|
1106
|
+
/**
|
|
1107
|
+
* Subscribe to real-time market trades for the given coins.
|
|
1108
|
+
* Returns a {@link TradeWatchStream} that emits each trade as it happens.
|
|
1109
|
+
* Call `.close()` when done.
|
|
1110
|
+
*
|
|
1111
|
+
* @param coins - Coins in canonical format (e.g. `["hl:0:BTC", "hl:0:ETH"]`)
|
|
1112
|
+
*/
|
|
1113
|
+
watchTrades(coins: string[]): Promise<TradeWatchStream>;
|
|
1114
|
+
/**
|
|
1115
|
+
* Create a live candle chart that merges historical candle data with
|
|
1116
|
+
* real-time WebSocket updates. The candle array stays sorted and deduped;
|
|
1117
|
+
* new bars appear automatically as candle events arrive.
|
|
1118
|
+
*
|
|
1119
|
+
* Use `stream.ensureRange(start, end)` when the chart viewport changes
|
|
1120
|
+
* (zoom, resize, scroll, jump to date) — the SDK tracks which ranges
|
|
1121
|
+
* have been fetched and only requests the gaps. Use `stream.loadMore()`
|
|
1122
|
+
* for simple backward scrolling.
|
|
1123
|
+
*
|
|
1124
|
+
* @param market - Canonical market ID (e.g. `"hl:0:BTC"`, `"hl:1:BRENTOIL"`)
|
|
1125
|
+
* @param interval - Candle interval (e.g. `"1m"`, `"5m"`)
|
|
1126
|
+
* @param options - Optional `{ count }` for initial history (default 300)
|
|
1127
|
+
*/
|
|
1128
|
+
watchCandleChart(market: string, interval: CandleInterval, options?: {
|
|
1129
|
+
count?: number;
|
|
1130
|
+
}): Promise<CandleChartStream>;
|
|
1131
|
+
/**
|
|
1132
|
+
* Watch the exchange state for an exchange Arca object, including positions,
|
|
1133
|
+
* open orders, and pending intents (order operations in flight).
|
|
1134
|
+
* Resolves the object path from `objectId` and creates a path-scoped watch.
|
|
1135
|
+
*
|
|
1136
|
+
* Pending intents are the exchange equivalent of transfer holds: they signal
|
|
1137
|
+
* that an order has been submitted but the venue hasn't confirmed it yet.
|
|
1138
|
+
* Use `stream.pendingIntents` to show in-progress state in the UI.
|
|
1139
|
+
*/
|
|
1140
|
+
watchExchangeState(objectId: string): Promise<ExchangeWatchStream>;
|
|
1141
|
+
private _autoTrackOps?;
|
|
1142
|
+
private _autoTrackBal?;
|
|
1143
|
+
private _autoTrackExchange?;
|
|
1144
|
+
/**
|
|
1145
|
+
* Enable automatic optimistic tracking: every mutation method will
|
|
1146
|
+
* immediately reflect its predicted effects on the registered streams.
|
|
1147
|
+
*
|
|
1148
|
+
* - `operationStream`: gets a `trackSubmission` call for each mutation,
|
|
1149
|
+
* showing `submitting → pending → completed/failed`.
|
|
1150
|
+
* - `balanceStream`: gets an `applyPrediction` call for transfers,
|
|
1151
|
+
* immediately showing `departing` and `arriving` amounts.
|
|
1152
|
+
* - `exchangeStream` (optional): exchange intents are already backend-driven
|
|
1153
|
+
* and don't require client-side prediction, but registering allows future
|
|
1154
|
+
* client-side enrichment.
|
|
1155
|
+
*/
|
|
1156
|
+
enableAutoTracking(operationStream?: OperationWatchStream, balanceStream?: BalanceWatchStream, exchangeStream?: ExchangeWatchStream): void;
|
|
1157
|
+
/**
|
|
1158
|
+
* Disable automatic tracking.
|
|
1159
|
+
*/
|
|
1160
|
+
disableAutoTracking(): void;
|
|
1161
|
+
/**
|
|
1162
|
+
* Run all DB-only invariant checks (I1-I6) via the internal API.
|
|
1163
|
+
* Returns structured results per invariant with pass/fail and violations.
|
|
1164
|
+
*
|
|
1165
|
+
* Accepts either a numeric `limit` (legacy positional form) or an options
|
|
1166
|
+
* object. When `realmId` is provided every invariant query is scoped to
|
|
1167
|
+
* that realm, which is dramatically faster than the default platform-wide
|
|
1168
|
+
* scan as the platform grows. The 5-min platform maintenance cron uses
|
|
1169
|
+
* the un-scoped form; per-realm callers (e.g. the regression suite) should
|
|
1170
|
+
* pass `{ realmId }`.
|
|
1171
|
+
*/
|
|
1172
|
+
checkInvariants(opts?: number | {
|
|
1173
|
+
limit?: number;
|
|
1174
|
+
realmId?: string;
|
|
1175
|
+
}): Promise<InvariantCheckResponse>;
|
|
1176
|
+
/**
|
|
1177
|
+
* Wait until all operations in the realm have reached a terminal state.
|
|
1178
|
+
* Uses WebSocket events to react to completions instantly, with periodic
|
|
1179
|
+
* HTTP polls as a safety net.
|
|
1180
|
+
*
|
|
1181
|
+
* @param opts.intervalMs - Safety-net poll interval in ms (default: 5000)
|
|
1182
|
+
* @param opts.timeoutMs - Max wait time in ms (default: 120000)
|
|
1183
|
+
* @param opts.onPoll - Optional callback with the current pending count
|
|
1184
|
+
* @returns The number of polls performed
|
|
1185
|
+
*/
|
|
1186
|
+
waitForQuiescence(opts?: {
|
|
1187
|
+
intervalMs?: number;
|
|
1188
|
+
timeoutMs?: number;
|
|
1189
|
+
onPoll?: (pendingCount: number) => void;
|
|
1190
|
+
}): Promise<number>;
|
|
1191
|
+
private _resolutionStats;
|
|
1192
|
+
/**
|
|
1193
|
+
* Returns how many operations were resolved via each path.
|
|
1194
|
+
* Useful for benchmarking and diagnostics — a high `poll` count
|
|
1195
|
+
* indicates WebSocket events are being missed.
|
|
1196
|
+
*/
|
|
1197
|
+
getResolutionStats(): {
|
|
1198
|
+
ws: number;
|
|
1199
|
+
poll: number;
|
|
1200
|
+
initial: number;
|
|
1201
|
+
};
|
|
1202
|
+
/** Resets the resolution stats counters to zero. */
|
|
1203
|
+
resetResolutionStats(): void;
|
|
1204
|
+
/**
|
|
1205
|
+
* Wait for a specific operation to reach a terminal state (completed or failed).
|
|
1206
|
+
*
|
|
1207
|
+
* Auto-connects the WebSocket and subscribes to the operations channel
|
|
1208
|
+
* so callers don't need to manage the connection manually.
|
|
1209
|
+
* If the WS event arrives without embedded operation data (enrichment failure),
|
|
1210
|
+
* fetches the operation via HTTP as a fallback.
|
|
1211
|
+
*
|
|
1212
|
+
* @param operationId - The operation ID to wait for
|
|
1213
|
+
* @param timeoutMs - Maximum time to wait (default 30s)
|
|
1214
|
+
* @throws {OperationFailedError} if the operation reaches a failed state
|
|
1215
|
+
*/
|
|
1216
|
+
waitForOperation(operationId: string, timeoutMs?: number): Promise<Operation>;
|
|
1217
|
+
/**
|
|
1218
|
+
* Get the custody status for this realm, including contract address,
|
|
1219
|
+
* total balance, all boundaries, exchange arcas, and venue halts.
|
|
1220
|
+
*/
|
|
1221
|
+
getCustodyStatus(): Promise<CustodyStatus>;
|
|
1222
|
+
/**
|
|
1223
|
+
* Get a single isolation boundary by ID.
|
|
1224
|
+
*/
|
|
1225
|
+
getBoundary(boundaryId: string): Promise<CustodyBoundary>;
|
|
1226
|
+
/**
|
|
1227
|
+
* List all isolation boundaries for this realm.
|
|
1228
|
+
*/
|
|
1229
|
+
listBoundaries(): Promise<CustodyBoundary[]>;
|
|
1230
|
+
/**
|
|
1231
|
+
* List exchange arcas, optionally filtered to a specific boundary.
|
|
1232
|
+
*/
|
|
1233
|
+
listExchangeArcas(boundaryId?: string): Promise<CustodyExchangeArca[]>;
|
|
1234
|
+
/**
|
|
1235
|
+
* Register a recovery key for an isolation boundary.
|
|
1236
|
+
* This is an operator-initiated action (valid only when no recovery key is set).
|
|
1237
|
+
* After registration, only the recovery key holder can lock/unlock/withdraw.
|
|
1238
|
+
*
|
|
1239
|
+
* The wallet address is typically generated client-side via `Arca.generateRecoveryKey()`
|
|
1240
|
+
* or provided by the user from an existing wallet.
|
|
1241
|
+
*/
|
|
1242
|
+
registerRecoveryKey(opts: RegisterRecoveryKeyOptions): Promise<RegisterRecoveryKeyResponse>;
|
|
1243
|
+
/**
|
|
1244
|
+
* Prepare an unsigned `lockBoundary` transaction.
|
|
1245
|
+
* The caller signs and submits this transaction from their recovery key wallet.
|
|
1246
|
+
* Locking freezes all operator fund movement and cancels any pending exit.
|
|
1247
|
+
*/
|
|
1248
|
+
prepareLockBoundary(contractAddress: string, chainId: number, boundaryId: string): PreparedCustodyTransaction;
|
|
1249
|
+
/**
|
|
1250
|
+
* Prepare an unsigned `unlockBoundary` transaction.
|
|
1251
|
+
* Only the actor who locked the boundary can unlock it.
|
|
1252
|
+
*/
|
|
1253
|
+
prepareUnlockBoundary(contractAddress: string, chainId: number, boundaryId: string): PreparedCustodyTransaction;
|
|
1254
|
+
/**
|
|
1255
|
+
* Prepare an unsigned `withdraw` transaction.
|
|
1256
|
+
* Withdraws the entire boundary balance to the recovery key holder.
|
|
1257
|
+
* Requires: boundary is locked by the caller, caller is recovery key holder.
|
|
1258
|
+
*/
|
|
1259
|
+
prepareWithdraw(contractAddress: string, chainId: number, boundaryId: string): PreparedCustodyTransaction;
|
|
1260
|
+
/**
|
|
1261
|
+
* Prepare an unsigned `assignRecoveryKey` transaction for changing an existing key.
|
|
1262
|
+
* When the boundary already has a recovery key, only the current holder can change it.
|
|
1263
|
+
* For initial assignment (no existing key), use `registerRecoveryKey()` instead.
|
|
1264
|
+
*/
|
|
1265
|
+
prepareAssignRecoveryKey(contractAddress: string, chainId: number, boundaryId: string, newRecoveryKey: string): PreparedCustodyTransaction;
|
|
1266
|
+
/**
|
|
1267
|
+
* Prepare an unsigned `setTimeLock` transaction.
|
|
1268
|
+
* Recovery key holders can only increase the time lock; never decrease.
|
|
1269
|
+
*/
|
|
1270
|
+
prepareSetTimeLock(contractAddress: string, chainId: number, boundaryId: string, durationSeconds: number): PreparedCustodyTransaction;
|
|
1271
|
+
/**
|
|
1272
|
+
* Prepare an unsigned `cancelPendingExit` transaction.
|
|
1273
|
+
* Can be called by recovery key holder or operator.
|
|
1274
|
+
*/
|
|
1275
|
+
prepareCancelPendingExit(contractAddress: string, chainId: number, boundaryId: string): PreparedCustodyTransaction;
|
|
1276
|
+
/**
|
|
1277
|
+
* Prepare an unsigned `recoveryWithdrawAccount` transaction.
|
|
1278
|
+
* Sweeps an exchange arca's balance back to its boundary.
|
|
1279
|
+
* Requires: boundary is locked by the recovery key holder.
|
|
1280
|
+
*/
|
|
1281
|
+
prepareRecoveryWithdrawAccount(contractAddress: string, chainId: number, arcaId: string): PreparedCustodyTransaction;
|
|
1282
|
+
/**
|
|
1283
|
+
* Generate a recovery key pair entirely client-side.
|
|
1284
|
+
*
|
|
1285
|
+
* Creates a 12-word BIP-39 mnemonic using the platform CSPRNG
|
|
1286
|
+
* (`crypto.getRandomValues`) and derives the Ethereum address at the
|
|
1287
|
+
* standard BIP-44 path (`m/44'/60'/0'/0/0`). No network call is made;
|
|
1288
|
+
* the mnemonic never leaves the caller's process.
|
|
1289
|
+
*
|
|
1290
|
+
* All intermediate cryptographic material (seed, private key bytes) is
|
|
1291
|
+
* zeroed after derivation. The mnemonic itself is a JavaScript string and
|
|
1292
|
+
* cannot be reliably erased from memory — for environments requiring
|
|
1293
|
+
* guaranteed zeroization, generate the key in a native module or secure
|
|
1294
|
+
* enclave and pass only the derived address to {@link registerRecoveryKey}.
|
|
1295
|
+
*
|
|
1296
|
+
* **Two-path UX recommendation**: most users already have an Ethereum
|
|
1297
|
+
* wallet (MetaMask, Phantom, Ledger, etc.). Prefer letting them paste or
|
|
1298
|
+
* connect an existing address via {@link registerRecoveryKey}. Reserve
|
|
1299
|
+
* this method for users who need a new wallet generated for them.
|
|
1300
|
+
*
|
|
1301
|
+
* @example
|
|
1302
|
+
* ```typescript
|
|
1303
|
+
* // Path A: user already has a wallet — just register the address
|
|
1304
|
+
* await arca.registerRecoveryKey({
|
|
1305
|
+
* boundaryId: 'b0',
|
|
1306
|
+
* walletAddress: '0x1234...abcd', // from WalletConnect, paste, etc.
|
|
1307
|
+
* });
|
|
1308
|
+
*
|
|
1309
|
+
* // Path B: generate a new recovery wallet
|
|
1310
|
+
* const recovery = Arca.generateRecoveryKey();
|
|
1311
|
+
* // Show recovery.mnemonic to the user — they MUST back it up
|
|
1312
|
+
* await arca.registerRecoveryKey({
|
|
1313
|
+
* boundaryId: 'b0',
|
|
1314
|
+
* walletAddress: recovery.address,
|
|
1315
|
+
* });
|
|
1316
|
+
* ```
|
|
1317
|
+
*/
|
|
1318
|
+
static generateRecoveryKey(): GeneratedRecoveryKey;
|
|
1319
|
+
/**
|
|
1320
|
+
* Wrap a mutation HTTP call in an OperationHandle.
|
|
1321
|
+
* Defers ready() + throwIfOperationFailed into the promise chain.
|
|
1322
|
+
*/
|
|
1323
|
+
private op;
|
|
1324
|
+
private realmId;
|
|
1325
|
+
private throwIfOperationFailed;
|
|
1326
|
+
private extractRealmAndScheduleRefresh;
|
|
1327
|
+
/**
|
|
1328
|
+
* Call the token provider, deduplicate concurrent calls, apply the new token,
|
|
1329
|
+
* and schedule the next proactive refresh.
|
|
1330
|
+
*/
|
|
1331
|
+
private refreshTokenFromProvider;
|
|
1332
|
+
private applyNewToken;
|
|
1333
|
+
private scheduleProactiveRefresh;
|
|
1334
|
+
/**
|
|
1335
|
+
* Release resources associated with this Arca client.
|
|
1336
|
+
* Clears any proactive token refresh timers and disconnects the WebSocket.
|
|
1337
|
+
* Useful for teardown in short-lived processes or tests.
|
|
1338
|
+
*/
|
|
1339
|
+
dispose(): void;
|
|
1340
|
+
private emitAuthError;
|
|
1341
|
+
private resolveRealm;
|
|
1342
|
+
}
|
|
1343
|
+
//# sourceMappingURL=arca.d.ts.map
|