@polymarket/clob-client-v2 1.2.0-canary.1 → 1.2.0

package/README.md

@@ -46,12 +46,23 @@ const resp = await client.createAndPostOrder(
 console.log(resp);
 ```
 
-See [examples](examples/) for more information.
+For a position-backed outcome, provide `positionID` instead. The client uses
+the identifier field to select Exchange V3 signing automatically:
+
+```ts
+const resp = await client.createAndPostOrder(
+    {
+        positionID: "", // position ID of the market outcome
+        price: 0.4,
+        side: Side.BUY,
+        size: 100,
+    },
+    { tickSize: "0.01" },
+    OrderType.GTC,
+);
+```
 
-Limit and market orders automatically use Exchange V3 for protocol V2 position IDs.
-Legacy CTF token IDs use the server's exchange version. To override automatic
-selection, pass `version: 1`, `version: 2`, or `version: 3` in the order options,
-for example `{ tickSize: "0.01", version: 3 }`.
+See [examples](examples/) for more information.
 
 ### Market Orders
 
@@ -72,6 +83,30 @@ const resp = await client.createAndPostMarketOrder(
 console.log(resp);
 ```
 
+### Warm up order cache metadata
+
+The first order on a new client fetches the order version and the market's tick size,
+neg-risk flag, and fee details before it can be signed. Both are public GET requests and
+need no signer or credentials. To take them off the first trade, run them ahead of time
+on the same client instance that will submit orders:
+
+```ts
+await Promise.all([
+    client.getVersion(), // adopted as the order version for this client
+    client.getClobMarketInfo(conditionID), // caches tick size, neg risk, and fees for both outcomes
+]);
+```
+
+Each call asks the server and refreshes the caches, so repeating it costs one request. If
+the version request fails, `getVersion` adopts the default version 2 and the first order
+corrects it through the mismatch recovery built into order posting. With `throwOnError`
+both calls throw `ApiError` instead, so treat a rejected warm-up as a background failure.
+A new client instance starts with empty caches. Order creation and `getVersion` reuse a
+version or market request that is still in flight instead of starting another one. Orders
+never require these calls. An order placed before `getClobMarketInfo` resolves still
+performs its own token-to-market lookup. Books, balances, allowances, credentials, and
+builder fee rates are not cached by these calls.
+
 ### Authentication
 
 The client has two authentication levels:

package/dist/client.cjs

@@ -4,6 +4,7 @@ const require_errors = require('./errors.cjs');
 const require_index = require('./fees/index.cjs');
 const require_index$1 = require('./headers/index.cjs');
 const require_index$2 = require('./http-helpers/index.cjs');
+const require_orderAsset = require('./order-builder/helpers/orderAsset.cjs');
 const require_signatureTypeV2 = require('./order-utils/model/signatureTypeV2.cjs');
 const require_side = require('./order-utils/model/side.cjs');
 const require_clob = require('./types/clob.cjs');
@@ -15,7 +16,6 @@ const require_calculateBuyMarketPrice = require('./order-builder/helpers/calcula
 const require_calculateSellMarketPrice = require('./order-builder/helpers/calculateSellMarketPrice.cjs');
 const require_roundingConfig = require('./order-builder/helpers/roundingConfig.cjs');
 const require_orderBuilder = require('./order-builder/orderBuilder.cjs');
-const require_protocol = require('./protocol.cjs');
 
 //#region src/client.ts
 const RESOLVE_TRADES_TIMEOUT_MS = 3e4;
@@ -40,6 +40,8 @@ var ClobClient = class {
 	signatureType;
 	funderAddress;
 	cachedVersion;
+	versionRequest;
+	marketInfoRequests = /* @__PURE__ */ new Map();
 	retryOnError;
 	throwOnError;
 	feeSlippage;
@@ -80,8 +82,26 @@ var ClobClient = class {
 			data: { heartbeat_id: heartbeatId }
 		});
 	}
+	/**
+	* Fetches the current order version from the server and adopts it for the
+	* orders this client signs afterwards. Joins a version request that is
+	* already in flight. An error response yields the default version 2, which
+	* the first order corrects through the order version mismatch recovery.
+	* Throws ApiError when the client was created with throwOnError.
+	*/
 	async getVersion() {
-		return (await this.get(`${this.host}/version`))?.version ?? 2;
+		return this.versionRequest ?? this.startVersionRequest();
+	}
+	startVersionRequest() {
+		const request = this.get(`${this.host}/version`).then((response) => {
+			const version = response?.version ?? 2;
+			this.cachedVersion = version;
+			return version;
+		}).finally(() => {
+			if (this.versionRequest === request) this.versionRequest = void 0;
+		});
+		this.versionRequest = request;
+		return request;
 	}
 	async getServerTime() {
 		return this.get(`${this.host}${require_endpoints.TIME}`);
@@ -101,7 +121,23 @@ var ClobClient = class {
 	async getMarket(conditionID) {
 		return this.get(`${this.host}${require_endpoints.GET_MARKET}${conditionID}`);
 	}
+	/**
+	* Fetches the market parameters for a condition and caches the tick size,
+	* neg-risk flag, and fee details of both outcomes for later orders. Every
+	* call refreshes the caches. Concurrent calls for a condition share one request.
+	*/
 	async getClobMarketInfo(conditionID) {
+		const pending = this.marketInfoRequests.get(conditionID);
+		if (pending) return pending;
+		const request = this.fetchClobMarketInfo(conditionID);
+		this.marketInfoRequests.set(conditionID, request);
+		try {
+			return await request;
+		} finally {
+			this.marketInfoRequests.delete(conditionID);
+		}
+	}
+	async fetchClobMarketInfo(conditionID) {
 		const result = await this.get(`${this.host}${require_endpoints.GET_CLOB_MARKET}${conditionID}`);
 		if (!result?.t) throw new Error(`failed to fetch market info for condition id ${conditionID}`);
 		for (const token of result.t) {
@@ -430,16 +466,17 @@ var ClobClient = class {
 		this.canL1Auth();
 		const orderToSign = { ...userOrder };
 		if (this.builderConfig?.builderCode && !orderToSign.builderCode) orderToSign.builderCode = this.builderConfig.builderCode;
-		const { tokenID } = orderToSign;
-		const tickSize = await this._resolveTickSize(tokenID, options?.tickSize);
+		const routing = require_orderAsset.resolveOrderRouting(orderToSign, options?.version);
+		const { assetID } = routing;
+		const tickSize = await this._resolveTickSize(assetID, options?.tickSize);
 		if (!require_utilities.priceValid(orderToSign.price, tickSize)) throw new Error(`invalid price (${orderToSign.price}), min: ${parseFloat(tickSize)} - max: ${1 - parseFloat(tickSize)}`);
 		orderToSign.price = require_utilities.roundNormal(orderToSign.price, require_roundingConfig.ROUNDING_CONFIG[tickSize].price);
-		const version = await this.resolveOrderVersion(tokenID, options?.version);
-		if (version !== 1 && orderToSign.side === require_side.Side.BUY && "userUSDCBalance" in orderToSign && orderToSign.userUSDCBalance !== void 0) orderToSign.size = await this.adjustBuyAmountForBalance(tokenID, orderToSign.size * orderToSign.price, orderToSign.price, orderToSign.userUSDCBalance, orderToSign.builderCode) / orderToSign.price;
-		const negRisk = options?.negRisk ?? await this.getNegRisk(tokenID);
+		const version = routing.exchangeVersion ?? await this.resolveVersion();
+		if (version !== 1 && orderToSign.side === require_side.Side.BUY && "userUSDCBalance" in orderToSign && orderToSign.userUSDCBalance !== void 0) orderToSign.size = await this.adjustBuyAmountForBalance(assetID, orderToSign.size * orderToSign.price, orderToSign.price, orderToSign.userUSDCBalance, orderToSign.builderCode) / orderToSign.price;
+		const negRisk = version === 3 ? false : options?.negRisk ?? await this.getNegRisk(assetID);
 		if (version === 1) {
 			const userFeeRateBps = "feeRateBps" in orderToSign ? orderToSign.feeRateBps : void 0;
-			orderToSign.feeRateBps = await this._resolveFeeRateBps(tokenID, userFeeRateBps);
+			orderToSign.feeRateBps = await this._resolveFeeRateBps(assetID, userFeeRateBps);
 		}
 		return this.orderBuilder.buildOrder(orderToSign, {
 			tickSize,
@@ -448,23 +485,24 @@ var ClobClient = class {
 	}
 	async createMarketOrder(userMarketOrder, options) {
 		this.canL1Auth();
-		const { tokenID } = userMarketOrder;
-		await this._ensureMarketInfoCached(tokenID);
-		const tickSize = await this._resolveTickSize(tokenID, options?.tickSize);
-		if (!userMarketOrder.price) userMarketOrder.price = await this.calculateMarketPrice(tokenID, userMarketOrder.side, userMarketOrder.amount, userMarketOrder.orderType);
+		const routing = require_orderAsset.resolveOrderRouting(userMarketOrder, options?.version);
+		const { assetID } = routing;
+		await this._ensureMarketInfoCached(assetID);
+		const tickSize = await this._resolveTickSize(assetID, options?.tickSize);
+		if (!userMarketOrder.price) userMarketOrder.price = await this.calculateMarketPrice(assetID, userMarketOrder.side, userMarketOrder.amount, userMarketOrder.orderType);
 		if (!require_utilities.priceValid(userMarketOrder.price, tickSize)) throw new Error(`invalid price (${userMarketOrder.price}), min: ${parseFloat(tickSize)} - max: ${1 - parseFloat(tickSize)}`);
 		const orderToSign = { ...userMarketOrder };
 		if (this.builderConfig?.builderCode && !orderToSign.builderCode) orderToSign.builderCode = this.builderConfig.builderCode;
 		await this.ensureBuilderFeeRateCached(orderToSign.builderCode);
 		if (orderToSign.side === require_side.Side.BUY && "userUSDCBalance" in orderToSign && orderToSign.userUSDCBalance !== void 0) {
 			const price = orderToSign.price;
-			orderToSign.amount = await this.adjustBuyAmountForBalance(tokenID, orderToSign.amount, price, orderToSign.userUSDCBalance, orderToSign.builderCode);
+			orderToSign.amount = await this.adjustBuyAmountForBalance(assetID, orderToSign.amount, price, orderToSign.userUSDCBalance, orderToSign.builderCode);
 		}
-		const negRisk = options?.negRisk ?? await this.getNegRisk(tokenID);
-		const version = await this.resolveOrderVersion(tokenID, options?.version);
+		const version = routing.exchangeVersion ?? await this.resolveVersion();
+		const negRisk = version === 3 ? false : options?.negRisk ?? await this.getNegRisk(assetID);
 		if (version === 1) {
 			const userFeeRateBps = "feeRateBps" in orderToSign ? orderToSign.feeRateBps : void 0;
-			orderToSign.feeRateBps = await this._resolveFeeRateBps(tokenID, userFeeRateBps);
+			orderToSign.feeRateBps = await this._resolveFeeRateBps(assetID, userFeeRateBps);
 		}
 		return this.orderBuilder.buildMarketOrder(orderToSign, {
 			tickSize,
@@ -478,20 +516,16 @@ var ClobClient = class {
 		return this.orderBuilder.buildExchangeV3OrderFromAmounts(orderToSign);
 	}
 	async createAndPostOrder(userOrder, options, orderType = require_clob.OrderType.GTC, postOnly = false, deferExec = false) {
-		let postOrderResponse;
-		await this._retryOnVersionUpdate(userOrder.tokenID, options?.version, async () => {
+		return this._retryOnVersionUpdate(async () => {
 			const order = await this.createOrder(userOrder, options);
-			postOrderResponse = await this.postOrder(order, orderType, postOnly, deferExec);
+			return this.postOrder(order, orderType, postOnly, deferExec);
 		});
-		return postOrderResponse;
 	}
 	async createAndPostMarketOrder(userMarketOrder, options, orderType = require_clob.OrderType.FOK, deferExec = false) {
-		let postOrderMarketResponse;
-		await this._retryOnVersionUpdate(userMarketOrder.tokenID, options?.version, async () => {
+		return this._retryOnVersionUpdate(async () => {
 			const order = await this.createMarketOrder(userMarketOrder, options);
-			postOrderMarketResponse = await this.postOrder(order, orderType, false, deferExec);
+			return this.postOrder(order, orderType, false, deferExec);
 		});
-		return postOrderMarketResponse;
 	}
 	async getOpenOrders(params, only_first_page = false, next_cursor) {
 		this.canL2Auth();
@@ -871,6 +905,7 @@ var ClobClient = class {
 			if (!result?.condition_id) throw new Error(`failed to resolve condition id for token ${tokenID}`);
 			this.tokenConditionMap[tokenID] = result.condition_id;
 		}
+		if (tokenID in this.feeInfos) return;
 		await this.getClobMarketInfo(this.tokenConditionMap[tokenID]);
 	}
 	async ensureBuilderFeeRateCached(builderCode) {
@@ -894,25 +929,20 @@ var ClobClient = class {
 		if (marketFeeRateBps > 0 && userFeeRateBps !== void 0 && userFeeRateBps !== marketFeeRateBps) throw new Error(`invalid user provided fee rate: ${userFeeRateBps}, fee rate for the market must be ${marketFeeRateBps}`);
 		return marketFeeRateBps;
 	}
-	async resolveOrderVersion(tokenID, version) {
-		return version ?? (require_protocol.isV2PositionId(tokenID) ? 3 : this.resolveVersion());
-	}
 	async resolveVersion(forceUpdate = false) {
 		if (!forceUpdate && this.cachedVersion !== void 0) return this.cachedVersion;
-		const apiVersion = await this.getVersion();
-		this.cachedVersion = apiVersion;
-		return apiVersion;
-	}
-	async _retryOnVersionUpdate(tokenID, explicitVersion, retryFunc) {
-		if (explicitVersion != null || require_protocol.isV2PositionId(tokenID)) {
-			await retryFunc();
-			return;
-		}
-		const version = await this.resolveVersion();
-		for (let attempt = 0; attempt < 2; attempt++) {
-			await retryFunc();
-			if (version === await this.resolveVersion()) break;
+		if (!forceUpdate && this.versionRequest) return this.versionRequest;
+		return this.startVersionRequest();
+	}
+	async _retryOnVersionUpdate(attempt) {
+		try {
+			const response = await attempt();
+			if (!this._isOrderVersionMismatch(response)) return response;
+		} catch (err) {
+			const data = err instanceof require_errors.ApiError ? err.data : void 0;
+			if (!this._isOrderVersionMismatch(data)) throw err;
 		}
+		return attempt();
 	}
 	_isOrderVersionMismatch(resp) {
 		const error = resp?.error;