@zebpay_rajesh/zebpay-mcp-server 0.1.0

package/src/private/FuturesClient.ts

@@ -0,0 +1,189 @@
+/*
+  Futures client for basic trading and positions.
+*/
+
+import { ZebpayAPI } from "./ZebpayAPI.js";
+
+export class FuturesClient {
+  constructor(private readonly api: ZebpayAPI) {}
+
+  // GET /api/v1/wallet/balance
+  async getWalletBalance(): Promise<unknown> {
+    return this.api.request({
+      method: "GET",
+      path: "/wallet/balance",
+      useFutures: true,
+    });
+  }
+
+  // POST /api/v1/trade/order
+  async placeOrder(params: {
+    symbol: string;
+    amount: number | string;
+    side: "BUY" | "SELL";
+    type: "MARKET" | "LIMIT";
+    marginAsset: string;
+    price?: number | string; // for LIMIT orders
+    clientOrderId?: string;
+  }): Promise<unknown> {
+    const body: Record<string, unknown> = {
+      symbol: params.symbol,
+      amount: typeof params.amount === "string" ? params.amount : String(params.amount),
+      side: params.side,
+      type: params.type,
+      marginAsset: params.marginAsset,
+    };
+    if (params.price !== undefined) body.price = typeof params.price === "string" ? params.price : String(params.price);
+    if (params.clientOrderId) body.clientOrderId = params.clientOrderId;
+    return this.api.request({
+      method: "POST",
+      path: "/trade/order",
+      body,
+      useFutures: true,
+    });
+  }
+
+  // POST /api/v1/trade/addMargin
+  async addMargin(params: { symbol: string; amount: number | string; marginAsset: string }): Promise<unknown> {
+    const body = {
+      symbol: params.symbol,
+      amount: typeof params.amount === "string" ? params.amount : String(params.amount),
+      marginAsset: params.marginAsset,
+    };
+    return this.api.request({
+      method: "POST",
+      path: "/trade/addMargin",
+      body,
+      useFutures: true,
+    });
+  }
+
+  // POST /api/v1/trade/reduceMargin
+  async reduceMargin(params: { symbol: string; amount: number | string; marginAsset: string }): Promise<unknown> {
+    const body = {
+      symbol: params.symbol,
+      amount: typeof params.amount === "string" ? params.amount : String(params.amount),
+      marginAsset: params.marginAsset,
+    };
+    return this.api.request({
+      method: "POST",
+      path: "/trade/reduceMargin",
+      body,
+      useFutures: true,
+    });
+  }
+
+  // GET /api/v1/trade/order/open-orders
+  async getOpenOrders(params: { symbol?: string; limit?: number; since?: string | number }): Promise<unknown> {
+    const query: Record<string, string> = {};
+    if (params.symbol) query.symbol = params.symbol;
+    if (params.limit !== undefined) query.limit = String(params.limit);
+    if (params.since !== undefined) query.since = String(params.since);
+    return this.api.request({
+      method: "GET",
+      path: "/trade/order/open-orders",
+      queryParams: query,
+      useFutures: true,
+    });
+  }
+
+  // GET /api/v1/trade/order/history
+  async getOrderHistory(params: { page?: number; pageSize?: number }): Promise<unknown> {
+    const query: Record<string, string> = {};
+    if (params.page !== undefined) query.page = String(params.page);
+    if (params.pageSize !== undefined) query.pageSize = String(params.pageSize);
+    return this.api.request({
+      method: "GET",
+      path: "/trade/order/history",
+      queryParams: query,
+      useFutures: true,
+    });
+  }
+
+  // GET /api/v1/trade/linkedOrders/{clientOrderId}
+  async getLinkedOrders(clientOrderId: string): Promise<unknown> {
+    const path = `/trade/linkedOrders/${encodeURIComponent(clientOrderId)}`;
+    return this.api.request({
+      method: "GET",
+      path,
+      useFutures: true,
+    });
+  }
+
+  // GET /api/v1/trade/positions
+  async getPositions(params: { status?: string } = {}): Promise<unknown> {
+    const query: Record<string, string> = {};
+    if (params.status) query.status = params.status;
+    return this.api.request({
+      method: "GET",
+      path: "/trade/positions",
+      queryParams: query,
+      useFutures: true,
+    });
+  }
+
+  // GET /api/v1/trade/history
+  async getTradeHistory(params: { page?: number; pageSize?: number }): Promise<unknown> {
+    const query: Record<string, string> = {};
+    if (params.page !== undefined) query.page = String(params.page);
+    if (params.pageSize !== undefined) query.pageSize = String(params.pageSize);
+    return this.api.request({
+      method: "GET",
+      path: "/trade/history",
+      queryParams: query,
+      useFutures: true,
+    });
+  }
+
+  // GET /api/v1/trade/transaction/history
+  async getTransactionHistory(params: { page?: number; pageSize?: number }): Promise<unknown> {
+    const query: Record<string, string> = {};
+    if (params.page !== undefined) query.page = String(params.page);
+    if (params.pageSize !== undefined) query.pageSize = String(params.pageSize);
+    return this.api.request({
+      method: "GET",
+      path: "/trade/transaction/history",
+      queryParams: query,
+      useFutures: true,
+    });
+  }
+
+  // DELETE /api/v1/trade/order
+  async deleteOrder(params: { orderId?: string | number; clientOrderId?: string }): Promise<unknown> {
+    const query: Record<string, string> = {};
+    if (params.orderId !== undefined) query.orderId = String(params.orderId);
+    if (params.clientOrderId !== undefined) query.clientOrderId = params.clientOrderId;
+    return this.api.request({
+      method: "DELETE",
+      path: "/trade/order",
+      queryParams: query,
+      useFutures: true,
+    });
+  }
+
+  // GET /api/v1/trade/userLeverage
+  async getUserLeverage(params: { symbol: string }): Promise<unknown> {
+    const query: Record<string, string> = { symbol: params.symbol };
+    return this.api.request({
+      method: "GET",
+      path: "/trade/userLeverage",
+      queryParams: query,
+      useFutures: true,
+    });
+  }
+
+  // POST /api/v1/trade/update/userLeverage
+  async updateUserLeverage(params: { symbol: string; leverage: number | string }): Promise<unknown> {
+    const body = {
+      symbol: params.symbol,
+      leverage: typeof params.leverage === "string" ? params.leverage : String(params.leverage),
+    };
+    return this.api.request({
+      method: "POST",
+      path: "/trade/update/userLeverage",
+      body,
+      useFutures: true,
+    });
+  }
+}
+

