DhanHQ MCP Server

Instructions

Implementation Reference

• src/authentication.ts:256-283 (handler)

  Core implementation of the placeOrder function that executes the API call to place an order on DhanHQ.

  export async function placeOrder(
    request: PlaceOrderRequest
  ): Promise<OrderResponse> {
    try {
      log(`Placing order: ${request.transactionType} ${request.quantity} shares`);
  
      const response = await axios.post<OrderResponse>(
        'https://api.dhan.co/v2/orders',
        request,
        {
          headers: getApiHeaders(),
        }
      );
  
      log(`✓ Order placed successfully. Order ID: ${response.data.orderId}`);
      return response.data;
    } catch (error) {
      const errorMessage =
        error instanceof axios.AxiosError
          ? `API Error: ${error.response?.status} - ${JSON.stringify(error.response?.data)}`
          : error instanceof Error
            ? error.message
            : 'Unknown error';
  
      log(`✗ Failed to place order: ${errorMessage}`);
      throw new Error(`Failed to place order: ${errorMessage}`);
    }
  }

• src/types.ts:56-73 (schema)

  TypeScript interface defining the structure and types for PlaceOrderRequest used in the handler.

  export interface PlaceOrderRequest {
    dhanClientId: string;
    correlationId: string;
    transactionType: 'BUY' | 'SELL';
    exchangeSegment: string;
    productType: 'CNC' | 'INTRADAY' | 'MARGIN' | 'MTF' | 'CO' | 'BO';
    orderType: 'LIMIT' | 'MARKET' | 'STOP_LOSS' | 'STOP_LOSS_MARKET';
    validity: 'DAY' | 'IOC';
    securityId: string;
    quantity: number;
    disclosedQuantity?: number;
    price?: number;
    triggerPrice?: number;
    afterMarketOrder?: boolean;
    amoTime?: 'PRE_OPEN' | 'OPEN' | 'OPEN_30' | 'OPEN_60';
    boProfitValue?: number;
    boStopLossValue?: number;
  }

• src/index.ts:118-165 (registration)

  MCP tool registration in the tools list, including name, description, and detailed inputSchema for validation.

  {
    name: 'place_order',
    description:
      'Places a new order on DhanHQ. Requires authentication. Supports MARKET, LIMIT, STOP_LOSS, and STOP_LOSS_MARKET orders.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        dhanClientId: { type: 'string', description: 'Your Dhan client ID' },
        correlationId: { type: 'string', description: 'Unique correlation ID for order tracking' },
        transactionType: { type: 'string', enum: ['BUY', 'SELL'] },
        exchangeSegment: { type: 'string', description: 'e.g., NSE_EQ, BSE_EQ, NFO_FUT' },
        productType: {
          type: 'string',
          enum: ['CNC', 'INTRADAY', 'MARGIN', 'MTF', 'CO', 'BO'],
          description: 'CNC=Delivery, INTRADAY=Intraday, MARGIN=Margin, CO=Cover Order, BO=Bracket Order',
        },
        orderType: {
          type: 'string',
          enum: ['MARKET', 'LIMIT', 'STOP_LOSS', 'STOP_LOSS_MARKET'],
        },
        validity: {
          type: 'string',
          enum: ['DAY', 'IOC'],
          description: 'DAY=Valid for today, IOC=Immediate or Cancel',
        },
        securityId: { type: 'string', description: 'Security ID for the instrument' },
        quantity: { type: 'number', description: 'Quantity to order' },
        price: { type: 'number', description: 'Price per share (required for LIMIT/STOP_LOSS)' },
        triggerPrice: { type: 'number', description: 'Trigger price (required for STOP_LOSS/STOP_LOSS_MARKET)' },
        disclosedQuantity: { type: 'number', description: 'Quantity visible in order book (min 30% of quantity)' },
        afterMarketOrder: { type: 'boolean', description: 'Flag for after-market orders' },
        amoTime: { type: 'string', enum: ['PRE_OPEN', 'OPEN', 'OPEN_30', 'OPEN_60'], description: 'AMO timing' },
        boProfitValue: { type: 'number', description: 'BO target price change' },
        boStopLossValue: { type: 'number', description: 'BO stop loss price change' },
      },
      required: [
        'dhanClientId',
        'correlationId',
        'transactionType',
        'exchangeSegment',
        'productType',
        'orderType',
        'validity',
        'securityId',
        'quantity',
        'price',
      ],
    },

• src/index.ts:505-534 (handler)

  MCP server dispatch handler for 'place_order' tool that maps arguments and invokes the core placeOrder function.

  case 'place_order': {
    console.error('[Tool] Executing: place_order');
    const orderArgs = args as Record<string, unknown>;
    const result = await placeOrder({
      dhanClientId: orderArgs.dhanClientId as string,
      correlationId: orderArgs.correlationId as string,
      transactionType: orderArgs.transactionType as 'BUY' | 'SELL',
      exchangeSegment: orderArgs.exchangeSegment as string,
      productType: orderArgs.productType as 'CNC' | 'INTRADAY' | 'MARGIN' | 'MTF' | 'CO' | 'BO',
      orderType: orderArgs.orderType as 'LIMIT' | 'MARKET' | 'STOP_LOSS' | 'STOP_LOSS_MARKET',
      validity: orderArgs.validity as 'DAY' | 'IOC',
      securityId: orderArgs.securityId as string,
      quantity: orderArgs.quantity as number,
      price: orderArgs.price as number | undefined,
      triggerPrice: orderArgs.triggerPrice as number | undefined,
      disclosedQuantity: orderArgs.disclosedQuantity as number | undefined,
      afterMarketOrder: orderArgs.afterMarketOrder as boolean | undefined,
      amoTime: orderArgs.amoTime as 'PRE_OPEN' | 'OPEN' | 'OPEN_30' | 'OPEN_60' | undefined,
      boProfitValue: orderArgs.boProfitValue as number | undefined,
      boStopLossValue: orderArgs.boStopLossValue as number | undefined,
    });
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }