@decibeltrade/sdk 0.1.1

package/src/read/user-open-orders/user-open-orders.types.ts

@@ -0,0 +1,42 @@
+import z from "zod/v4";
+
+import { BaseRequestArgs } from "../base-reader";
+
+export interface UserOpenOrdersRequestArgs extends BaseRequestArgs {
+  subAddr: string;
+}
+
+export const UserOpenOrderSchema = z.object({
+  parent: z.string(),
+  market: z.string(),
+  order_id: z.string(),
+  client_order_id: z.string().nullable(),
+  orig_size: z.number().nullable(),
+  remaining_size: z.number().nullable(),
+  size_delta: z.number().nullable(),
+  price: z.number().nullable(),
+  is_buy: z.boolean(),
+  details: z.string(),
+  transaction_version: z.number(),
+  unix_ms: z.number(),
+  tp_order_id: z.string().nullable(),
+  tp_trigger_price: z.number().nullable(),
+  tp_limit_price: z.number().nullable(),
+  sl_order_id: z.string().nullable(),
+  sl_trigger_price: z.number().nullable(),
+  sl_limit_price: z.number().nullable(),
+  order_type: z.string().optional(),
+  trigger_condition: z.string().optional(),
+  order_direction: z.string().optional(),
+  is_reduce_only: z.boolean().optional(),
+});
+
+export const UserOpenOrdersSchema = z.array(UserOpenOrderSchema);
+
+export const UserOpenOrdersWsMessageSchema = z.object({
+  orders: z.array(UserOpenOrderSchema),
+});
+
+export type UserOpenOrder = z.infer<typeof UserOpenOrderSchema>;
+export type UserOpenOrders = z.infer<typeof UserOpenOrdersSchema>;
+export type UserOpenOrdersWsMessage = z.infer<typeof UserOpenOrdersWsMessageSchema>;

package/src/read/user-order-history/user-order-history.reader.ts

@@ -0,0 +1,34 @@
+import { BaseReader } from "../base-reader";
+import {
+  UserOrderHistoryRequestArgs,
+  UserOrdersSchema,
+  UserOrdersWsMessage,
+  UserOrdersWsMessageSchema,
+} from "./user-order-history.types";
+
+export class UserOrderHistoryReader extends BaseReader {
+  async getByAddr({ subAddr, fetchOptions }: UserOrderHistoryRequestArgs) {
+    const response = await this.getRequest({
+      schema: UserOrdersSchema,
+      url: `${this.deps.config.tradingHttpUrl}/api/v1/order_history`,
+      queryParams: {
+        user: subAddr,
+      },
+      options: fetchOptions,
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Subscribe to user order history updates
+   * @param subAddr The subaccount address of the user to subscribe to
+   * @param onData Callback function for received user order history data
+   * @returns A function to unsubscribe from the user order history updates
+   */
+  subscribeByAddr(subAddr: string, onData: (data: UserOrdersWsMessage) => void) {
+    const topic = `user_order_history:${subAddr}`;
+
+    return this.deps.ws.subscribe(topic, UserOrdersWsMessageSchema, onData);
+  }
+}

package/src/read/user-order-history/user-order-history.types.ts

@@ -0,0 +1,44 @@
+import z from "zod/v4";
+
+import { BaseRequestArgs } from "../base-reader";
+import { PaginatedResponseSchema } from "../pagination.types";
+
+export interface UserOrderHistoryRequestArgs extends BaseRequestArgs {
+  subAddr: string;
+}
+
+export const UserOrderSchema = z.object({
+  parent: z.string(),
+  market: z.string(),
+  client_order_id: z.string(),
+  order_id: z.string(),
+  status: z.string(),
+  order_type: z.string(),
+  trigger_condition: z.string(),
+  order_direction: z.string(),
+  orig_size: z.number(),
+  remaining_size: z.number(),
+  size_delta: z.number(),
+  price: z.number(),
+  is_buy: z.boolean(),
+  is_reduce_only: z.boolean(),
+  details: z.string(),
+  tp_order_id: z.string().nullable(),
+  tp_trigger_price: z.number().nullable(),
+  tp_limit_price: z.number().nullable(),
+  sl_order_id: z.string().nullable(),
+  sl_trigger_price: z.number().nullable(),
+  sl_limit_price: z.number().nullable(),
+  transaction_version: z.number(),
+  unix_ms: z.number(),
+});
+
+export const UserOrdersSchema = PaginatedResponseSchema(UserOrderSchema);
+
+export const UserOrdersWsMessageSchema = z.object({
+  orders: z.array(UserOrderSchema),
+});
+
+export type UserOrder = z.infer<typeof UserOrderSchema>;
+export type UserOrders = z.infer<typeof UserOrdersSchema>;
+export type UserOrdersWsMessage = z.infer<typeof UserOrdersWsMessageSchema>;

package/src/read/user-positions/user-positions.reader.ts

@@ -0,0 +1,55 @@
+import { BaseReader } from "../base-reader";
+import {
+  UserPositionsRequestArgs,
+  UserPositionsSchema,
+  UserPositionsWsMessage,
+  UserPositionsWsMessageSchema,
+} from "./user-positions.types";
+
+export class UserPositionsReader extends BaseReader {
+  /**
+   * Get the positions for a given user
+   * @param userAddr The address of the user to get positions for
+   * @param includeDeleted Whether to include deleted positions in the response
+   * @returns The positions for the given user
+   */
+  async getByAddr({
+    subAddr,
+    marketAddr,
+    includeDeleted = false,
+    limit = 10,
+    fetchOptions,
+  }: UserPositionsRequestArgs) {
+    const queryParams = new URLSearchParams({
+      user: subAddr,
+      include_deleted: includeDeleted.toString(),
+      limit: limit.toString(),
+    });
+
+    if (marketAddr) {
+      queryParams.set("market_address", marketAddr);
+    }
+
+    const response = await this.getRequest({
+      schema: UserPositionsSchema,
+      url: `${this.deps.config.tradingHttpUrl}/api/v1/user_positions`,
+      queryParams,
+      options: fetchOptions,
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Subscribe to user positions updates
+   * @param subAddr The subaccount address of the user to subscribe to
+   * @param apiUrl The WebSocket server URL
+   * @param onData Callback function for received user positions data
+   * @returns A function to unsubscribe from the user positions updates
+   */
+  subscribeByAddr(subAddr: string, onData: (data: UserPositionsWsMessage) => void) {
+    const topic = `user_positions:${subAddr}`;
+
+    return this.deps.ws.subscribe(topic, UserPositionsWsMessageSchema, onData);
+  }
+}

package/src/read/user-positions/user-positions.types.ts

@@ -0,0 +1,43 @@
+import z from "zod/v4";
+
+import { BaseRequestArgs } from "../base-reader";
+
+export interface UserPositionsRequestArgs extends BaseRequestArgs {
+  subAddr: string;
+  marketAddr?: string;
+  includeDeleted?: boolean;
+  limit?: number;
+}
+
+export const UserPositionSchema = z.object({
+  market: z.string(),
+  user: z.string(),
+  size: z.number(),
+  // margin: z.number(),
+  max_allowed_leverage: z.number(),
+  user_leverage: z.number(),
+  entry_price: z.number(),
+  is_isolated: z.boolean(),
+  unrealized_funding: z.number(),
+  estimated_liquidation_price: z.number(),
+  tp_order_id: z.string().nullable(),
+  tp_trigger_price: z.number().nullable(),
+  tp_limit_price: z.number().nullable(),
+  sl_order_id: z.string().nullable(),
+  sl_trigger_price: z.number().nullable(),
+  sl_limit_price: z.number().nullable(),
+  has_fixed_sized_tpsls: z.boolean(),
+});
+
+export const UserPositionsSchema = z.array(UserPositionSchema);
+
+export const UserPositionWsMessageSchema = z.object(UserPositionSchema);
+
+export const UserPositionsWsMessageSchema = z.object({
+  positions: UserPositionsSchema,
+});
+
+export type UserPosition = z.infer<typeof UserPositionSchema>;
+export type UserPositions = z.infer<typeof UserPositionsSchema>;
+export type UserPositionWsMessage = z.infer<typeof UserPositionWsMessageSchema>;
+export type UserPositionsWsMessage = z.infer<typeof UserPositionsWsMessageSchema>;

package/src/read/user-subaccounts/user-subaccounts.reader.ts

@@ -0,0 +1,30 @@
+import { BaseReader } from "../base-reader";
+import { UserSubaccountsRequestArgs, UserSubaccountsSchema } from "./user-subaccounts.types";
+
+export class UserSubaccountsReader extends BaseReader {
+  /**
+   * Get the subaccounts for a given user
+   * @param ownerAddr The address of the owner to get subaccounts for
+   * @param limit The number of subaccounts to get (default: 10)
+   * @returns The subaccounts for the given user
+   */
+  async getByAddr({
+    ownerAddr,
+    // limit = 10,
+    fetchOptions,
+  }: UserSubaccountsRequestArgs) {
+    const queryParams = new URLSearchParams({
+      owner: ownerAddr,
+      // limit: limit.toString(),
+    });
+
+    const response = await this.getRequest({
+      schema: UserSubaccountsSchema,
+      url: `${this.deps.config.tradingHttpUrl}/api/v1/subaccounts`, // TODO: update to /user_subaccounts?
+      queryParams,
+      options: fetchOptions,
+    });
+
+    return response.data;
+  }
+}

package/src/read/user-subaccounts/user-subaccounts.types.ts

@@ -0,0 +1,21 @@
+import z from "zod/v4";
+
+import { BaseRequestArgs } from "../base-reader";
+
+export interface UserSubaccountsRequestArgs extends BaseRequestArgs {
+  ownerAddr: string;
+  // limit?: number; // TODO: Add limit
+}
+
+export const UserSubaccountSchema = z.object({
+  subaccount_address: z.string(),
+  primary_account_address: z.string(),
+  is_primary: z.boolean(),
+  is_active: z.boolean().optional(),
+  custom_label: z.string().nullable(),
+});
+
+export const UserSubaccountsSchema = z.array(UserSubaccountSchema);
+
+export type UserSubaccount = z.infer<typeof UserSubaccountSchema>;
+export type UserSubaccounts = UserSubaccount[];

package/src/read/user-trade-history/user-trade-history.reader.ts

@@ -0,0 +1,38 @@
+import { BaseReader } from "../base-reader";
+import {
+  UserTradeHistoryRequestArgs,
+  UserTradesSchema,
+  UserTradesWsMessage,
+  UserTradesWsMessageSchema,
+} from "./user-trade-history.types";
+
+export class UserTradeHistoryReader extends BaseReader {
+  /**
+   * Get the trade history for a given user
+   * @param subAddr The subaccount address of the user to get trade history for
+   * @param limit The number of trades to get (default: 10)
+   * @returns The trade history for the given user
+   */
+  async getByAddr({ subAddr, limit = 10, fetchOptions }: UserTradeHistoryRequestArgs) {
+    const response = await this.getRequest({
+      schema: UserTradesSchema,
+      url: `${this.deps.config.tradingHttpUrl}/api/v1/trade_history`,
+      queryParams: { user: subAddr, limit: limit.toString() },
+      options: fetchOptions,
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Subscribe to trade history updates
+   * @param subAddr The subaccount address of the user to subscribe to
+   * @param onData Callback function for received trade history data
+   * @returns A function to unsubscribe from the trade history updates
+   */
+  subscribeByAddr(subAddr: string, onData: (data: UserTradesWsMessage) => void) {
+    const topic = `user_trade_history:${subAddr}`;
+
+    return this.deps.ws.subscribe(topic, UserTradesWsMessageSchema, onData);
+  }
+}

package/src/read/user-trade-history/user-trade-history.types.ts

@@ -0,0 +1,33 @@
+import z from "zod/v4";
+
+import { BaseRequestArgs } from "../base-reader";
+
+export interface UserTradeHistoryRequestArgs extends BaseRequestArgs {
+  subAddr: string;
+  limit?: number;
+}
+
+export const UserTradeSchema = z.object({
+  account: z.string(),
+  market: z.string(),
+  action: z.string(),
+  size: z.number(),
+  price: z.number(),
+  is_profit: z.boolean(),
+  realized_pnl_amount: z.number(),
+  is_funding_positive: z.boolean(),
+  realized_funding_amount: z.number(),
+  is_rebate: z.boolean(),
+  fee_amount: z.number(),
+  transaction_unix_ms: z.number(),
+  transaction_version: z.number(),
+});
+
+export const UserTradesSchema = z.array(UserTradeSchema);
+export const UserTradesWsMessageSchema = z.object({
+  trades: z.array(UserTradeSchema),
+});
+
+export type UserTrade = z.infer<typeof UserTradeSchema>;
+export type UserTrades = z.infer<typeof UserTradesSchema>;
+export type UserTradesWsMessage = z.infer<typeof UserTradesWsMessageSchema>;

package/src/read/vaults/vaults.reader.ts

@@ -0,0 +1,79 @@
+import { BaseReader } from "../base-reader";
+import {
+  PublicVaultsRequestArgs,
+  UserOwnedVaultsRequestArgs,
+  UserOwnedVaultsResponseSchema,
+  UserPerformancesOnVaultsRequestArgs,
+  UserPerformancesOnVaultsResponseSchema,
+  VaultsResponseSchema,
+} from "./vaults.types";
+
+export class VaultsReader extends BaseReader {
+  /**
+   * Get all vaults
+   * @returns  All vaults
+   */
+  async getVaults({ fetchOptions, ...args }: PublicVaultsRequestArgs = {}) {
+    const queryParams = new URLSearchParams();
+
+    if (args.vaultType) queryParams.set("vault_type", args.vaultType);
+    if (args.limit) queryParams.set("limit", args.limit.toString());
+    if (args.offset) queryParams.set("offset", args.offset.toString());
+
+    const response = await this.getRequest({
+      schema: VaultsResponseSchema,
+      url: `${this.deps.config.tradingHttpUrl}/api/v1/vaults`,
+      queryParams,
+      options: fetchOptions,
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Get vaults by owner address
+   * @param user The user address to filter vaults by
+   * @returns The vaults for the given owner address
+   */
+  async getUserOwnedVaults({ fetchOptions, ...args }: UserOwnedVaultsRequestArgs) {
+    const queryParams = new URLSearchParams({
+      user: args.ownerAddr,
+    });
+
+    if (args.limit) queryParams.set("limit", args.limit.toString());
+
+    if (args.offset) queryParams.set("offset", args.offset.toString());
+
+    const response = await this.getRequest({
+      schema: UserOwnedVaultsResponseSchema,
+      url: `${this.deps.config.tradingHttpUrl}/api/v1/user_owned_vaults`,
+      queryParams,
+      options: fetchOptions,
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Get user performance
+   * @param args The arguments for the user performance
+   * @returns The user performance
+   */
+  async getUserPerformancesOnVaults({
+    fetchOptions,
+    ...args
+  }: UserPerformancesOnVaultsRequestArgs) {
+    const queryParams = new URLSearchParams({
+      user_address: args.ownerAddr,
+    });
+
+    const response = await this.getRequest({
+      schema: UserPerformancesOnVaultsResponseSchema,
+      url: `${this.deps.config.tradingHttpUrl}/api/v1/user_vault_performance`,
+      queryParams,
+      options: fetchOptions,
+    });
+
+    return response.data;
+  }
+}

package/src/read/vaults/vaults.types.ts

@@ -0,0 +1,106 @@
+import z from "zod/v4";
+
+import { BaseRequestArgs } from "../base-reader";
+import { PaginatedResponseSchema } from "../pagination.types";
+
+/**
+ * Arguments for fetching vaults owned by a specific user
+ */
+export interface UserOwnedVaultsRequestArgs extends BaseRequestArgs {
+  ownerAddr: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface PublicVaultsRequestArgs extends BaseRequestArgs {
+  limit?: number;
+  offset?: number;
+  vaultType?: "user" | "protocol";
+  address?: string;
+}
+
+/**
+ * Arguments for fetching user performance metrics for a specific subaccount
+ */
+export interface UserPerformancesOnVaultsRequestArgs extends BaseRequestArgs {
+  ownerAddr: string;
+}
+
+/**
+ * Schema for a vault in the protocol
+ * Represents both protocol-wide vaults and user-managed vaults
+ */
+export const VaultSchema = z.object({
+  address: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  manager: z.string(),
+  status: z.string(),
+  created_at: z.number(),
+  tvl: z.number().nullable(),
+  volume: z.number().nullable(),
+  all_time_return: z.number().nullable(),
+  past_month_return: z.number().nullable(),
+  sharpe_ratio: z.number().nullable(),
+  max_drawdown: z.number().nullable(),
+  weekly_win_rate_12w: z.number().nullable(),
+  profit_share: z.number().nullable(),
+  pnl_90d: z.number().nullable(),
+  manager_avg_cash: z.number().nullable(),
+  average_leverage: z.number().nullable(),
+  depositors: z.number().nullable(),
+  perp_equity: z.number().nullable(),
+  vault_type: z.string(),
+  pnl_history: z.array(z.string()).nullable(),
+  social_links: z.array(z.string()).nullable(),
+});
+
+export const VaultsResponseSchema = PaginatedResponseSchema(VaultSchema).extend({
+  total_value_locked: z.number(),
+  total_volume: z.number(),
+});
+export type VaultsResponse = z.infer<typeof VaultsResponseSchema>;
+export type Vault = z.infer<typeof VaultSchema>;
+export type Vaults = Vault[];
+
+/**
+ * Schema for vaults owned/managed by a specific user
+ * Contains summary information about vaults the user manages
+ */
+export const UserOwnedVaultSchema = z.object({
+  vault_address: z.string(),
+  vault_name: z.string(),
+  vault_share_symbol: z.string(),
+  status: z.string(),
+  age_days: z.number(),
+  num_managers: z.number(),
+  tvl: z.number().nullable(),
+  apr: z.number().nullable(),
+  manager_equity: z.number().nullable(),
+  manager_stake: z.number().nullable(),
+});
+
+export const UserOwnedVaultsResponseSchema = PaginatedResponseSchema(UserOwnedVaultSchema);
+export type UserOwnedVaultsResponse = z.infer<typeof UserOwnedVaultsResponseSchema>;
+export type UserOwnedVault = z.infer<typeof UserOwnedVaultSchema>;
+export type UserOwnedVaults = UserOwnedVault[];
+
+/**
+ * Schema for user performance metrics within a vault
+ * Tracks a user's deposits, shares, returns, and PnL for a specific vault
+ */
+export const UserPerformanceOnVaultSchema = z.object({
+  vault_address: z.string(),
+  user_address: z.string(),
+  net_deposits: z.number().nullable(),
+  current_num_shares: z.number().nullable(),
+  current_value_of_shares: z.number().nullable(),
+  all_time_return: z.number().nullable(),
+  unrealized_pnl: z.number().nullable(),
+  share_price: z.number(),
+  volume: z.number(),
+  weekly_win_rate_12w: z.number().nullable(),
+});
+export const UserPerformancesOnVaultsResponseSchema = z.array(UserPerformanceOnVaultSchema);
+export type UserPerformanceOnVault = z.infer<typeof UserPerformanceOnVaultSchema>;
+export type UserPerformancesOnVaults = UserPerformanceOnVault[];