package/src/private/SpotClient.ts

@@ -0,0 +1,250 @@
+/*
+  Spot client for market orders.
+*/
+
+import { ZebpayAPI } from "./ZebpayAPI.js";
+
+export interface SpotMarketOrderParams {
+  symbol: string; // e.g., BTC-INR
+  side: "BUY" | "SELL";
+  quoteOrderAmount?: string; // Quote currency value (e.g., INR) - will be mapped to body based on side
+  amount?: string; // Base currency amount (e.g., BTC) - will be mapped to body based on side
+  clientOrderId?: string; // Must contain only letters, numbers, dots, colons, slashes, underscores, and hyphens, 1-36 characters
+  platform?: string;
+}
+
+export interface SpotLimitOrderParams {
+  symbol: string;
+  side: "BUY" | "SELL";
+  quoteOrderAmount?: string; // Quote currency value (e.g., INR) - will be mapped to body based on side
+  amount?: string; // Base currency amount (e.g., BTC) - will be mapped to body based on side
+  price: string; // Limit price as string to preserve precision
+  clientOrderId?: string; // Must contain only letters, numbers, dots, colons, slashes, underscores, and hyphens, 1-36 characters
+  platform?: string;
+}
+
+export interface GetOrdersParams {
+  symbol: string; // Trading pair symbol (required)
+  status?: "ACTIVE" | "FILLED" | "CANCELLED"; // Order status (default: ACTIVE)
+  currentPage?: number; // Current page number (default: 1)
+  pageSize?: number; // Number of records per page (default: 20)
+  startTime?: number; // Start time in milliseconds
+  endTime?: number; // End time in milliseconds
+}
+
+export interface GetExchangeFeeParams {
+  symbol: string; // Trading pair symbol (required)
+  side: "BUY" | "SELL"; // Order side (required)
+}
+
+export class SpotClient {
+  constructor(private readonly api: ZebpayAPI) {}
+
+  async placeMarketOrder(params: SpotMarketOrderParams): Promise<unknown> {
+    const path = "/ex/orders";
+    
+    // Build body based on order side:
+    // BUY orders: use quoteOrderAmount (value in quote currency, e.g., INR)
+    // SELL orders: use amount (quantity in base currency, e.g., BTC)
+    const body: Record<string, unknown> = {
+      symbol: params.symbol,
+      side: params.side,
+      type: "MARKET",
+    };
+    
+    // Map to the appropriate field based on side
+    if (params.side === "BUY") {
+      // For BUY orders, use quoteOrderAmount in body
+      if (params.quoteOrderAmount) {
+        body.quoteOrderAmount = params.quoteOrderAmount;
+      } else if (params.amount) {
+        // If amount is provided for BUY, it should already be converted to quoteOrderAmount by the tool
+        body.quoteOrderAmount = params.amount;
+      }
+    } else {
+      // For SELL orders, use amount in body
+      if (params.amount) {
+        body.amount = params.amount;
+      } else if (params.quoteOrderAmount) {
+        // If quoteOrderAmount is provided for SELL, it should already be converted to amount by the tool
+        body.amount = params.quoteOrderAmount;
+      }
+    }
+    
+    if (params.clientOrderId) {
+      body.clientOrderId = params.clientOrderId;
+    }
+    
+    if (params.platform) {
+      body.platform = params.platform;
+    }
+    
+    return this.api.request({
+      method: "POST",
+      path,
+      body,
+      useFutures: false,
+    });
+  }
+
+  async placeLimitOrder(params: SpotLimitOrderParams): Promise<unknown> {
+    const path = "/ex/orders";
+    
+    // Build body based on order side:
+    // BUY orders: use quoteOrderAmount (value in quote currency, e.g., INR)
+    // SELL orders: use amount (quantity in base currency, e.g., BTC)
+    const body: Record<string, unknown> = {
+      symbol: params.symbol,
+      side: params.side,
+      type: "LIMIT",
+      price: params.price,
+    };
+    
+    // Map to the appropriate field based on side
+    if (params.side === "BUY") {
+      // For BUY orders, use quoteOrderAmount in body
+      if (params.quoteOrderAmount) {
+        body.quoteOrderAmount = params.quoteOrderAmount;
+      } else if (params.amount) {
+        // If amount is provided for BUY, it should already be converted to quoteOrderAmount by the tool
+        body.quoteOrderAmount = params.amount;
+      }
+    } else {
+      // For SELL orders, use amount in body
+      if (params.amount) {
+        body.amount = params.amount;
+      } else if (params.quoteOrderAmount) {
+        // If quoteOrderAmount is provided for SELL, it should already be converted to amount by the tool
+        body.amount = params.quoteOrderAmount;
+      }
+    }
+    
+    if (params.clientOrderId) {
+      body.clientOrderId = params.clientOrderId;
+    }
+    if (params.platform) {
+      body.platform = params.platform;
+    }
+    return this.api.request({
+      method: "POST",
+      path,
+      body,
+      useFutures: false,
+    });
+  }
+
+  async cancelOrdersBySymbol(symbol: string): Promise<unknown> {
+    const path = "/ex/orders";
+    return this.api.request({
+      method: "DELETE",
+      path,
+      useFutures: false,
+      queryParams: {
+        symbol: symbol.toUpperCase(),
+      },
+    });
+  }
+
+  async cancelAllOrders(): Promise<unknown> {
+    const path = "/ex/orders/cancelAll";
+    return this.api.request({
+      method: "DELETE",
+      path,
+      useFutures: false,
+    });
+  }
+
+  async getOrderFills(orderId: string): Promise<unknown> {
+    const path = "/ex/order/fills/";
+    return this.api.request({
+      method: "GET",
+      path,
+      useFutures: false,
+      queryParams: {
+        orderId,
+      },
+    });
+  }
+
+  async getOrderById(orderId: string): Promise<unknown> {
+    const path = "/ex/order";
+    return this.api.request({
+      method: "GET",
+      path,
+      useFutures: false,
+      queryParams: {
+        orderId,
+      },
+    });
+  }
+
+  async cancelOrderById(orderId: string): Promise<unknown> {
+    const path = "/ex/order";
+    return this.api.request({
+      method: "DELETE",
+      path,
+      useFutures: false,
+      queryParams: {
+        orderId,
+      },
+    });
+  }
+
+  async getBalance(currencies?: string): Promise<unknown> {
+    const path = "/account/balance";
+    const queryParams: Record<string, string> | undefined = currencies
+      ? { currencies }
+      : undefined;
+    return this.api.request({
+      method: "GET",
+      path,
+      useFutures: false,
+      queryParams,
+    });
+  }
+
+  async getOrders(params: GetOrdersParams): Promise<unknown> {
+    const path = "/ex/orders";
+    const queryParams: Record<string, string> = {
+      symbol: params.symbol.toUpperCase(),
+    };
+    
+    if (params.status) {
+      queryParams.status = params.status;
+    }
+    if (params.currentPage !== undefined) {
+      queryParams.currentPage = params.currentPage.toString();
+    }
+    if (params.pageSize !== undefined) {
+      queryParams.pageSize = params.pageSize.toString();
+    }
+    if (params.startTime !== undefined) {
+      queryParams.startTime = params.startTime.toString();
+    }
+    if (params.endTime !== undefined) {
+      queryParams.endTime = params.endTime.toString();
+    }
+    
+    return this.api.request({
+      method: "GET",
+      path,
+      useFutures: false,
+      queryParams,
+    });
+  }
+
+  async getExchangeFee(params: GetExchangeFeeParams): Promise<unknown> {
+    const path = `/ex/tradefee`;
+    
+    return this.api.request({
+      method: "GET",
+      path,
+      useFutures: false,
+      queryParams: {
+        symbol: params.symbol.toUpperCase(),
+        side: params.side,
+      },
+    });
+  }
+}
+

