@ctgexchange/sdk 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,467 @@
+import { WebSocket } from 'ws';
+
+/**
+ * Types for CTG.EXCHANGE API payloads.
+ *
+ * The API's **decimal contract**: every monetary value — `price`, `qty`,
+ * `volume`, fee amounts — is a JSON **string** (`"3500.55"`), never a
+ * number. This SDK keeps those fields as `string`: that is lossless and
+ * leaves the choice of big-decimal library to you. Never `Number()`
+ * them blindly. Basis-point fields, counters, ids and epoch timestamps
+ * are real `number`s; `created_at` is an RFC 3339 `string`.
+ */
+/** A trading pair plus its order filters. All money fields are strings. */
+interface SymbolInfo {
+    symbol: string;
+    base_asset: string;
+    quote_asset: string;
+    price_scale: number;
+    qty_scale: number;
+    quote_asset_scale: number;
+    tick_size: string;
+    step_size: string;
+    min_price: string;
+    max_price: string;
+    min_qty: string;
+    max_qty: string;
+    min_notional: string;
+}
+/** A 24h rolling ticker. */
+interface Ticker {
+    symbol: string;
+    price: string;
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    /** Base-asset volume. */
+    volume: string;
+    trades: number;
+    change_bps: number;
+    /** Epoch timestamp. */
+    ts: number;
+}
+/** A single OHLC candle. */
+interface Candle {
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    volume: string;
+    open_time: number;
+    close_time: number;
+    trades: number;
+}
+/** One price level of an order book. */
+interface BookLevel {
+    price: string;
+    qty: string;
+}
+/** A full order book snapshot. */
+interface OrderBook {
+    symbol: string;
+    last_update_id: number;
+    bids: BookLevel[];
+    asks: BookLevel[];
+}
+/** A per-asset balance. */
+interface Balance {
+    asset: string;
+    available: string;
+    reserved: string;
+}
+type OrderSide = "buy" | "sell";
+type OrderType = "limit" | "market";
+type OrderStatus = "new" | "open" | "partially_filled" | "filled" | "canceled" | "expired" | "rejected";
+type TimeInForce = "GTC" | "IOC" | "FOK" | "POST_ONLY";
+/** Fraction of a charged fee credited to a referrer. */
+interface FeeRebate {
+    /** Referrer wallet address. */
+    account_id?: string;
+    /** Share of the fee in basis points. */
+    fraction_bps?: number;
+}
+/** An order. */
+interface Order {
+    /** Canonical server id (UUIDv7). */
+    id: string;
+    /** Client-supplied idempotency key. */
+    client_order_id?: string;
+    /** Owner wallet address. */
+    uid?: string;
+    symbol: string;
+    side: OrderSide;
+    type: OrderType;
+    time_in_force?: TimeInForce;
+    status: OrderStatus;
+    price: string;
+    avg_execution_price?: string;
+    qty: string;
+    filled_qty: string;
+    remaining_qty: string;
+    /** Total fee paid, a decimal string in the scale of `fee_asset`. */
+    fee_amount?: string;
+    fee_asset?: string;
+    /** Per-order taker fee override in bps; 0 = global default. */
+    taker_fee_bps?: number;
+    /** Per-order maker fee override in bps; 0 = global default. */
+    maker_fee_bps?: number;
+    rebate?: FeeRebate;
+    created_at: string;
+    updated_at?: string;
+}
+/**
+ * A matched trade. Both sides' addresses, order ids and fees are
+ * exposed — see "matcher transparency".
+ */
+interface Trade {
+    id: string;
+    symbol: string;
+    price: string;
+    qty: string;
+    /** Side of the taker (aggressor) order. */
+    aggressor_side?: OrderSide;
+    maker_order_id?: string;
+    taker_order_id?: string;
+    buy_order_id?: string;
+    sell_order_id?: string;
+    /** Buyer wallet address. */
+    buy_uid?: string;
+    /** Seller wallet address. */
+    sell_uid?: string;
+    /** Effective buyer fee in bps; omitted when 0. */
+    buy_fee_bps?: number;
+    /** Effective seller fee in bps; omitted when 0. */
+    sell_fee_bps?: number;
+    buy_rebate?: FeeRebate;
+    sell_rebate?: FeeRebate;
+    buy_fee_amount?: string;
+    buy_fee_asset?: string;
+    sell_fee_amount?: string;
+    sell_fee_asset?: string;
+    created_at?: string;
+}
+/** A referral rebate entry. */
+interface Rebate {
+    referrer_account: string;
+    fraction_bps: number;
+}
+/**
+ * A fee / rebate snapshot. A `null` integer means no override applies —
+ * the platform default is then in effect.
+ */
+interface UserFees {
+    taker_fee_bps: number | null;
+    maker_fee_bps: number | null;
+    rebate: Rebate | null;
+}
+/** The result of placing an order: the order plus any immediate fills. */
+interface PlaceOrderResult {
+    order: Order;
+    trades: Trade[];
+}
+/** Parameters for placing an order. */
+interface PlaceOrderParams {
+    side: OrderSide;
+    type: OrderType;
+    /** Decimal string (recommended) or number. */
+    price?: string | number;
+    /** Decimal string (recommended) or number. */
+    qty?: string | number;
+    /** Optional idempotency key; one is generated when omitted. */
+    clientOrderId?: string;
+}
+/** Parameters for modifying an order — send both for the API to accept. */
+interface ModifyOrderParams {
+    newPrice?: string | number;
+    newQty?: string | number;
+}
+/** A parsed server WebSocket message: a `snapshot` or an `update`. */
+interface StreamMessage {
+    type: "snapshot" | "update";
+    channel: string;
+    symbol?: string;
+    data: unknown;
+    /** The full raw frame. */
+    raw: Record<string, unknown>;
+}
+
+/**
+ * REST client for the CTG.EXCHANGE API.
+ *
+ * Covers the whole `/api/v1` REST surface: public market data plus the
+ * private, API-key-signed account and order endpoints.
+ *
+ *     const client = new Client({ apiKey, apiSecret });
+ *     const book = await client.getOrderBook("CTGUSDT");
+ */
+
+declare const DEFAULT_BASE_URL = "https://api.ctg.exchange";
+/** A `fetch`-compatible function — injectable for testing. */
+type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+interface ClientOptions {
+    /** Key id (`ak_...`). Required only for private endpoints. */
+    apiKey?: string;
+    /** Key secret (`sk_...`). Required only for private endpoints. */
+    apiSecret?: string;
+    /** REST base URL. Defaults to production. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 10000. */
+    timeoutMs?: number;
+    /** How many times to retry a `429`, honouring `Retry-After`. Default 0. */
+    maxRetries?: number;
+    /** A `fetch` implementation. Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+}
+/** A REST client for the CTG.EXCHANGE API. */
+declare class Client {
+    private readonly apiKey?;
+    private readonly apiSecret?;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options?: ClientOptions);
+    private buildRequestUri;
+    private request;
+    /** All trading symbols with their order filters. */
+    getSymbols(): Promise<SymbolInfo[]>;
+    /** 24h ticker for every symbol. */
+    getTickers(): Promise<Ticker[]>;
+    /** Current order book for `symbol`. */
+    getOrderBook(symbol: string): Promise<OrderBook>;
+    /** 24h ticker for `symbol`. */
+    getTicker(symbol: string): Promise<Ticker>;
+    /**
+     * Candles for `symbol` at `interval` (`1m` / `5m` / `15m` / `1h` /
+     * `4h` / `1d`).
+     *
+     * Omit `from` / `to` for the latest `limit` candles. Pass `from` /
+     * `to` (Unix ms) to select a historical window `[from, to)` for
+     * scrollback.
+     */
+    getCandles(symbol: string, interval?: string, opts?: {
+        limit?: number;
+        from?: number;
+        to?: number;
+    }): Promise<Candle[]>;
+    /** Recent public trade prints for `symbol`. */
+    getTrades(symbol: string, limit?: number): Promise<Trade[]>;
+    /** Per-asset balances for the API key's owner (scope: read). */
+    getBalances(): Promise<Balance[]>;
+    /** Fee/rebate snapshot for the API key's owner (scope: read). */
+    getFees(): Promise<UserFees>;
+    /**
+     * Place an order (scope: trade).
+     *
+     * A `clientOrderId` is generated when you do not supply one — it lets
+     * the engine de-dup on safe retries.
+     */
+    placeOrder(symbol: string, params: PlaceOrderParams): Promise<PlaceOrderResult>;
+    /** List the owner's orders for `symbol` (scope: read). */
+    getOrders(symbol: string, opts?: {
+        status?: OrderStatus;
+        limit?: number;
+        offset?: number;
+    }): Promise<Order[]>;
+    /**
+     * List every open order across all symbols (scope: read).
+     *
+     * Each `Order` carries its own `symbol`; decimal fields are converted
+     * per that order's scales. For closed-order history use `getOrders`
+     * per symbol.
+     */
+    getOpenOrders(): Promise<Order[]>;
+    /** Get one order by its canonical server id (scope: read). */
+    getOrder(symbol: string, orderId: string): Promise<Order>;
+    /** Cancel one order (scope: trade). */
+    cancelOrder(symbol: string, orderId: string): Promise<Order>;
+    /** Cancel every open order for `symbol` (scope: trade). */
+    cancelAllOrders(symbol: string): Promise<Order[]>;
+    /**
+     * Modify a resting order's price and quantity (scope: trade).
+     *
+     * The API expects the full new state — pass both `newPrice` and
+     * `newQty`.
+     */
+    modifyOrder(symbol: string, orderId: string, params: ModifyOrderParams): Promise<Order>;
+    /** The owner's trade history for `symbol` (scope: read). */
+    getMyTrades(symbol: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Trade[]>;
+}
+
+/**
+ * WebSocket clients for the CTG.EXCHANGE streams.
+ *
+ * - {@link MarketDataStream} — public market data, no auth.
+ * - {@link UserStream} — the caller's private `orders` / `trades` /
+ *   `balances`, authenticated in-band with a signed first frame.
+ *
+ * Both auto-reconnect by default and re-send their subscriptions on
+ * every (re)connect, so a dropped socket is transparent to the
+ * consumer:
+ *
+ *     const stream = new MarketDataStream({ channels: ["trades@CTGUSDT"] });
+ *     for await (const msg of stream) {
+ *       console.log(msg.channel, msg.type, msg.data);
+ *     }
+ */
+
+declare const DEFAULT_WS_BASE_URL = "wss://api.ctg.exchange";
+/**
+ * Parse a raw frame into a {@link StreamMessage}, or `null` for control
+ * frames (auth replies, subscribe acks) — only data frames are surfaced.
+ */
+declare function parseFrame(raw: string): StreamMessage | null;
+interface StreamOptions {
+    /** WebSocket base URL. Defaults to production. */
+    baseUrl?: string;
+    /** Channels to subscribe to on every (re)connect. */
+    channels?: Iterable<string>;
+    /** Auto-reconnect on a dropped socket. Default `true`. */
+    reconnect?: boolean;
+    /** Delay before a reconnect attempt, in milliseconds. Default 2000. */
+    reconnectDelayMs?: number;
+}
+/** Shared connect / subscribe / reconnect machinery. */
+declare abstract class BaseStream implements AsyncIterable<StreamMessage> {
+    private readonly url;
+    private readonly channels;
+    private reconnect;
+    private readonly reconnectDelayMs;
+    private ws;
+    private closed;
+    private queue;
+    private socketEnded;
+    private resolveNext;
+    protected constructor(path: string, options: StreamOptions);
+    /** No-op for the public stream; overridden by {@link UserStream}. */
+    protected authenticate(_ws: WebSocket): Promise<void>;
+    /** Close the socket and stop reconnecting. */
+    close(): void;
+    /** Add channels (e.g. `orderbook@CTGUSDT`). Kept across reconnects. */
+    subscribe(channels: string | Iterable<string>): void;
+    /** Drop channels. */
+    unsubscribe(channels: string | Iterable<string>): void;
+    private send;
+    private wake;
+    private open;
+    private nextMessage;
+    [Symbol.asyncIterator](): AsyncGenerator<StreamMessage>;
+}
+/**
+ * Public market-data stream — `orderbook` / `ticker` / `candles` /
+ * `trades`. No authentication.
+ */
+declare class MarketDataStream extends BaseStream {
+    constructor(options?: StreamOptions);
+}
+interface UserStreamOptions extends StreamOptions {
+    /** Key id (`ak_...`). */
+    apiKey: string;
+    /** Key secret (`sk_...`). */
+    apiSecret: string;
+}
+/**
+ * Private stream — the caller's `orders` / `trades` / `balances`.
+ * Authenticates in-band with a signed first frame.
+ */
+declare class UserStream extends BaseStream {
+    private readonly apiKey;
+    private readonly apiSecret;
+    constructor(options: UserStreamOptions);
+    protected authenticate(ws: WebSocket): Promise<void>;
+}
+
+/**
+ * Typed errors for the CTG.EXCHANGE SDK.
+ *
+ * Every non-2xx REST response is thrown as an {@link ApiError} subclass
+ * chosen by status code. The exchange returns a JSON error body
+ * `{ error, message, request_id }` — `requestId` is surfaced on the
+ * error; quote it when reporting a problem.
+ */
+/** Base class for every error thrown by this SDK. */
+declare class CtgExchangeError extends Error {
+    constructor(message: string);
+}
+/** A non-2xx HTTP response from the API. */
+declare class ApiError extends CtgExchangeError {
+    readonly statusCode: number;
+    readonly apiError?: string;
+    readonly apiMessage?: string;
+    readonly requestId?: string;
+    constructor(statusCode: number, apiError?: string, apiMessage?: string, requestId?: string);
+}
+/** 400 — the request was malformed. */
+declare class BadRequestError extends ApiError {
+}
+/** 401 — missing, expired, unknown or wrong-signature API key. */
+declare class AuthenticationError extends ApiError {
+}
+/** 403 — the key lacks the required scope, or the IP is off-allowlist. */
+declare class PermissionDeniedError extends ApiError {
+}
+/** 404 — unknown symbol or order. */
+declare class NotFoundError extends ApiError {
+}
+/** 429 — per-key or per-IP rate limit exceeded. */
+declare class RateLimitError extends ApiError {
+    /** The `Retry-After` header value in seconds, when the server sent one. */
+    readonly retryAfter?: number;
+    constructor(statusCode: number, apiError?: string, apiMessage?: string, requestId?: string, retryAfter?: number);
+}
+/** 5xx — the API failed to handle a well-formed request. */
+declare class ServerError extends ApiError {
+}
+interface ErrorBody {
+    error?: string;
+    message?: string;
+    request_id?: string;
+}
+/** Map an HTTP status + JSON error body to the right error instance. */
+declare function errorFromResponse(statusCode: number, body: ErrorBody | undefined, retryAfter?: number): ApiError;
+
+/**
+ * HMAC-SHA256 request signing for the CTG.EXCHANGE API.
+ *
+ * Two signing schemes share one key secret:
+ *
+ * REST — the canonical string is four newline-joined fields:
+ *
+ *     <ts>\n<METHOD>\n<request-uri>\n<hex sha256 of body>
+ *
+ * WebSocket — the in-band auth frame signs the string `ws-auth\n<ts>`.
+ *
+ * Both produce a lowercase-hex HMAC-SHA256 keyed by the API key secret.
+ */
+/** Hex SHA-256 of a request body. `sha256("")` for an empty body. */
+declare function sha256Hex(body: string): string;
+/**
+ * Build the four-field canonical string a REST signature covers.
+ *
+ * `requestUri` is the path plus query string exactly as sent on the
+ * request line, e.g. `/api/v1/me/orders/CTGUSDT?limit=50`.
+ */
+declare function restCanonicalString(ts: number | string, method: string, requestUri: string, body?: string): string;
+/** Lowercase-hex HMAC-SHA256 of the REST canonical string. */
+declare function signRest(secret: string, ts: number | string, method: string, requestUri: string, body?: string): string;
+/**
+ * The three signed headers a private REST request must carry.
+ *
+ * `ts` defaults to the current Unix time in seconds; the server rejects
+ * timestamps outside its signature window (default 30s), so keep the
+ * local clock in sync.
+ */
+declare function restHeaders(keyId: string, secret: string, method: string, requestUri: string, body?: string, ts?: number): Record<string, string>;
+/** Lowercase-hex HMAC-SHA256 over `ws-auth\n<ts>`. */
+declare function signWsAuth(secret: string, ts: number | string): string;
+/** The signed `auth` frame to send first on the private WebSocket stream. */
+declare function wsAuthMessage(keyId: string, secret: string, ts?: number): {
+    op: "auth";
+    args: [string, number, string];
+};
+
+export { ApiError, AuthenticationError, BadRequestError, type Balance, type BookLevel, type Candle, Client, type ClientOptions, CtgExchangeError, DEFAULT_BASE_URL, DEFAULT_WS_BASE_URL, type FeeRebate, type FetchLike, MarketDataStream, type ModifyOrderParams, NotFoundError, type Order, type OrderBook, type OrderSide, type OrderStatus, type OrderType, PermissionDeniedError, type PlaceOrderParams, type PlaceOrderResult, RateLimitError, type Rebate, ServerError, type StreamMessage, type StreamOptions, type SymbolInfo, type Ticker, type TimeInForce, type Trade, type UserFees, UserStream, type UserStreamOptions, errorFromResponse, parseFrame, restCanonicalString, restHeaders, sha256Hex, signRest, signWsAuth, wsAuthMessage };