20260168111

Committed 16 Dec 2025 07:33AM UTC coverage: 95.34% (-1.3%) from 96.688%

Build # 20260168111

Build Type

push

github

Committed by

nktkas

Commit Message

docs: improve code documentation

Run Details

661 of 881 branches covered (75.03%)

Branch coverage included in aggregate %.

5 of 5 new or added lines in 2 files covered. (100.0%)

151 existing lines in 17 files now uncovered.

12843 of 13283 relevant lines covered (96.69%)

1103.6 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

96.26

/src/api/exchange/_methods/modify.ts

import * as v from "@valibot/valibot";

// ============================================================
// API Schemas
// ============================================================

import { Address, Cloid, UnsignedDecimal, UnsignedInteger } from "../../_schemas.ts";
import { ErrorResponse, SignatureSchema, SuccessResponse } from "./_base/commonSchemas.ts";

/**
 * Modify an order.
 * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#modify-an-order
 */
export const ModifyRequest = /* @__PURE__ */ (() => {
  return v.pipe(
    v.object({
      /** Action to perform. */
      action: v.pipe(
        v.object({
          /** Type of action. */
          type: v.pipe(
            v.literal("modify"),
            v.description("Type of action."),
          ),
          /** Order ID or Client Order ID. */
          oid: v.pipe(
            v.union([UnsignedInteger, Cloid]),
            v.description("Order ID or Client Order ID."),
          ),
          /** New order parameters. */
          order: v.pipe(
            v.object({
              /** Asset ID. */
              a: v.pipe(
                UnsignedInteger,
                v.description("Asset ID."),
              ),
              /** Position side (`true` for long, `false` for short). */
              b: v.pipe(
                v.boolean(),
                v.description("Position side (`true` for long, `false` for short)."),
              ),
              /** Price. */
              p: v.pipe(
                UnsignedDecimal,
                v.check((input) => Number(input) > 0, "Value must be greater than zero."),
                v.description("Price."),
              ),
              /** Size (in base currency units). */
              s: v.pipe(
                UnsignedDecimal,
                v.description("Size (in base currency units)."),
              ),
              /** Is reduce-only? */
              r: v.pipe(
                v.boolean(),
                v.description("Is reduce-only?"),
              ),
              /** Order type (`limit` for limit orders, `trigger` for stop-loss/take-profit orders). */
              t: v.pipe(
                v.union([
                  v.object({
                    /** Limit order parameters. */
                    limit: v.pipe(
                      v.object({
                        /**
                         * Time-in-force.
                         * - `"Gtc"`: Remains active until filled or canceled.
                         * - `"Ioc"`: Fills immediately or cancels any unfilled portion.
                         * - `"Alo"`: Adds liquidity only.
                         * - `"FrontendMarket"`: Similar to Ioc, used in Hyperliquid UI.
                         * - `"LiquidationMarket"`: Similar to Ioc, used in Hyperliquid UI.
                         */
                        tif: v.pipe(
                          v.picklist(["Gtc", "Ioc", "Alo", "FrontendMarket", "LiquidationMarket"]),
                          v.description(
                            "Time-in-force." +
                              '\n- `"Gtc"`: Remains active until filled or canceled.' +
                              '\n- `"Ioc"`: Fills immediately or cancels any unfilled portion.' +
                              '\n- `"Alo"`: Adds liquidity only.' +
                              '\n- `"FrontendMarket"`: Similar to Ioc, used in Hyperliquid UI.' +
                              '\n- `"LiquidationMarket"`: Similar to Ioc, used in Hyperliquid UI.',
                          ),
                        ),
                      }),
                      v.description("Limit order parameters."),
                    ),
                  }),
                  v.object({
                    /** Trigger order parameters. */
                    trigger: v.pipe(
                      v.object({
                        /** Is market order? */
                        isMarket: v.pipe(
                          v.boolean(),
                          v.description("Is market order?"),
                        ),
                        /** Trigger price. */
                        triggerPx: v.pipe(
                          UnsignedDecimal,
                          v.check((input) => Number(input) > 0, "Value must be greater than zero."),
                          v.description("Trigger price."),
                        ),
                        /** Indicates whether it is take profit or stop loss. */
                        tpsl: v.pipe(
                          v.picklist(["tp", "sl"]),
                          v.description("Indicates whether it is take profit or stop loss."),
                        ),
                      }),
                      v.description("Trigger order parameters."),
                    ),
                  }),
                ]),
                v.description("Order type (`limit` for limit orders, `trigger` for stop-loss/take-profit orders)."),
              ),
              /** Client Order ID. */
              c: v.pipe(
                v.optional(Cloid),
                v.description("Client Order ID."),
              ),
            }),
            v.description("New order parameters."),
          ),
        }),
        v.description("Action to perform."),
      ),
      /** Nonce (timestamp in ms) used to prevent replay attacks. */
      nonce: v.pipe(
        UnsignedInteger,
        v.description("Nonce (timestamp in ms) used to prevent replay attacks."),
      ),
      /** ECDSA signature components. */
      signature: v.pipe(
        SignatureSchema,
        v.description("ECDSA signature components."),
      ),
      /** Vault address (for vault trading). */
      vaultAddress: v.pipe(
        v.optional(Address),
        v.description("Vault address (for vault trading)."),
      ),
      /** Expiration time of the action. */
      expiresAfter: v.pipe(
        v.optional(UnsignedInteger),
        v.description("Expiration time of the action."),
      ),
    }),
    v.description("Modify an order."),
  );
})();
export type ModifyRequest = v.InferOutput<typeof ModifyRequest>;