package/src/private/ZebpayAPI.ts

@@ -0,0 +1,205 @@
+/*
+  Core ZebpayAPI encapsulates signing, sending, and error normalization.
+*/
+
+import { AppConfig } from "../config.js";
+import { CredentialsProvider } from "../security/credentials.js";
+import { buildAuthHeaders, buildQueryStringAuthHeaders, signQueryString, signPayloadString, signRequest } from "../security/signing.js";
+import { HttpClient, HttpError } from "../http/httpClient.js";
+import { convertHttpErrorToMcpError, createInternalError } from "../mcp/errors.js";
+import { McpError } from "@modelcontextprotocol/sdk/types.js";
+
+export interface RequestOptions {
+  method: string;
+  path: string; // path starting with '/'
+  body?: unknown;
+  useFutures?: boolean; // choose base URL
+  queryParams?: Record<string, string>; // optional query parameters
+}
+
+export class ZebpayAPI {
+  constructor(
+    private readonly config: AppConfig,
+    private readonly creds: CredentialsProvider,
+    private readonly http: HttpClient
+  ) {}
+
+  private baseUrl(useFutures: boolean): string {
+    return useFutures ? this.config.futuresBaseUrl : this.config.spotBaseUrl;
+  }
+
+  private buildUrl(useFutures: boolean, path: string, queryParams?: Record<string, string>): string {
+    const trimmed = path.startsWith("/") ? path : `/${path}`;
+    let url = `${this.baseUrl(useFutures)}${trimmed}`;
+    
+    if (queryParams && Object.keys(queryParams).length > 0) {
+      const queryString = Object.entries(queryParams)
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+        .join("&");
+      url += `?${queryString}`;
+      
+      // Debug logging
+      if (this.config.logLevel === "debug") {
+        console.error(JSON.stringify({
+          level: "debug",
+          msg: "buildUrl details",
+          queryParams,
+          queryString,
+          finalUrl: url
+        }));
+      }
+    }
+    
+    return url;
+  }
+
+  async request<T = unknown>({ method, path, body, useFutures = false, queryParams: providedQueryParams }: RequestOptions): Promise<T> {
+    const apiKey = this.creds.getApiKey();
+    const secret = this.creds.getSecretKey();
+
+    const methodUpper = method.toUpperCase();
+    const isGetOrDelete = methodUpper === "GET" || methodUpper === "DELETE";
+    const isPost = methodUpper === "POST";
+    const includeBody = isPost && body !== undefined && body !== null;
+
+    let url: string;
+    let authHeaders: Record<string, string>;
+    let finalBody: unknown = body;
+
+    if (isGetOrDelete) {
+      // For GET and DELETE requests, use query-string based signing (Zebpay API format)
+      const timestamp = Date.now().toString();
+      const queryParams: Record<string, string> = {
+        timestamp,
+        ...providedQueryParams, // Merge provided query params with timestamp
+      };
+      
+      // Build query string for signing (sorted alphabetically for consistent signing)
+      // This same sorted order must be used in the URL to match the signature
+      const sortedEntries = Object.entries(queryParams)
+        .sort(([a], [b]) => a.localeCompare(b));
+      const queryString = sortedEntries
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+        .join("&");
+      
+      // Sign the query string
+      const signature = signQueryString(queryString, secret);
+      
+      // Build auth headers (only API key and signature, no timestamp header)
+      authHeaders = buildQueryStringAuthHeaders(apiKey, signature, this.config.signingHeaders);
+      
+      // Build URL with the same sorted query string to match the signature
+      const trimmed = path.startsWith("/") ? path : `/${path}`;
+      url = `${this.baseUrl(useFutures)}${trimmed}?${queryString}`;
+      
+      // Debug logging
+      if (this.config.logLevel === "debug") {
+        console.error(JSON.stringify({
+          level: "debug",
+          msg: `${methodUpper} request details`,
+          path,
+          queryString,
+          timestamp,
+          url,
+          hasQueryParams: url.includes("?")
+        }));
+      }
+    } else if (isPost) {
+      // For POST requests, sign the JSON body directly (Zebpay API format)
+      const timestamp = Date.now();
+      
+      // Prepare payload with timestamp added
+      const payload = body ? { ...(body as Record<string, unknown>), timestamp } : { timestamp };
+      
+      // Stringify the payload (deterministic JSON stringify)
+      const payloadString = JSON.stringify(payload);
+      
+      // Sign the payload string directly
+      const signature = signPayloadString(payloadString, secret);
+      
+      // Build auth headers (only API key and signature, no timestamp header)
+      authHeaders = buildQueryStringAuthHeaders(apiKey, signature, this.config.signingHeaders);
+      
+      // Set the final body with timestamp included
+      finalBody = payload;
+      url = this.buildUrl(useFutures, path);
+      
+      // Debug logging
+      if (this.config.logLevel === "debug") {
+        console.error(JSON.stringify({
+          level: "debug",
+          msg: "POST request details",
+          path,
+          payloadString,
+          timestamp,
+          signature
+        }));
+      }
+    } else {
+      // For other methods (PUT, PATCH, etc.), fall back to original signing method
+      const signature = signRequest(method, path, includeBody ? body : undefined, secret, {
+        headers: this.config.signingHeaders,
+        includeBody,
+      });
+      authHeaders = buildAuthHeaders(apiKey, signature, this.config.signingHeaders);
+      url = this.buildUrl(useFutures, path);
+    }
+
+    try {
+      const res = await this.http.request<T>({
+        method,
+        url,
+        headers: authHeaders,
+        body: isPost ? finalBody : (isGetOrDelete ? undefined : body),
+        timeoutMs: this.config.timeoutMs,
+        retryCount: this.config.retryCount,
+      });
+      return res.data as T;
+    } catch (err) {
+      if (err instanceof HttpError) {
+        // Extract error message from various possible response formats
+        let errorMessage = err.message || "Unknown API error";
+        
+        // Extract error message and preserve full details for better error handling
+        let errorDetails = err.details;
+        
+        if (err.details) {
+          if (typeof err.details === "string") {
+            errorMessage = err.details;
+          } else if (typeof err.details === "object") {
+            // Check common error response fields (in order of preference)
+            const details = err.details as Record<string, unknown>;
+            
+            // Extract statusDescription first (most specific)
+            if (typeof details.statusDescription === "string" && details.statusDescription) {
+              errorMessage = details.statusDescription;
+            } else if (typeof details.error === "string" && details.error) {
+              errorMessage = details.error;
+            } else if (typeof details.message === "string" && details.message) {
+              errorMessage = details.message;
+            } else if (typeof details.msg === "string" && details.msg) {
+              errorMessage = details.msg;
+            } else if (typeof details.errorMessage === "string" && details.errorMessage) {
+              errorMessage = details.errorMessage;
+            }
+            
+            // Preserve the full details object for error conversion
+            errorDetails = details;
+          }
+        }
+        
+        throw convertHttpErrorToMcpError(err.status, errorMessage, errorDetails, err.isHtmlResponse);
+      }
+      // Re-throw MCP errors as-is
+      if (err instanceof McpError) {
+        throw err;
+      }
+      // Wrap other errors as internal errors
+      throw createInternalError(
+        err instanceof Error ? err.message : String(err),
+        { originalError: String(err) }
+      );
+    }
+  }
+}
+