@arca-network/sdk 2.14.0 → 2.16.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/dist/types.d.ts CHANGED
@@ -59,6 +59,13 @@ export type RealmBacking = 'chain' | 'ledger-only';
59
59
  export interface RealmSettings {
60
60
  /** Default application fee in tenths of a basis point (e.g. 40 = 4.0 bps) */
61
61
  defaultApplicationFeeTenthsBps?: number | null;
62
+ /**
63
+ * Browser origins (e.g. `https://app.example.com`) whose pages may call the
64
+ * REST API with a token locked to this realm (a scoped token or a
65
+ * realm-locked API key). `http://localhost:<port>` is accepted on paper
66
+ * realms. Omit to leave unchanged; pass `[]` to clear.
67
+ */
68
+ allowedOrigins?: string[];
62
69
  }
63
70
  export interface Realm {
64
71
  id: RealmId;
@@ -863,7 +870,11 @@ export interface PathAggregation {
863
870
  export interface RealmProjection {
864
871
  realmId: string;
865
872
  name: string;
866
- /** Projectable fields: `equity`, `realizedValue`, `unrealizedValue`, `positions`. */
873
+ /**
874
+ * Projectable fields: `equity`, `realizedValue`, `unrealizedValue`,
875
+ * `positions`, and the windowed figures `pnl` and `volume` (served only
876
+ * to a read or watch that asks for a `window`).
877
+ */
867
878
  fields: string[];
868
879
  /** Path patterns (exact path, `"*"`, or trailing `"/prefix/*"`). */
869
880
  resources: string[];
@@ -916,11 +927,80 @@ export interface ProjectedValuation {
916
927
  unrealizedValue?: string | null;
917
928
  /** Open positions (projection field `positions`). */
918
929
  positions?: PositionValue[] | null;
930
+ /**
931
+ * P&L over the rolling window (projection field `pnl`). Present only
932
+ * when the projection grants `pnl` and the read or watch asked for a
933
+ * `window`. Re-marked with `equity` between server deltas.
934
+ */
935
+ pnl?: ProjectedPnl;
936
+ /**
937
+ * Traded volume over the rolling window (projection field `volume`).
938
+ * Present only when the projection grants `volume` and the read or watch
939
+ * asked for a `window`. Never re-marked: a price move does not change
940
+ * past volume.
941
+ */
942
+ volume?: ProjectedVolume;
943
+ }
944
+ /** A rolling window a projection read or watch can ask for. */
945
+ export type ProjectionWindow = '30d';
946
+ /**
947
+ * Readiness of one windowed figure. `complete`: the value covers the whole
948
+ * window. `incomplete` (P&L only): a mark was missing at `from` or now, so
949
+ * the value understates or overstates. `pending`: not computed yet; the
950
+ * value is omitted so it can never read as zero. Unknown values from a
951
+ * newer server pass through as strings.
952
+ */
953
+ export type WindowedStatus = 'complete' | 'incomplete' | 'pending';
954
+ /** How much of the window a figure covers. */
955
+ export type WindowedCoverage = 'full' | 'since_creation';
956
+ /**
957
+ * An account's P&L over `(from, asOf]`: `A(asOf) - A(from)`, where
958
+ * `A(t) = equity(t) - cumInflows(t) + cumOutflows(t)`. Deposits,
959
+ * withdrawals and transfers are flows and never count; realized and
960
+ * unrealized gains, fees, funding and liquidations do. Equals
961
+ * `getPnlHistory`'s P&L for the same `from`.
962
+ *
963
+ * Rows can be ranked or summed when their `from` matches.
964
+ */
965
+ export interface ProjectedPnl {
966
+ window: ProjectionWindow | string;
967
+ /** Window start (an hour boundary), RFC 3339. */
968
+ from: string;
969
+ /** When the value was computed, RFC 3339 with milliseconds. Absent while pending. */
970
+ asOf?: string;
971
+ /** `since_creation` when the account is younger than the window. */
972
+ coverage?: WindowedCoverage | string;
973
+ /** The account's first point, set with `coverage: "since_creation"`. */
974
+ coveredFrom?: string;
975
+ status: WindowedStatus | string;
976
+ /** Exact decimal USD. Omitted while `pending`. */
977
+ pnlUsd?: string;
978
+ }
979
+ /**
980
+ * An account's traded volume over `(from, asOf]`: the exact sum of
981
+ * `|fill size × fill price|` over its fill records booked in the window,
982
+ * liquidations and partial fills included, each fill counted once.
983
+ * Deposits, transfers, fees, funding and unfilled orders never count.
984
+ */
985
+ export interface ProjectedVolume {
986
+ window: ProjectionWindow | string;
987
+ /** Window start (an hour boundary), RFC 3339. */
988
+ from: string;
989
+ /** The ledger read the sum is true at. Absent while pending. */
990
+ asOf?: string;
991
+ coverage?: WindowedCoverage | string;
992
+ coveredFrom?: string;
993
+ /** `complete` or `pending`. */
994
+ status: WindowedStatus | string;
995
+ /** Exact decimal USD. Omitted while `pending`. */
996
+ volumeUsd?: string;
919
997
  }
920
998
  /** One page of the batched projection read, keyset-paginated by path. */
921
999
  export interface ProjectionValuationsPage {
922
1000
  projection: string;
923
1001
  fields: string[];
1002
+ /** The window the rows' `pnl` / `volume` figures cover, when one was asked for. */
1003
+ window?: string;
924
1004
  valuations: ProjectedValuation[];
925
1005
  /** Set when more pages remain; pass it back verbatim as `cursor`. */
926
1006
  cursor?: string;
@@ -943,6 +1023,12 @@ export interface GetProjectionValuationsOptions {
943
1023
  cursor?: string;
944
1024
  /** Page size (default 100, max 500). */
945
1025
  limit?: number;
1026
+ /**
1027
+ * Attach the windowed `pnl` / `volume` figures the projection grants,
1028
+ * over this rolling window. Refused for a projection that grants
1029
+ * neither.
1030
+ */
1031
+ window?: ProjectionWindow;
946
1032
  }
947
1033
  /**
948
1034
  * The interest set of a projection watch: which of the accounts a
@@ -970,6 +1056,12 @@ export interface ProjectionWatchScope {
970
1056
  export interface WatchProjectionOptions extends ProjectionWatchScope {
971
1057
  /** Exchange whose mids re-mark the rows between server deltas (default `"sim"`). */
972
1058
  exchange?: string;
1059
+ /**
1060
+ * Attach the windowed `pnl` / `volume` figures the projection grants,
1061
+ * over this rolling window. `setPaths` / `setPrefix` keep it. Refused
1062
+ * for a projection that grants neither.
1063
+ */
1064
+ window?: ProjectionWindow;
973
1065
  }
974
1066
  export interface WatchSnapshotBalanceEntry {
975
1067
  entityId: string;
@@ -2318,16 +2410,21 @@ export interface TwapStartedEvent extends BaseTwapEvent {
2318
2410
  }
2319
2411
  export interface TwapProgressEvent extends BaseTwapEvent {
2320
2412
  type: typeof EventType.TwapProgress;
2321
- /** Total executed size at the moment the slice resolved. */
2413
+ /** Total executed size once this slice's fill is counted. */
2322
2414
  executedSize?: string;
2323
- /** Total executed notional (USD) at the moment the slice resolved. */
2415
+ /** Total executed notional (USD) once this slice's fill is counted. */
2324
2416
  executedNotional?: string;
2325
- /** Cumulative count of slices the scanner has dispatched so far. */
2417
+ /** Slices sent so far. See {@link Twap.sliceCount}. */
2326
2418
  sliceCount?: number;
2327
2419
  filledSlices?: number;
2328
2420
  failedSlices?: number;
2329
- /** Status of the most recently resolved slice: "completed" | "failed". */
2421
+ /**
2422
+ * The slice that just settled: "completed" when it executed a nonzero
2423
+ * size (partial fills included), "failed" when it executed nothing.
2424
+ */
2330
2425
  lastSliceStatus?: string;
2426
+ /** When the next slice is due. See {@link Twap.nextSliceAt}. */
2427
+ nextSliceAt?: string;
2331
2428
  }
2332
2429
  export interface TwapCompletedEvent extends BaseTwapEvent {
2333
2430
  type: typeof EventType.TwapCompleted;
@@ -2477,6 +2574,7 @@ export interface RealmEvent {
2477
2574
  filledSlices?: number;
2478
2575
  failedSlices?: number;
2479
2576
  lastSliceStatus?: string;
2577
+ nextSliceAt?: string;
2480
2578
  /** Absolute post-transition account states. See {@link FrameAccount}. */
2481
2579
  accounts?: FrameAccount[];
2482
2580
  /** What produced the transition. */
@@ -2518,16 +2616,19 @@ export interface CreatePerpsExchangeOptions {
2518
2616
  * then use `btc.name`. Note the symbol is the BASE ASSET (`'BTC'`), not
2519
2617
  * the venue symbol (`'BTC-USD-PERP'`) — the latter is `market.venueSymbol`
2520
2618
  * and is display text only.
2619
+ * - The venue account id is a 20-byte `0x` wallet address.
2521
2620
  * - Leverage is fixed per market (10x on the crypto perps, derived from the
2522
- * venue's initial-margin rate). `setLeverage` and the margin-mode calls
2523
- * are unsupported and refuse; hide those controls rather than catching.
2524
- * - No TP/SL and no TWAP in v1.
2621
+ * venue's initial-margin rate). `setLeverage` and `setMarginMode` refuse;
2622
+ * hide those controls rather than catching. Margin mode is chosen per
2623
+ * order instead (`isolated: true`).
2624
+ * - Post-only (`timeInForce: 'ALO'`) is supported; reduce-only must be IOC
2625
+ * or a market order. No TP/SL and no TWAP.
2525
2626
  * - The order book is SHARED and PUBLIC: anyone with a testnet key can
2526
2627
  * trade against you and can read any account's state. It is also a
2527
2628
  * testnet, which means its operator can reset it without notice. Say both
2528
2629
  * in any user-facing copy.
2529
- * - The venue charges a one-time ~1 USDT account activation fee on first
2530
- * activity, so equity reads as deposit − 1 afterwards.
2630
+ * - The venue's one-time account activation fee is paid on top of the
2631
+ * first deposit, so equity equals the amount deposited.
2531
2632
  */
2532
2633
  venue?: 'hl-sim' | 'hl' | 'gll-testnet';
2533
2634
  /** Optional operation path (idempotency key) */
@@ -2921,6 +3022,17 @@ export interface OrderOperationResponse {
2921
3022
  };
2922
3023
  }
2923
3024
  export type TwapStatus = 'active' | 'completed' | 'cancelled' | 'failed';
3025
+ /**
3026
+ * A TWAP order. It is scheduled as {@link expectedSliceCount} slots, one
3027
+ * every {@link intervalSeconds} from {@link startTime}. In each slot at most
3028
+ * one slice is sent: an IOC market order for an even share of what is left
3029
+ * over the remaining slots, never more than three planned slices and never
3030
+ * more than `totalSize − executedSize`. A slot passes without a slice while
3031
+ * the previous slice is still in flight, or when its share is below the
3032
+ * venue's minimum order. The TWAP completes when `executedSize` reaches
3033
+ * `totalSize`, when no slot is left, or at {@link endTime}; it fails after
3034
+ * five failed slices in a row.
3035
+ */
2924
3036
  export interface Twap {
2925
3037
  twapId: string;
2926
3038
  realmId: RealmId;
@@ -2932,22 +3044,28 @@ export interface Twap {
2932
3044
  market: string;
2933
3045
  side: 'buy' | 'sell';
2934
3046
  totalSize: string | null;
3047
+ /** Summed fill size of settled slices, partial fills included. */
2935
3048
  executedSize: string;
3049
+ /** Summed fill size × average fill price (USD) of settled slices. */
2936
3050
  executedNotional: string;
2937
3051
  /**
2938
- * Running counter of slices the scanner has dispatched so far. Starts
2939
- * at 0 and increments once per dispatch. To render "X of N" before
2940
- * the first slice resolves, use {@link expectedSliceCount}.
3052
+ * Slices sent so far, including one still in flight. Starts at 0 and
3053
+ * never exceeds {@link expectedSliceCount}.
2941
3054
  */
2942
3055
  sliceCount: number;
2943
3056
  /**
2944
- * Planned total slice count, computed at create time as
2945
- * `max(1, durationSeconds / intervalSeconds)`. Stable for the
2946
- * TWAP's lifetime; use this when displaying progress as "X / N"
2947
- * since {@link sliceCount} is 0 until the first slice dispatches.
3057
+ * Number of slots: `max(1, durationSeconds / intervalSeconds)`. Stable
3058
+ * for the TWAP's lifetime; use it for "X of N" progress.
2948
3059
  */
2949
3060
  expectedSliceCount: number;
3061
+ /** Settled slices that executed a nonzero size, partial fills included. */
2950
3062
  filledSlices: number;
3063
+ /**
3064
+ * Settled slices that executed nothing (rejected, failed, or an IOC
3065
+ * that found no liquidity within the slippage cap).
3066
+ * `sliceCount − filledSlices − failedSlices` is 1 while a slice is in
3067
+ * flight and 0 otherwise.
3068
+ */
2951
3069
  failedSlices: number;
2952
3070
  intervalSeconds: number;
2953
3071
  /** Echo of the request's `durationMinutes`. */
@@ -2957,8 +3075,11 @@ export interface Twap {
2957
3075
  status: TwapStatus;
2958
3076
  /**
2959
3077
  * High-level discriminator for terminal state:
2960
- * `"user"`, `"liquidated"`, `"consecutive_failures"`. Set on both
2961
- * `cancelled` and `failed` TWAPs. Use this for programmatic branching.
3078
+ * `"user"`, `"liquidated"`, `"consecutive_failures"`,
3079
+ * `"progress_unknown"` (started before fills were counted into
3080
+ * `executedSize`, so stopped rather than risk trading past its total).
3081
+ * Set on both `cancelled` and `failed` TWAPs. Use this for
3082
+ * programmatic branching.
2962
3083
  */
2963
3084
  cancelReason: string | null;
2964
3085
  /**
@@ -2980,7 +3101,14 @@ export interface Twap {
2980
3101
  leverage: number | null;
2981
3102
  slippageBps: number;
2982
3103
  randomize: boolean;
3104
+ /** Failed slices since the last filled one; the TWAP fails at 5. */
2983
3105
  consecutiveFailures: number;
3106
+ /**
3107
+ * When the next slot opens and the next slice is due. Absent once the
3108
+ * TWAP is no longer active. At or after {@link endTime} it means no slot
3109
+ * is left and the TWAP completes once its in-flight slice settles.
3110
+ */
3111
+ nextSliceAt?: string;
2984
3112
  createdAt: string;
2985
3113
  updatedAt: string;
2986
3114
  }
@@ -3384,12 +3512,25 @@ export interface Fill {
3384
3512
  /** Trigger price of the originating order. Present only for trigger orders. */
3385
3513
  triggerPx?: string;
3386
3514
  /**
3387
- * Classification of an `isLiquidation` fill: a margin-call close
3388
- * (`liquidation`) or a backstop / auto-deleverage close (`adl`). Absent
3389
- * on liquidations recorded before the venue method was stamped.
3515
+ * Classification of an `isLiquidation` fill that was a margin
3516
+ * liquidation: a margin-call close (`liquidation`) or a backstop /
3517
+ * auto-deleverage close (`adl`). Absent on liquidations recorded before
3518
+ * the venue method was stamped, and on a venue close that was not a
3519
+ * liquidation (see `closeReason`).
3390
3520
  */
3391
3521
  liquidationKind?: 'liquidation' | 'adl';
3522
+ /**
3523
+ * Why the venue closed the position on an `isLiquidation` fill:
3524
+ * `liquidation` or `adl` (the account could not carry it), `delisted`
3525
+ * (the market was delisted and the position settled), or `dust_sweep`
3526
+ * (the paper venue closed a position smaller than one lot, at the mark,
3527
+ * with no fee). Absent when the venue recorded no reason — treat that
3528
+ * as a liquidation.
3529
+ */
3530
+ closeReason?: FillCloseReason;
3392
3531
  }
3532
+ /** Why a venue closed a position on its own. See {@link Fill.closeReason}. */
3533
+ export type FillCloseReason = 'liquidation' | 'adl' | 'delisted' | 'dust_sweep';
3393
3534
  export interface FillListResponse {
3394
3535
  fills: Fill[];
3395
3536
  total: number;
@@ -3683,6 +3824,15 @@ export interface ExchangeState {
3683
3824
  * `observedBefore`. Absent from a platform that predates the field.
3684
3825
  */
3685
3826
  observedAt?: string;
3827
+ /**
3828
+ * `"fold"` when this state was computed by the platform's own Hyperliquid
3829
+ * account fold from Arca's records (positions, open P&L, margin, liquidation
3830
+ * price, withdrawable under Hyperliquid's margining rules) rather than read
3831
+ * from the venue; `observedAt` is then the fold's publication time. Absent
3832
+ * on a venue read. Realms move onto the fold per realm; the venue is read
3833
+ * only to reconcile.
3834
+ */
3835
+ stateSource?: string;
3686
3836
  }
3687
3837
  /**
3688
3838
  * One venue-confirmed execution that the ledger has not fully recorded into