@kuestcom/clob-client 5.8.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 Polymarket
+Copyright (c) 2026 Kuest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# Kuest CLOB Client
+
+<a href='https://www.npmjs.com/package/@kuestcom/clob-client'>
+    <img src='https://img.shields.io/npm/v/@kuestcom/clob-client.svg' alt='NPM'/>
+</a>
+
+Typescript client for the Kuest CLOB
+
+### Usage
+
+```ts
+// npm install @kuestcom/clob-client
+// npm install ethers
+// Client initialization example and dumping API Keys
+
+import { ApiKeyCreds, ClobClient, OrderType, Side, } from "@kuestcom/clob-client";
+import { Wallet } from "@ethersproject/wallet";
+
+const host = 'https://clob.kuest.com';
+const funder = ''; // This is your Kuest Profile Address, where you send UDSC to. 
+const signer = new Wallet(""); // This is your Private Key.
+
+
+// In general don't create a new API key, always derive or createOrDerive
+const creds = new ClobClient(host, 80002, signer).createOrDeriveApiKey();
+
+//0: Browser Wallet(Metamask, Coinbase Wallet, etc)
+//1: Magic/Email Login
+const signatureType = 1; 
+  (async () => {
+    const clobClient = new ClobClient(host, 80002, signer, await creds, signatureType, funder);
+    const resp2 = await clobClient.createAndPostOrder(
+        {
+            tokenID: "", //Use https://docs.kuest.com/developers/gamma-markets-api/get-markets to grab a sample token
+            price: 0.01,
+            side: Side.BUY,
+            size: 5,
+        },
+        { tickSize: "0.001",negRisk: false }, //You'll need to adjust these based on the market. Get the tickSize and negRisk T/F from the get-markets above
+        //{ tickSize: "0.001",negRisk: true },
+
+        OrderType.GTC, 
+    );
+    console.log(resp2)
+  })();
+```
+
+See [examples](examples/) for more information
+
+### Builder signing
+
+Builder signing: disabled.
+To enable later, remove line 145 of `src/client.ts`: `const BUILDER_SIGNING_ENABLED = false;`
+
+### Using viem WalletClient
+
+```ts
+import { ClobClient } from "@kuestcom/clob-client";
+import { createWalletClient, http } from "viem";
+import { polygonAmoy } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+
+const host = "https://clob.kuest.com";
+const account = privateKeyToAccount("0x...");
+const walletClient = createWalletClient({
+    account,
+    chain: polygonAmoy,
+    transport: http(),
+});
+
+const clobClient = new ClobClient(host, 80002, walletClient);
+```
+
+### Error Handling
+
+By default, API errors are returned as `{ error: "...", status: ... }` objects. To have the client throw errors instead, pass `throwOnError: true` as the last constructor argument:
+
+```ts
+import { ClobClient, ApiError } from "@kuestcom/clob-client";
+
+const clobClient = new ClobClient(
+    host, 80002, signer, await creds, signatureType, funder,
+    undefined, // geoBlockToken
+    undefined, // useServerTime
+    undefined, // builderConfig
+    undefined, // getSigner
+    undefined, // retryOnError
+    undefined, // tickSizeTtlMs
+    true,      // throwOnError
+);
+
+try {
+    const book = await clobClient.getOrderBook(tokenID);
+} catch (e) {
+    if (e instanceof ApiError) {
+        console.log(e.message); // "No orderbook exists for the requested token id"
+        console.log(e.status);  // 404
+        console.log(e.data);    // full error response object from the API
+    }
+}
+```

package/dist/client.d.ts