/**
 * Successful response without specific data or error response.
 * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#modify-an-order
 */
export const ModifyResponse = /* @__PURE__ */ (() => {
  return v.pipe(
    v.union([SuccessResponse, ErrorResponse]),
    v.description("Successful response without specific data or error response."),
  );
})();
export type ModifyResponse = v.InferOutput<typeof ModifyResponse>;

// ============================================================
// Execution Logic
// ============================================================

import { type ExchangeConfig, executeL1Action, type ExtractRequestOptions } from "./_base/execute.ts";
import type { ExcludeErrorResponse } from "./_base/errors.ts";

/** Schema for user-provided action parameters (excludes system fields). */
const ModifyParameters = /* @__PURE__ */ (() => {
  return v.omit(
    v.object(ModifyRequest.entries.action.entries),
    ["type"],
  );
})();
/** Action parameters for the {@linkcode modify} function. */
export type ModifyParameters = v.InferInput<typeof ModifyParameters>;

/** Request options for the {@linkcode modify} function. */
export type ModifyOptions = ExtractRequestOptions<v.InferInput<typeof ModifyRequest>>;

/** Successful variant of {@linkcode ModifyResponse} without errors. */
export type ModifySuccessResponse = ExcludeErrorResponse<ModifyResponse>;

/**
 * Modify an order.
 *
 * @param config - General configuration for Exchange API requests.
 * @param params - Parameters specific to the API request.
 * @param opts - Request execution options.
 *
 * @returns Successful response without specific data.
 *
 * @throws {ValiError} When the request parameters fail validation (before sending).
 * @throws {TransportError} When the transport layer throws an error.
 * @throws {ApiRequestError} When the API returns an unsuccessful response.
 *
 * @example
 * ```ts
 * import { HttpTransport } from "@nktkas/hyperliquid";
 * import { modify } from "@nktkas/hyperliquid/api/exchange";
 * import { privateKeyToAccount } from "npm:viem/accounts";
 *
 * const wallet = privateKeyToAccount("0x..."); // viem or ethers
 * const transport = new HttpTransport(); // or `WebSocketTransport`
 *
 * await modify(
 *   { transport, wallet },
 *   {
 *     oid: 123,
 *     order: {
 *       a: 0,
 *       b: true,
 *       p: "31000",
 *       s: "0.2",
 *       r: false,
 *       t: { limit: { tif: "Gtc" } },
 *       c: "0x...",
 *     },
 *   },
 * );
 * ```
 *
 * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#modify-an-order
 */
export function modify(
  config: ExchangeConfig,
  params: ModifyParameters,
  opts?: ModifyOptions,
): Promise<ModifySuccessResponse> {
  const action = v.parse(ModifyParameters, params);
  return executeL1Action(config, { type: "modify", ...action }, opts);
}

