useOrderEntry

The useOrderEntry hook provides a variety of supporting functions according to input parameters and the prevailing market data.

const useOrderEntry: (
  symbol: string,
  options: {
    /** initial order state, default is buy limit order */
    initialOrder?: Omit<Partial<FullOrderState>, "symbol">;
  }
) => OrderEntryReturn;

type OrderEntryReturn = {
  submit: (options?: { resetOnSuccess?: boolean }) => Promise<void>;
  reset: () => void;
  resetErrors: () => void;
  resetMetaState: () => void;
  formattedOrder: Partial<FullOrderState>;
  maxQty: number;
  /**
   * The estimated liquidation price.
   */
  estLiqPrice: number | null;
  /**
   * The estimated leverage after order creation.
   */
  estLeverage: number | null;
  helper: {
    /**
     * Function to validate the order.
     * @returns {Promise<VerifyResult | null>} The validation result.
     */
    validate: () => Promise<VerifyResult | null>;
  };
  freeCollateral: number;
  /**
   * set a single value to the order data;
   * @param key
   * @param value
   * @returns
   */
  setValue: (
    key: keyof FullOrderState,
    value: any,
    options?: {
      shouldUpdateLastChangedField?: boolean;
    }
  ) => void;
  setValues: (values: Partial<FullOrderState>) => void;
  symbolInfo: API.SymbolExt;
  /**
   * Meta state including validation and submission status.
   */
  metaState: {
    dirty: {
      [K in keyof OrderlyOrder]?: boolean;
    };
    submitted: boolean;
    validated: boolean;
    errors: VerifyResult | null;
  };
  /**
   * Indicates if a mutation (order creation) is in progress.
   */
  isMutating: boolean;
  markPrice: number | undefined;
};

Real-time data

useOrderEntry provides some real-time data that the UI will use when creating orders based on the latest market data.

maxQty: The maximum quantity that the user can trade based on the free collateral.
freeCollateral: The amount collateral available for trading, factoring in open positions and pending orders.
markPrice: The mark price of the symbol.
estLiqPrice: The estimated liquidation price, if a position is created from given order paramters.
estLeverage: The estimated leverage, if a position is created from given order paramters.

Updating values

For updating values two functions are provided: setValue and setValues. useOrderEntry is built on the concepts of react-hook-form. If you have been using it in conjunction with react-hook-form with the SDK v1, then you might want to entirely remove it now.

// ...
const { setValue } = useOrderEntry(symbol, {
  initialOrder: {
    side: OrderSide.BUY,
    order_type: OrderType.MARKET,
    price: undefined,
    order_quantity: undefined
  }
});
// ...

return (
  <>
    {/* ... */}
    <select
      onChange={(event) => {
        setValue("order_type", event.target.value);
      }}
    >
      <option value="MARKET">Market</option>
      <option value="LIMIT">Limit</option>
      <option value="STOP_LIMIT">Stop Limit</option>
    </select>

    <input
      type="string"
      placeholder="Price"
      name="price"
      onChange={(event) => {
        setValue("price", event.target.value);
      }}
    />

    <input
      type="string"
      placeholder="Quantity"
      name="order_quantity"
      onChange={(event) => {
        setValue("order_quantity", event.target.value);
      }}
    />
    {/* ... */}
  </>
);

Order validations

Order inputs will be validated automatically and any error will be returned in the metaState.errors field.

import { renderFormError } from "./formHelper.tsx";

// ...
const {
  setValue,
  metaState: { errors, dirty, submitted }
} = useOrderEntry(symbol, {
  initialOrder: {
    side: OrderSide.BUY,
    order_type: OrderType.MARKET,
    trigger_price: undefined,
    price: undefined,
    order_quantity: undefined
  }
});
const hasError = useCallback(
  (
    key: keyof OrderlyOrder
  ):
    | {
        message: string;
      }
    | undefined => {
    if (!dirty[key] && !submitted) {
      return;
    }
    return errors?.[key];
  },
  [errors, dirty, submitted]
);
// ...

return (
  <>
    {/* ... */}
    <input
      type="string"
      placeholder="Quantity"
      name="order_quantity"
      onChange={(event) => {
        setValue("order_quantity", event.target.value);
      }}
    />
    {renderFormError(hasError("order_quantity"))}
    {/* ... */}
  </>
);

export const renderFormError = (error?: { message: string }) => {
  return (
    <span
      className={`${
        error == null ? "h-0" : "h-[1.3rem]"
      } overflow-hidden color-red transition-duration-300 transition-property-[height] transition-ease-out`}
    >
      {error?.message ?? ""}
    </span>
  );
};

Placing orders

You can place orders by calling the submit function.

// ...
const { submit, reset } = useOrderEntry(symbol, {
  initialOrder: {
    side: OrderSide.BUY,
    order_type: OrderType.MARKET,
    price: undefined,
    order_quantity: undefined
  }
});
// ...

return (
  <>
    {/* ... */}

    <form
      onSubmit={async (event) => {
        event.preventDefault();
        await submit();
        reset();
      }}
    >
      <button type="submit"> Create Order</button>
    </form>
    {/* ... */}
  </>
);

Software development kits

[evm] react components SDK

[evm] react hooks SDK

[evm] core SDK

[evm] perp SDK

Autogenerated technical reference

Real-time data

Updating values

Order validations

Placing orders

​Real-time data

​Updating values

​Order validations

​Placing orders

Real-time data

Updating values

Order validations

Placing orders