@decibeltrade/sdk 0.1.1

package/src/gas/gas-price-manager.ts

@@ -0,0 +1,115 @@
+import { Aptos, AptosConfig } from "@aptos-labs/ts-sdk";
+
+import { DecibelConfig } from "../constants";
+
+export interface GasPriceInfo {
+  gasEstimate: number;
+  timestamp: number;
+}
+
+export interface GasPriceManagerOptions {
+  nodeApiKey?: string;
+  multiplier: number;
+  refreshIntervalMs: number;
+}
+
+export class GasPriceManager {
+  private gasPrice: GasPriceInfo | null = null;
+  private intervalId: NodeJS.Timeout | null = null;
+  private readonly aptos: Aptos;
+  private readonly refreshIntervalMs: number;
+  private isInitialized = false;
+  private readonly multiplier: number;
+
+  constructor(config: DecibelConfig, opts?: GasPriceManagerOptions) {
+    this.aptos = new Aptos(
+      new AptosConfig({
+        network: config.network,
+        fullnode: config.fullnodeUrl,
+        clientConfig: { API_KEY: opts?.nodeApiKey },
+      }),
+    );
+    this.refreshIntervalMs = opts?.refreshIntervalMs ?? 60_000; // default to 1 minute
+    this.multiplier = opts?.multiplier ?? 2; // default to 2x multilier to ensure we have enough gas for the transactipon
+  }
+
+  getGasPrice(): number | undefined {
+    const estimatedGasPrice = this.gasPrice?.gasEstimate;
+    if (!estimatedGasPrice) {
+      return undefined;
+    }
+    return estimatedGasPrice;
+  }
+
+  /**
+   * Initialize the gas price manager and start fetching gas prices
+   */
+  async initialize(): Promise<void> {
+    try {
+      if (this.isInitialized) {
+        return;
+      }
+
+      // Fetch initial gas price
+      await this.fetchAndSetGasPrice();
+
+      // Set up interval to refresh gas price
+      this.intervalId = setInterval(async () => {
+        try {
+          await this.fetchAndSetGasPrice();
+        } catch (error) {
+          console.warn("Failed to fetch gas price:", error);
+        }
+      }, this.refreshIntervalMs);
+
+      this.isInitialized = true;
+    } catch (error) {
+      console.error("Failed to initialize gas price manager:", error);
+    }
+  }
+
+  refresh() {
+    void this.fetchAndSetGasPrice();
+  }
+
+  /**
+   * Stop the gas price manager and clear the interval
+   */
+  destroy(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+    this.isInitialized = false;
+    this.gasPrice = null; // Clear cached data
+  }
+
+  async fetchGasPriceEstimation(): Promise<number> {
+    return this.aptos.getGasPriceEstimation().then((gasEstimation) => {
+      return gasEstimation.gas_estimate * this.multiplier; // Multiplier is applied here to ensure we have enough gas for the transaction
+    });
+  }
+
+  /**
+   * Fetch gas price from the network
+   */
+  async fetchAndSetGasPrice(): Promise<number> {
+    try {
+      const gasEstimate = await this.fetchGasPriceEstimation();
+
+      if (!gasEstimate) {
+        throw new Error("Gas estimation returned no gas estimate");
+      }
+
+      this.gasPrice = {
+        gasEstimate,
+        timestamp: Date.now(),
+      };
+
+      return gasEstimate;
+    } catch (error) {
+      console.error("Failed to fetch gas price:", error);
+      throw error;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./admin";
+export * from "./constants";
+export * from "./fee-pay";
+export * from "./gas/gas-price-manager";
+export * from "./order-event.types";
+export * from "./order-status";
+export * from "./read/index";
+export * from "./subaccount-types";
+export * from "./utils";
+export * from "./write";

package/src/order-event.types.ts

@@ -0,0 +1,65 @@
+// Type definitions for OrderEvent returned by placeOrder transactions
+
+export interface OrderEventClientOrderId {
+  vec: unknown[];
+}
+
+export interface OrderEventStatus {
+  __variant__: string;
+}
+
+export interface OrderEventTimeInForce {
+  __variant__: string;
+}
+
+export interface OrderEventTriggerCondition {
+  vec: unknown[];
+}
+
+export interface OrderEventOrderId {
+  order_id: string;
+}
+
+export interface OrderEvent {
+  client_order_id: OrderEventClientOrderId;
+  details: string;
+  is_bid: boolean;
+  is_taker: boolean;
+  market: string;
+  metadata_bytes: string;
+  order_id: string;
+  orig_size: string;
+  parent: string;
+  price: string;
+  remaining_size: string;
+  size_delta: string;
+  status: OrderEventStatus;
+  time_in_force: OrderEventTimeInForce;
+  trigger_condition: OrderEventTriggerCondition;
+  user: string;
+}
+
+export interface TwapEvent {
+  account: string;
+  duration_s: string;
+  frequency_s: string;
+  is_buy: boolean;
+  is_reduce_only: boolean;
+  market: string;
+  order_id: OrderEventOrderId;
+  orig_size: string;
+  remain_size: string;
+  start_time_s: string;
+  status: OrderEventStatus;
+}
+
+export type PlaceOrderResult =
+  | {
+      success: true;
+      orderId: string | undefined;
+      transactionHash: string;
+    }
+  | {
+      success: false;
+      error: string;
+    };

package/src/order-status.ts

@@ -0,0 +1,89 @@
+import z from "zod/v4";
+
+import { DecibelConfig } from "./constants";
+
+// Order status response schema
+export const OrderStatusSchema = z.object({
+  parent: z.string(),
+  market: z.string(),
+  order_id: z.string(),
+  status: z.string(),
+  orig_size: z.number(),
+  remaining_size: z.number(),
+  size_delta: z.number(),
+  price: z.number(),
+  is_buy: z.boolean(),
+  details: z.string(),
+  transaction_version: z.number(),
+  unix_ms: z.number(),
+});
+
+export type OrderStatus = z.infer<typeof OrderStatusSchema>;
+
+export type OrderStatusType = "Acknowledged" | "Filled" | "Cancelled" | "Rejected" | "Unknown";
+
+export class OrderStatusClient {
+  constructor(private config: DecibelConfig) {}
+
+  /**
+   * Get order status by order ID and market address using REST API
+   */
+  async getOrderStatus(
+    orderId: string,
+    marketAddress: string,
+    userAddress: string,
+  ): Promise<OrderStatus | null> {
+    try {
+      const url = `${this.config.tradingHttpUrl}/api/v1/orders?order_id=${orderId}&market_address=${marketAddress}&user_address=${userAddress}`;
+      const response = await fetch(url);
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          return null; // Order not found yet
+        }
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const data = await response.json();
+      return OrderStatusSchema.parse(data);
+    } catch (error) {
+      console.error("Error fetching order status:", error);
+      return null;
+    }
+  }
+
+  /**
+   * Parse order status string to enum-like type
+   */
+  parseOrderStatusType(status: string | undefined | null): OrderStatusType {
+    if (!status) return "Unknown";
+    const upperStatus = status.toLowerCase();
+    if (upperStatus.includes("acknowledged")) return "Acknowledged";
+    if (upperStatus.includes("filled")) return "Filled";
+    if (upperStatus.includes("cancelled")) return "Cancelled";
+    if (upperStatus.includes("rejected")) return "Rejected";
+    return "Unknown";
+  }
+
+  /**
+   * Check if order status represents success
+   */
+  isSuccessStatus(status: string | undefined | null): boolean {
+    return this.parseOrderStatusType(status) === "Filled";
+  }
+
+  /**
+   * Check if order status represents failure
+   */
+  isFailureStatus(status: string | undefined | null): boolean {
+    const statusType = this.parseOrderStatusType(status);
+    return statusType === "Cancelled" || statusType === "Rejected";
+  }
+
+  /**
+   * Check if order status is final (success or failure)
+   */
+  isFinalStatus(status: string | undefined | null): boolean {
+    return this.isSuccessStatus(status) || this.isFailureStatus(status);
+  }
+}

package/src/read/account-overview/account-overview.reader.ts

@@ -0,0 +1,43 @@
+import { BaseReader } from "../base-reader";
+import {
+  AccountOverviewRequestArgs,
+  AccountOverviewSchema,
+  AccountOverviewWsMessage,
+  AccountOverviewWsMessageSchema,
+} from "./account-overview.types";
+
+export class AccountOverviewReader extends BaseReader {
+  /**
+   * Get the account overview for a given user
+   * @param subAddr The subaccount address to get the account overview for
+   * @returns The account overview for the given subaccount address
+   */
+  async getByAddr({ subAddr, volumeWindow, fetchOptions }: AccountOverviewRequestArgs) {
+    const queryParams = new URLSearchParams({ user: subAddr });
+
+    if (volumeWindow) {
+      queryParams.set("volume_window", volumeWindow);
+    }
+
+    const response = await this.getRequest({
+      schema: AccountOverviewSchema,
+      url: `${this.deps.config.tradingHttpUrl}/api/v1/account_overviews`,
+      queryParams,
+      options: fetchOptions,
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Subscribe to account overview
+   * @param subAddr The subaccount address of the user to subscribe to
+   * @param onData Callback function for received account overview data
+   * @returns A function to unsubscribe from the account overview updates
+   */
+  subscribeByAddr(subAddr: string, onData: (data: AccountOverviewWsMessage) => void) {
+    const topic = `account_overview:${subAddr}`;
+
+    return this.deps.ws.subscribe(topic, AccountOverviewWsMessageSchema, onData);
+  }
+}

package/src/read/account-overview/account-overview.types.ts

@@ -0,0 +1,45 @@
+import z from "zod/v4";
+
+import { BaseRequestArgs } from "../base-reader";
+
+export interface AccountOverviewRequestArgs extends BaseRequestArgs {
+  subAddr: string;
+  volumeWindow?: VolumeWindow;
+}
+
+export const VolumeWindow = {
+  SevenDays: "7d",
+  FourteenDays: "14d",
+  ThirtyDays: "30d",
+  NinetyDays: "90d",
+} as const;
+
+export type VolumeWindow = (typeof VolumeWindow)[keyof typeof VolumeWindow];
+
+export const AccountOverviewSchema = z.object({
+  perp_equity_balance: z.number(),
+  unrealized_pnl: z.number(),
+  unrealized_funding_cost: z.number(),
+  cross_margin_ratio: z.number(),
+  maintenance_margin: z.number(),
+  cross_account_leverage_ratio: z.number().nullable(),
+  volume: z.number().nullable(),
+  all_time_return: z.number().nullable(),
+  pnl_90d: z.number().nullable(),
+  sharpe_ratio: z.number().nullable(),
+  max_drawdown: z.number().nullable(),
+  weekly_win_rate_12w: z.number().nullable(),
+  average_cash_position: z.number().nullable(),
+  average_leverage: z.number().nullable(),
+  cross_account_position: z.number(),
+  total_margin: z.number(),
+  usdc_cross_withdrawable_balance: z.number(),
+  usdc_isolated_withdrawable_balance: z.number(),
+});
+
+export const AccountOverviewWsMessageSchema = z.object({
+  account_overview: AccountOverviewSchema.omit({ volume: true }),
+});
+
+export type AccountOverview = z.infer<typeof AccountOverviewSchema>;
+export type AccountOverviewWsMessage = z.infer<typeof AccountOverviewWsMessageSchema>;

package/src/read/base-reader.ts

@@ -0,0 +1,41 @@
+import { DecibelReaderDeps } from "../constants";
+import {
+  FetchOptions,
+  getRequest as baseGetRequest,
+  GetRequestArgs,
+  patchRequest as basePatchRequest,
+  PatchRequestArgs,
+  postRequest as basePostRequest,
+  PostRequestArgs,
+} from "../utils";
+
+export interface BaseRequestArgs {
+  fetchOptions?: FetchOptions;
+}
+
+export class BaseReader {
+  constructor(protected readonly deps: DecibelReaderDeps) {}
+
+  protected async getRequest<TResponseData>(args: Omit<GetRequestArgs<TResponseData>, "apiKey">) {
+    return baseGetRequest({
+      ...args,
+      apiKey: this.deps.apiKey,
+    });
+  }
+
+  protected async postRequest<TResponseData>(args: Omit<PostRequestArgs<TResponseData>, "apiKey">) {
+    return basePostRequest({
+      ...args,
+      apiKey: this.deps.apiKey,
+    });
+  }
+
+  protected async patchRequest<TResponseData>(
+    args: Omit<PatchRequestArgs<TResponseData>, "apiKey">,
+  ) {
+    return basePatchRequest({
+      ...args,
+      apiKey: this.deps.apiKey,
+    });
+  }
+}

package/src/read/candlesticks/candlesticks.reader.ts

@@ -0,0 +1,61 @@
+import { getMarketAddr } from "../../utils";
+import { BaseReader } from "../base-reader";
+import {
+  CandlestickInterval,
+  CandlesticksRequestArgs,
+  CandlesticksSchema,
+  CandlestickWsMessage,
+  CandlestickWsMessageSchema,
+} from "./candlesticks.types";
+
+export class CandlesticksReader extends BaseReader {
+  /**
+   * Get the candlestick data points for a given market during a given time period
+   * @param marketName The name of the market to get candlestick data for
+   * @param interval The time interval of the candlestick data points
+   * @param startTime The start time of the candlestick data points
+   * @param endTime The end time of the candlestick data points
+   * @returns The candlestick data points for the given market during the given time period
+   */
+  async getByName({
+    marketName,
+    interval,
+    startTime,
+    endTime,
+    fetchOptions,
+  }: CandlesticksRequestArgs) {
+    const marketAddr = getMarketAddr(marketName, this.deps.config.deployment.perpEngineGlobal);
+
+    const response = await this.getRequest({
+      schema: CandlesticksSchema,
+      url: `${this.deps.config.tradingHttpUrl}/api/v1/candlesticks`,
+      queryParams: {
+        market: marketAddr.toString(),
+        interval,
+        startTime: startTime.toString(),
+        endTime: endTime.toString(),
+      },
+      options: fetchOptions,
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Subscribe to candlestick data points for a given market
+   * @param marketName The name of the market to subscribe to
+   * @param interval The time interval of the candlestick data points
+   * @param onData Callback function for received candlestick data points
+   * @returns A function to unsubscribe from the candlestick updates
+   */
+  subscribeByName(
+    marketName: string,
+    interval: CandlestickInterval,
+    onData: (data: CandlestickWsMessage) => void,
+  ) {
+    const marketAddr = getMarketAddr(marketName, this.deps.config.deployment.perpEngineGlobal);
+    const topic = `market_candlestick:${marketAddr}:${interval}`;
+
+    return this.deps.ws.subscribe(topic, CandlestickWsMessageSchema, onData);
+  }
+}

package/src/read/candlesticks/candlesticks.types.ts

@@ -0,0 +1,46 @@
+import z from "zod/v4";
+
+import { BaseRequestArgs } from "../base-reader";
+
+export interface CandlesticksRequestArgs extends BaseRequestArgs {
+  marketName: string;
+  interval: CandlestickInterval;
+  startTime: number;
+  endTime: number;
+}
+export const CandlestickInterval = {
+  OneMinute: "1m",
+  FifteenMinutes: "15m",
+  OneHour: "1h",
+  FourHours: "4h",
+  OneDay: "1d",
+} as const;
+
+export type CandlestickInterval = (typeof CandlestickInterval)[keyof typeof CandlestickInterval];
+
+export const CandlestickSchema = z.object({
+  /** time end */
+  T: z.number(),
+  /** close */
+  c: z.number(),
+  /** high */
+  h: z.number(),
+  /** internal */
+  i: z.string(),
+  /** low */
+  l: z.number(),
+  /** open */
+  o: z.number(),
+  /** time start */
+  t: z.number(),
+  /** volume */
+  v: z.number(),
+});
+export const CandlesticksSchema = z.array(CandlestickSchema);
+export const CandlestickWsMessageSchema = z.object({
+  candle: CandlestickSchema,
+});
+
+export type Candlestick = z.infer<typeof CandlestickSchema>;
+export type Candlesticks = z.infer<typeof CandlesticksSchema>;
+export type CandlestickWsMessage = z.infer<typeof CandlestickWsMessageSchema>;

package/src/read/delegations/delegations.reader.ts

@@ -0,0 +1,22 @@
+import { BaseReader } from "../base-reader";
+import { DelegationsRequestArgs, DelegationsSchema } from "./delegations.types";
+
+export class DelegationsReader extends BaseReader {
+  /**
+   * Get all active delegations for a subaccount
+   * @param args The arguments containing the subaccount address
+   * @returns The list of active delegations for the given subaccount
+   */
+  async getAll({ subAddr, fetchOptions }: DelegationsRequestArgs) {
+    const response = await this.getRequest({
+      schema: DelegationsSchema,
+      url: `${this.deps.config.tradingHttpUrl}/api/v1/delegations`,
+      queryParams: new URLSearchParams({
+        subaccount: subAddr,
+      }),
+      options: fetchOptions,
+    });
+
+    return response.data;
+  }
+}

package/src/read/delegations/delegations.types.ts

@@ -0,0 +1,19 @@
+import z from "zod/v4";
+
+import { BaseRequestArgs } from "../base-reader";
+
+export interface DelegationsRequestArgs extends BaseRequestArgs {
+  subAddr: string;
+}
+
+export const DelegationSchema = z.object({
+  delegated_account: z.string(),
+  permission_type: z.string(),
+  expiration_time_s: z.number().nullable(),
+});
+
+export const DelegationsSchema = z.array(DelegationSchema);
+
+export type Delegations = z.infer<typeof DelegationsSchema>;
+
+export type Delegation = z.infer<typeof DelegationSchema>;