1	import * as v from "@valibot/valibot";	364✔
2
3	// ============================================================
4	// API Schemas
5	// ============================================================
6
7	import { Address, Cloid, UnsignedDecimal, UnsignedInteger } from "../../_schemas.ts";	364✔
8	import { ErrorResponse, SignatureSchema, SuccessResponse } from "./_base/commonSchemas.ts";	364✔
9
10	/**
11	* Modify an order.
12	* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#modify-an-order
13	*/
14	export const ModifyRequest = /* @__PURE__ */ (() => {	364✔
15	return v.pipe(	618✔
16	v.object({	618✔
17	/** Action to perform. */
18	action: v.pipe(	618✔
19	v.object({	618✔
20	/** Type of action. */
21	type: v.pipe(	618✔
22	v.literal("modify"),	618✔
23	v.description("Type of action."),	618✔
24	),
25	/** Order ID or Client Order ID. */
26	oid: v.pipe(	618✔
27	v.union([UnsignedInteger, Cloid]),	2,472✔
28	v.description("Order ID or Client Order ID."),	618✔
29	),
30	/** New order parameters. */
31	order: v.pipe(	618✔
32	v.object({	618✔
33	/** Asset ID. */
34	a: v.pipe(	618✔
35	UnsignedInteger,	618✔
36	v.description("Asset ID."),	618✔
37	),
38	/** Position side (`true` for long, `false` for short). */
39	b: v.pipe(	618✔
40	v.boolean(),	618✔
41	v.description("Position side (`true` for long, `false` for short)."),	618✔
42	),
43	/** Price. */
44	p: v.pipe(	618✔
45	UnsignedDecimal,	618✔
46	v.check((input) => Number(input) > 0, "Value must be greater than zero."),	618✔
47	v.description("Price."),	618✔
48	),
49	/** Size (in base currency units). */
50	s: v.pipe(	618✔
51	UnsignedDecimal,	618✔
52	v.description("Size (in base currency units)."),	618✔
53	),
54	/** Is reduce-only? */
55	r: v.pipe(	618✔
56	v.boolean(),	618✔
57	v.description("Is reduce-only?"),	618✔
58	),
59	/** Order type (`limit` for limit orders, `trigger` for stop-loss/take-profit orders). */
60	t: v.pipe(	618✔
61	v.union([	618✔
62	v.object({	618✔
63	/** Limit order parameters. */
64	limit: v.pipe(	618✔
65	v.object({	618✔
66	/**
67	* Time-in-force.
68	* - `"Gtc"`: Remains active until filled or canceled.
69	* - `"Ioc"`: Fills immediately or cancels any unfilled portion.
70	* - `"Alo"`: Adds liquidity only.
71	* - `"FrontendMarket"`: Similar to Ioc, used in Hyperliquid UI.
72	* - `"LiquidationMarket"`: Similar to Ioc, used in Hyperliquid UI.
73	*/
74	tif: v.pipe(	618✔
75	v.picklist(["Gtc", "Ioc", "Alo", "FrontendMarket", "LiquidationMarket"]),	4,326✔
76	v.description(	618✔
77	"Time-in-force." +	618✔
78	'\n- `"Gtc"`: Remains active until filled or canceled.' +	618✔
79	'\n- `"Ioc"`: Fills immediately or cancels any unfilled portion.' +	618✔
80	'\n- `"Alo"`: Adds liquidity only.' +	618✔
81	'\n- `"FrontendMarket"`: Similar to Ioc, used in Hyperliquid UI.' +	618✔
82	'\n- `"LiquidationMarket"`: Similar to Ioc, used in Hyperliquid UI.',	618✔
83	),
84	),
85	}),	618✔
86	v.description("Limit order parameters."),	618✔
87	),
88	}),	618✔
89	v.object({	618✔
90	/** Trigger order parameters. */
91	trigger: v.pipe(	618✔
92	v.object({	618✔
93	/** Is market order? */
94	isMarket: v.pipe(	618✔
95	v.boolean(),	618✔
96	v.description("Is market order?"),	618✔
97	),
98	/** Trigger price. */
UNCOV 99	triggerPx: v.pipe(	×
UNCOV 100	UnsignedDecimal,	×
UNCOV 101	v.check((input) => Number(input) > 0, "Value must be greater than zero."),	×
UNCOV 102	v.description("Trigger price."),	×
103	),
104	/** Indicates whether it is take profit or stop loss. */
105	tpsl: v.pipe(	618✔
106	v.picklist(["tp", "sl"]),	2,472✔
107	v.description("Indicates whether it is take profit or stop loss."),	618✔
108	),
109	}),	618✔
110	v.description("Trigger order parameters."),	618✔
111	),
112	}),	618✔
113	]),	618✔
114	v.description("Order type (`limit` for limit orders, `trigger` for stop-loss/take-profit orders)."),	618✔
115	),
116	/** Client Order ID. */
117	c: v.pipe(	618✔
118	v.optional(Cloid),	618✔
119	v.description("Client Order ID."),	618✔
120	),
121	}),	618✔
122	v.description("New order parameters."),	618✔
123	),
124	}),	618✔
125	v.description("Action to perform."),	618✔
126	),
127	/** Nonce (timestamp in ms) used to prevent replay attacks. */
128	nonce: v.pipe(	618✔
129	UnsignedInteger,	618✔
130	v.description("Nonce (timestamp in ms) used to prevent replay attacks."),	618✔
131	),
132	/** ECDSA signature components. */
133	signature: v.pipe(	618✔
134	SignatureSchema,	618✔
135	v.description("ECDSA signature components."),	618✔
136	),
137	/** Vault address (for vault trading). */
138	vaultAddress: v.pipe(	618✔
139	v.optional(Address),	618✔
140	v.description("Vault address (for vault trading)."),	618✔
141	),
142	/** Expiration time of the action. */
143	expiresAfter: v.pipe(	618✔
144	v.optional(UnsignedInteger),	618✔
145	v.description("Expiration time of the action."),	618✔
146	),
147	}),	618✔
148	v.description("Modify an order."),	618✔
149	);
150	})();	364✔
151	export type ModifyRequest = v.InferOutput<typeof ModifyRequest>;
152
153	/**
154	* Successful response without specific data or error response.
155	* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#modify-an-order
156	*/
157	export const ModifyResponse = /* @__PURE__ */ (() => {	364✔
158	return v.pipe(	618✔
159	v.union([SuccessResponse, ErrorResponse]),	2,472✔
160	v.description("Successful response without specific data or error response."),	618✔
161	);
162	})();	364✔
163	export type ModifyResponse = v.InferOutput<typeof ModifyResponse>;
164
165	// ============================================================
166	// Execution Logic
167	// ============================================================
168
169	import { type ExchangeConfig, executeL1Action, type ExtractRequestOptions } from "./_base/execute.ts";	364✔
170	import type { ExcludeErrorResponse } from "./_base/errors.ts";
171
172	/** Schema for user-provided action parameters (excludes system fields). */
173	const ModifyParameters = /* @__PURE__ */ (() => {	364✔
174	return v.omit(	618✔
175	v.object(ModifyRequest.entries.action.entries),	618✔
176	["type"],	1,854✔
177	);
178	})();	364✔
179	/** Action parameters for the {@linkcode modify} function. */
180	export type ModifyParameters = v.InferInput<typeof ModifyParameters>;
181
182	/** Request options for the {@linkcode modify} function. */
183	export type ModifyOptions = ExtractRequestOptions<v.InferInput<typeof ModifyRequest>>;
184
185	/** Successful variant of {@linkcode ModifyResponse} without errors. */
186	export type ModifySuccessResponse = ExcludeErrorResponse<ModifyResponse>;
187
188	/**
189	* Modify an order.
190	*
191	* @param config - General configuration for Exchange API requests.
192	* @param params - Parameters specific to the API request.
193	* @param opts - Request execution options.
194	*
195	* @returns Successful response without specific data.
196	*
197	* @throws {ValiError} When the request parameters fail validation (before sending).
198	* @throws {TransportError} When the transport layer throws an error.
199	* @throws {ApiRequestError} When the API returns an unsuccessful response.
200	*
201	* @example
202	* ```ts
203	* import { HttpTransport } from "@nktkas/hyperliquid";
204	* import { modify } from "@nktkas/hyperliquid/api/exchange";
205	* import { privateKeyToAccount } from "npm:viem/accounts";
206	*
207	* const wallet = privateKeyToAccount("0x..."); // viem or ethers
208	* const transport = new HttpTransport(); // or `WebSocketTransport`
209	*
210	* await modify(
211	* { transport, wallet },
212	* {
213	* oid: 123,
214	* order: {
215	* a: 0,
216	* b: true,
217	* p: "31000",
218	* s: "0.2",
219	* r: false,
220	* t: { limit: { tif: "Gtc" } },
221	* c: "0x...",
222	* },
223	* },
224	* );
225	* ```
226	*
227	* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#modify-an-order
228	*/
229	export function modify(	364✔
230	config: ExchangeConfig,	364✔
231	params: ModifyParameters,	364✔
232	opts?: ModifyOptions,	364✔
233	): Promise<ModifySuccessResponse> {
234	const action = v.parse(ModifyParameters, params);	367✔
235	return executeL1Action(config, { type: "modify", ...action }, opts);	1,468✔
236	}	367✔

nktkas / hyperliquid / 20260168111

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous