blink-trade-sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,288 @@
+/** Exact wire models for Blink API v1. Large integers are decimal strings. */
+export type MarketType = 'perp' | 'spot';
+export type Resolution = '1m' | '5m' | '15m' | '1h' | '4h' | '1d';
+export interface Status {
+    status: 'ok' | 'syncing' | 'degraded';
+    timestamp_ns: string;
+}
+export interface MarginTier {
+    tier: number;
+    notional_lower_bound_quote_lots: string;
+    max_leverage: number;
+    maintenance_margin_rate_bps: number;
+    maintenance_deduction_quote_lots: string;
+}
+export interface Market {
+    market_type: MarketType;
+    market_id: number;
+    symbol: string;
+    base_token: string;
+    quote_token: string;
+    quote_token_id?: string;
+    base_decimals: number;
+    quote_decimals: number;
+    base_atoms_per_base_lot: string;
+    quote_atoms_per_quote_lot: string;
+    base_lots_per_base_unit: string;
+    quote_lots_per_quote_unit: string;
+    quote_lots_per_base_unit_per_tick: string;
+    default_maker_fee_100th_bps: number;
+    default_taker_fee_100th_bps: number;
+    liquidation_fee_100th_bps?: number;
+    min_size_base_lots: string;
+    min_order_notional_quote_lots: string;
+    max_market_order_value_quote_lots?: string;
+    max_limit_order_value_quote_lots?: string;
+    max_leverage?: number;
+    oracle_id?: string;
+    fee_recipient?: string;
+    margin_tiers?: MarginTier[];
+    status: 'active' | 'reduce_only' | 'paused' | 'settled';
+}
+export interface MarketStats {
+    market_type: MarketType;
+    market_id: number;
+    timestamp_ns: string;
+    last_price_ticks?: string;
+    mark_price_ticks?: string;
+    oracle_price_ticks?: string;
+    mid_price_ticks?: string;
+    best_bid_price_ticks?: string;
+    best_ask_price_ticks?: string;
+    open_interest_base_lots?: string;
+    funding_rate_100th_bps?: number;
+    predicted_funding_rate_100th_bps?: number;
+    volume_24h_base_lots: string;
+    volume_24h_quote_lots: string;
+    trades_24h: string;
+    low_24h_price_ticks?: string;
+    high_24h_price_ticks?: string;
+    change_24h_bps?: number;
+}
+export interface PriceLevel {
+    price_ticks: string;
+    size_base_lots: string;
+}
+export interface Orderbook {
+    timestamp_ns: string;
+    sequence: string;
+    bids: PriceLevel[];
+    asks: PriceLevel[];
+}
+export interface Trade {
+    timestamp_ns: string;
+    sequence: string;
+    price_ticks: string;
+    size_base_lots: string;
+    quote_notional_lots: string;
+    taker_is_bid: boolean;
+}
+export interface Candle {
+    open_time_ms: number;
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    volume_base: string;
+    volume_quote: string;
+    trades: number;
+}
+export interface MarkCandle {
+    open_time_ms: number;
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    samples: number;
+}
+/**
+ * A delegation row. Nested under `Subaccount.delegations` it identifies the
+ * delegate and its permissions; in the websocket catalog and account channels
+ * it also carries the owning `subaccount_id` plus the optional expiry and name.
+ */
+export interface Delegation {
+    delegate: string;
+    permissions: string[];
+    subaccount_id?: number;
+    expires_at_ns?: string;
+    name?: string;
+}
+export interface Subaccount {
+    subaccount_id: number;
+    status: 'active' | 'restricted' | 'closed';
+    created_at_ns: string;
+    cross_margin_balance_quote_lots: string;
+    total_isolated_margin_quote_lots: string;
+    equity_quote_lots: string;
+    available_margin_quote_lots: string;
+    transferable_margin_quote_lots: string;
+    initial_margin_requirement_quote_lots: string;
+    maintenance_margin_requirement_quote_lots: string;
+    delegations: Delegation[];
+}
+export interface Balance {
+    token_id: string;
+    total_token_atoms: string;
+    locked_token_atoms: string;
+    deposited_token_atoms: string;
+    withdrawn_token_atoms: string;
+}
+export interface Position {
+    market_id: number;
+    side: 'long' | 'short';
+    size_base_lots: string;
+    entry_price_ticks: string;
+    liquidation_price_ticks?: string;
+    margin_mode: 'cross' | 'isolated';
+    leverage: number;
+    position_value_quote_lots: string;
+    unrealized_pnl_quote_lots: string;
+    realized_pnl_quote_lots: string;
+    roe_bps: number;
+    margin_used_token_atoms: string;
+    isolated_margin_quote_lots: string;
+    fees_quote_lots: string;
+    /** Funding since opening including accrual; positive means paid. */
+    funding_paid_quote_lots: string;
+}
+export interface Order {
+    timestamp_ns: string;
+    sequence: string;
+    market_type: MarketType;
+    market_id: number;
+    order_id: string;
+    client_order_id: string;
+    side: 'bid' | 'ask';
+    price_ticks: string;
+    original_size_base_lots: string;
+    remaining_size_base_lots: string;
+    order_type: string;
+    time_in_force: string;
+    reduce_only?: boolean;
+    tick_offset?: string;
+    trigger_price_ticks?: string;
+    max_price_ticks?: string;
+    status: string;
+}
+export interface Fill {
+    /** Append-only row id (`"<tx_number>-<ordinal>"`) on websocket account rows; absent on REST rows. */
+    id?: string;
+    timestamp_ns: string;
+    sequence: string;
+    market_type: MarketType;
+    market_id: number;
+    order_id: string;
+    client_order_id: string;
+    role: 'maker' | 'taker';
+    side: 'bid' | 'ask';
+    price_ticks: string;
+    size_base_lots: string;
+    quote_notional_lots: string;
+    fee_quote_lots: string;
+    position_size_before_base_lots?: string;
+    position_size_after_base_lots?: string;
+    /** PnL closed by this fill before fees; zero for opening and spot fills. */
+    realized_pnl_quote_lots: string;
+    crossed?: boolean;
+    margin_bucket?: 'cross' | 'isolated';
+    liquidation_id?: string;
+    liquidation_method?: string;
+}
+export interface Transaction {
+    hash: string;
+    signer?: string;
+    method: string;
+    status: 'success' | 'failed';
+    /**
+     * Rollup block that included this transaction. Absent while the
+     * transaction is only soft-confirmed by the sequencer: the gateway omits
+     * the field until the block is indexed, then serves it as a string u64.
+     */
+    rollup_height?: string;
+    sequence: string;
+    timestamp_ns: string;
+    error?: string;
+    call?: Record<string, unknown>;
+}
+export interface FundingRate {
+    timestamp_ns: string;
+    sequence: string;
+    market_id: number;
+    funding_rate_100th_bps: number;
+    long_cumulative_funding_quote_lots: string;
+    short_cumulative_funding_quote_lots: string;
+}
+export interface FundingPayment {
+    /** Append-only row id (`"<tx_number>-<ordinal>"`) on websocket account rows; absent on REST rows. */
+    id?: string;
+    timestamp_ns: string;
+    sequence: string;
+    bucket: 'cross' | 'isolated';
+    market_id: number;
+    side: 'long' | 'short';
+    position_size_base_lots: string;
+    payment_quote_lots: string;
+    funding_index: string;
+}
+export interface BlpInfo {
+    total_shares: string;
+    protocol_fee_100th_bps: number;
+}
+/** Best bid and offer; a side is `null` when that side of the book is empty. */
+export interface Bbo {
+    bid: PriceLevel | null;
+    ask: PriceLevel | null;
+}
+/** A trade on the `trades/...` channel: the stream omits `sequence` and `quote_notional_lots`. */
+export interface WsTrade {
+    timestamp_ns: string;
+    price_ticks: string;
+    size_base_lots: string;
+    taker_is_bid: boolean;
+}
+/** The `orderbook` object of an update: the full book on the snapshot, changed levels afterwards (size `0` removes a level). */
+export interface BookLevels {
+    bids: PriceLevel[];
+    asks: PriceLevel[];
+}
+export interface Leverage {
+    market_id: number;
+    leverage: number;
+}
+export interface AccountCatalogEntry {
+    subaccount_id: number;
+    status: 'active' | 'restricted' | 'closed';
+    created_at_ns: string;
+}
+/** Snapshot of the `accounts/{address}` channel. */
+export interface AccountCatalog {
+    subaccounts: AccountCatalogEntry[];
+    delegations: Delegation[];
+}
+/** Snapshot of the `account/{address}/{subaccount_id}` channel; later frames are `operations` deltas. */
+export interface AccountSnapshot {
+    account: Subaccount;
+    delegations: Delegation[];
+    balances: Balance[];
+    positions: Position[];
+    leverages: Leverage[];
+    orders: Order[];
+    fills: Fill[];
+    funding_payments: FundingPayment[];
+}
+/**
+ * Kind of a collection delta: `reset` replaces a collection with `rows`,
+ * `insert` appends `row` to an append-only collection, `upsert` replaces the
+ * row with the same key or adds it, `delete` removes the row whose key fields
+ * `row` carries.
+ */
+export type OperationKind = 'reset' | 'insert' | 'upsert' | 'delete';
+/** One collection mutation from an account-channel `operations` array. */
+export interface CollectionOperation {
+    collection: string;
+    op: OperationKind | (string & {});
+    /** The complete row for `insert` / `upsert`; only the key fields for `delete`. */
+    row?: Record<string, unknown>;
+    /** The full collection for `reset`. */
+    rows?: Record<string, unknown>[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Exact wire models for Blink API v1. Large integers are decimal strings. */
+export {};

package/dist/ws-transport.d.ts

@@ -0,0 +1,50 @@
+import type { HelloFrame, WsMessage } from './ws.js';
+/** The websocket protocol version accepted by the shared transport. */
+export declare const WS_PROTOCOL_VERSION = 1;
+export interface WebSocketLike {
+    readyState: number;
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code?: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((error: unknown) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    ping?: () => void;
+}
+export interface TransportOptions {
+    socketFactory?: (url: string) => WebSocketLike;
+    repeat?: typeof setInterval;
+    cancelRepeat?: typeof clearInterval;
+    now?: () => number;
+    keepaliveIntervalMs?: number;
+    onMessage: (message: WsMessage) => void;
+    onClose?: (event: {
+        code?: number;
+        reason?: string;
+    }) => void;
+    onError?: (error: unknown) => void;
+    onDiagnostic?: (code: string, message: string, detail?: unknown) => void;
+    onProtocolError?: (error: Error) => void;
+}
+/** Shared physical connection, hello validation and heartbeat for both SDK clients. */
+export declare class WsTransport {
+    private readonly options;
+    private readonly socket;
+    private readonly readyPromise;
+    private helloFrame?;
+    private keepalive?;
+    private closed;
+    constructor(url: string, options: TransportOptions);
+    ready(): Promise<HelloFrame>;
+    hello(): HelloFrame | undefined;
+    canSend(): boolean;
+    send(command: object): void;
+    close(code?: number, reason?: string): void;
+    private startKeepalive;
+    private stopKeepalive;
+}

package/dist/ws-transport.js

@@ -0,0 +1,118 @@
+/** The websocket protocol version accepted by the shared transport. */
+export const WS_PROTOCOL_VERSION = 1;
+/** Shared physical connection, hello validation and heartbeat for both SDK clients. */
+export class WsTransport {
+    options;
+    socket;
+    readyPromise;
+    helloFrame;
+    keepalive;
+    closed = false;
+    constructor(url, options) {
+        this.options = options;
+        this.socket = options.socketFactory?.(url) ?? new WebSocket(url);
+        this.readyPromise = new Promise((resolve, reject) => {
+            this.socket.onopen = () => { };
+            this.socket.onerror = (error) => {
+                if (this.closed)
+                    return;
+                options.onError?.(error);
+                reject(error);
+                this.close();
+            };
+            this.socket.onmessage = ({ data }) => {
+                if (this.closed)
+                    return;
+                let frame;
+                try {
+                    if (typeof data !== 'string')
+                        throw new Error('Ignoring non-text frame');
+                    frame = JSON.parse(data);
+                    if (typeof frame !== 'object' ||
+                        frame === null ||
+                        Array.isArray(frame) ||
+                        !('type' in frame) ||
+                        typeof frame.type !== 'string') {
+                        throw new Error('Frame has no type');
+                    }
+                }
+                catch (error) {
+                    options.onDiagnostic?.('MALFORMED_FRAME', 'Ignoring malformed WebSocket frame', error);
+                    return;
+                }
+                const message = frame;
+                if (!this.helloFrame) {
+                    if (message.type !== 'hello' || message.protocol_version !== WS_PROTOCOL_VERSION) {
+                        const error = new Error(`server does not speak Blink WebSocket protocol v${WS_PROTOCOL_VERSION} (got ${message.type === 'hello' ? `v${message.protocol_version}` : message.type})`);
+                        reject(error);
+                        options.onProtocolError?.(error);
+                        this.close(1002, 'unsupported WebSocket protocol');
+                        return;
+                    }
+                    if (!Number.isFinite(message.keepalive_timeout_ms) || message.keepalive_timeout_ms <= 0) {
+                        options.onDiagnostic?.('INVALID_HELLO', 'hello did not advertise a keepalive timeout; using the default', message);
+                        message.keepalive_timeout_ms = 120_000;
+                    }
+                    this.helloFrame = message;
+                    this.startKeepalive(options.keepaliveIntervalMs ?? Math.max(1_000, Math.floor(message.keepalive_timeout_ms / 2)));
+                    resolve(message);
+                }
+                else if (!['update', 'error', 'unsubscribed', 'pong'].includes(message.type)) {
+                    options.onDiagnostic?.('UNKNOWN_FRAME', 'Ignoring unknown frame', message);
+                    return;
+                }
+                if ((message.type === 'update' || message.type === 'unsubscribed') && typeof message.channel !== 'string') {
+                    options.onDiagnostic?.('MALFORMED_FRAME', 'Frame has no channel', message);
+                    return;
+                }
+                options.onMessage(message);
+            };
+            this.socket.onclose = (event) => {
+                this.closed = true;
+                this.stopKeepalive();
+                reject(new Error('connection closed before the protocol-v1 hello'));
+                options.onClose?.(event);
+            };
+        });
+        this.readyPromise.catch(() => { });
+    }
+    ready() {
+        return this.readyPromise;
+    }
+    hello() {
+        return this.helloFrame;
+    }
+    canSend() {
+        return !this.closed && !!this.helloFrame && this.socket.readyState === 1;
+    }
+    send(command) {
+        this.socket.send(JSON.stringify(command));
+    }
+    close(code, reason) {
+        this.closed = true;
+        this.stopKeepalive();
+        this.socket.close(code, reason);
+    }
+    startKeepalive(periodMs) {
+        this.keepalive = (this.options.repeat ?? setInterval)(() => {
+            if (!this.canSend())
+                return;
+            try {
+                if (this.socket.ping)
+                    this.socket.ping();
+                else
+                    this.send({ type: 'ping', timestamp_ns: (BigInt((this.options.now ?? Date.now)()) * 1000000n).toString() });
+            }
+            catch (error) {
+                this.options.onError?.(error);
+                this.close();
+            }
+        }, periodMs);
+        this.keepalive.unref?.();
+    }
+    stopKeepalive() {
+        if (this.keepalive !== undefined)
+            (this.options.cancelRepeat ?? clearInterval)(this.keepalive);
+        this.keepalive = undefined;
+    }
+}