@@ -0,0 +1,164 @@
+import type { BuilderConfig } from "@kuestcom/builder-signing-sdk";
+import type { RequestOptions } from "./http-helpers/index.ts";
+import { OrderBuilder } from "./order-builder/builder.ts";
+import type { SignatureType, SignedOrder } from "./order-utils/index.ts";
+import type { IRfqClient } from "./rfq-deps.ts";
+import type { ClobSigner } from "./signer.ts";
+import type { ApiKeyCreds, ApiKeysResponse, BalanceAllowanceParams, BalanceAllowanceResponse, BanStatus, BookParams, BuilderApiKey, BuilderApiKeyResponse, BuilderTrade, Chain, CreateOrderOptions, DropNotificationParams, FeeRates, HeartbeatResponse, MarketPrice, MarketReward, MarketTradeEvent, NegRisk, Notification, OpenOrder, OpenOrderParams, OpenOrdersResponse, OrderBookSummary, OrderMarketCancelParams, OrderPayload, OrderScoring, OrderScoringParams, OrdersScoring, OrdersScoringParams, PaginationPayload, PostOrdersArgs, PriceHistoryFilterParams, ReadonlyApiKeyResponse, RewardsPercentages, TickSize, TickSizes, TotalUserEarning, Trade, TradeParams, UserEarning, UserMarketOrder, UserOrder, UserRewardsEarning } from "./types.ts";
+import { OrderType, Side } from "./types.ts";
+export declare class ClobClient {
+    readonly host: string;
+    readonly chainId: Chain;
+    readonly signer?: ClobSigner;
+    readonly creds?: ApiKeyCreds;
+    readonly orderBuilder: OrderBuilder;
+    readonly tickSizes: TickSizes;
+    readonly negRisk: NegRisk;
+    readonly feeRates: FeeRates;
+    readonly geoBlockToken?: string;
+    readonly useServerTime?: boolean;
+    readonly builderConfig?: BuilderConfig;
+    readonly rfq: IRfqClient;
+    readonly retryOnError?: boolean;
+    readonly throwOnError: boolean;
+    private tickSizeTimestamps;
+    private readonly tickSizeTtlMs;
+    constructor(host: string, chainId: Chain, signer?: ClobSigner, creds?: ApiKeyCreds, signatureType?: SignatureType, funderAddress?: string, geoBlockToken?: string, useServerTime?: boolean, builderConfig?: BuilderConfig, getSigner?: () => Promise<ClobSigner> | ClobSigner, retryOnError?: boolean, tickSizeTtlMs?: number, throwOnError?: boolean);
+    getOk(): Promise<any>;
+    getServerTime(): Promise<number>;
+    getSamplingSimplifiedMarkets(next_cursor?: string): Promise<PaginationPayload>;
+    getSamplingMarkets(next_cursor?: string): Promise<PaginationPayload>;
+    getSimplifiedMarkets(next_cursor?: string): Promise<PaginationPayload>;
+    getMarkets(next_cursor?: string): Promise<PaginationPayload>;
+    getMarket(conditionID: string): Promise<any>;
+    getOrderBook(tokenID: string): Promise<OrderBookSummary>;
+    getOrderBooks(params: BookParams[]): Promise<OrderBookSummary[]>;
+    getTickSize(tokenID: string): Promise<TickSize>;
+    /**
+     * Clears the tick size cache, forcing fresh fetches on the next access.
+     * @param tokenID - If provided, only clears the cache for this token. Otherwise clears all.
+     */
+    clearTickSizeCache(tokenID?: string): void;
+    getNegRisk(tokenID: string): Promise<boolean>;
+    getFeeRateBps(tokenID: string): Promise<number>;
+    /**
+     * Calculates the hash for the given orderbook
+     * @param orderbook
+     * @returns
+     */
+    getOrderBookHash(orderbook: OrderBookSummary): Promise<string>;
+    getMidpoint(tokenID: string): Promise<any>;
+    getMidpoints(params: BookParams[]): Promise<any>;
+    getPrice(tokenID: string, side: string): Promise<any>;
+    getPrices(params: BookParams[]): Promise<any>;
+    getSpread(tokenID: string): Promise<any>;
+    getSpreads(params: BookParams[]): Promise<any>;
+    getLastTradePrice(tokenID: string): Promise<any>;
+    getLastTradesPrices(params: BookParams[]): Promise<any>;
+    getPricesHistory(params: PriceHistoryFilterParams): Promise<MarketPrice[]>;
+    /**
+     * Creates a new API key for a user
+     * @param nonce
+     * @returns ApiKeyCreds
+     */
+    createApiKey(nonce?: number): Promise<ApiKeyCreds>;
+    /**
+     * Derives an existing API key for a user
+     * @param nonce
+     * @returns ApiKeyCreds
+     */
+    deriveApiKey(nonce?: number): Promise<ApiKeyCreds>;
+    createOrDeriveApiKey(nonce?: number): Promise<ApiKeyCreds>;
+    getApiKeys(): Promise<ApiKeysResponse>;
+    getClosedOnlyMode(): Promise<BanStatus>;
+    deleteApiKey(): Promise<any>;
+    /**
+     * Creates a new readonly API key for a user
+     * @returns ReadonlyApiKeyResponse
+     */
+    createReadonlyApiKey(): Promise<ReadonlyApiKeyResponse>;
+    getReadonlyApiKeys(): Promise<string[]>;
+    /**
+     * Deletes a readonly API key for a user
+     * @param key The readonly API key to delete
+     * @returns boolean
+     */
+    deleteReadonlyApiKey(key: string): Promise<boolean>;
+    /**
+     * Validates a readonly API key for a given address
+     * @param address The wallet address
+     * @param key The readonly API key to validate
+     * @returns string
+     */
+    validateReadonlyApiKey(address: string, key: string): Promise<string>;
+    getOrder(orderID: string): Promise<OpenOrder>;
+    getTrades(params?: TradeParams, only_first_page?: boolean, next_cursor?: string): Promise<Trade[]>;
+    getTradesPaginated(params?: TradeParams, next_cursor?: string): Promise<{
+        trades: Trade[];
+        next_cursor: string;
+        limit: number;
+        count: number;
+    }>;
+    getBuilderTrades(params?: TradeParams, next_cursor?: string): Promise<{
+        trades: BuilderTrade[];
+        next_cursor: string;
+        limit: number;
+        count: number;
+    }>;
+    getNotifications(): Promise<Notification[]>;
+    dropNotifications(params?: DropNotificationParams): Promise<void>;
+    getBalanceAllowance(params?: BalanceAllowanceParams): Promise<BalanceAllowanceResponse>;
+    updateBalanceAllowance(params?: BalanceAllowanceParams): Promise<void>;
+    createOrder(userOrder: UserOrder, options?: Partial<CreateOrderOptions>): Promise<SignedOrder>;
+    createMarketOrder(userMarketOrder: UserMarketOrder, options?: Partial<CreateOrderOptions>): Promise<SignedOrder>;
+    createAndPostOrder<T extends OrderType.GTC | OrderType.GTD = OrderType.GTC>(userOrder: UserOrder, options?: Partial<CreateOrderOptions>, orderType?: T, deferExec?: boolean, postOnly?: boolean): Promise<any>;
+    createAndPostMarketOrder<T extends OrderType.FOK | OrderType.FAK = OrderType.FOK>(userMarketOrder: UserMarketOrder, options?: Partial<CreateOrderOptions>, orderType?: T, deferExec?: boolean): Promise<any>;
+    getOpenOrders(params?: OpenOrderParams, only_first_page?: boolean, next_cursor?: string): Promise<OpenOrdersResponse>;
+    postOrder<T extends OrderType = OrderType.GTC>(order: SignedOrder, orderType?: T, deferExec?: boolean, postOnly?: boolean): Promise<any>;
+    postOrders(args: PostOrdersArgs[], deferExec?: boolean, defaultPostOnly?: boolean): Promise<any>;
+    cancelOrder(payload: OrderPayload): Promise<any>;
+    cancelOrders(ordersHashes: string[]): Promise<any>;
+    cancelAll(): Promise<any>;
+    /**
+     * Sends a heartbeat to the server to keep the session active.
+     *
+     * If heartbeats are started and one isn't sent within 10s, all orders will be cancelled.
+     * Requires Level 2 authentication.
+     *
+     * Pass the previously returned `heartbeat_id` to chain heartbeats.
+     * Pass `undefined`/`null` to start a new heartbeat chain.
+     */
+    postHeartbeat(heartbeatId?: string | null): Promise<HeartbeatResponse>;
+    cancelMarketOrders(payload: OrderMarketCancelParams): Promise<any>;
+    isOrderScoring(params?: OrderScoringParams): Promise<OrderScoring>;
+    areOrdersScoring(params?: OrdersScoringParams): Promise<OrdersScoring>;
+    getEarningsForUserForDay(date: string): Promise<UserEarning[]>;
+    getTotalEarningsForUserForDay(date: string): Promise<TotalUserEarning[]>;
+    getUserEarningsAndMarketsConfig(date: string, order_by?: string, position?: string, no_competition?: boolean): Promise<UserRewardsEarning[]>;
+    getRewardPercentages(): Promise<RewardsPercentages>;
+    getCurrentRewards(): Promise<MarketReward[]>;
+    getRawRewardsForMarket(conditionId: string): Promise<MarketReward[]>;
+    getMarketTradesEvents(conditionID: string): Promise<MarketTradeEvent[]>;
+    calculateMarketPrice(tokenID: string, side: Side, amount: number, orderType?: OrderType): Promise<number>;
+    createBuilderApiKey(): Promise<BuilderApiKey>;
+    getBuilderApiKeys(): Promise<BuilderApiKeyResponse[]>;
+    revokeBuilderApiKey(): Promise<any>;
+    protected _resolveTickSize(tokenID: string, tickSize?: TickSize): Promise<TickSize>;
+    protected get(endpoint: string, options?: RequestOptions): Promise<any>;
+    protected post(endpoint: string, options?: RequestOptions): Promise<any>;
+    protected put(endpoint: string, options?: RequestOptions): Promise<any>;
+    protected del(endpoint: string, options?: RequestOptions): Promise<any>;
+    private throwIfError;
+    private canL1Auth;
+    private canL2Auth;
+    private mustBuilderAuth;
+    private canBuilderAuth;
+    private ensureBuilderSigningEnabled;
+    private _resolveFeeRateBps;
+    private _generateBuilderHeaders;
+    private _getBuilderHeaders;
+    /**
+     * Opportunistically updates the tick size cache from an order book response.
+     */
+    private updateTickSizeFromOrderBook;
+}