Cryptochanges

Small software layer to make it easier to access exchanges using your API keys.

Breaking changes in 2.x

• Removed exchanges: FastEx and Probit (factory, exports, and ExchangeId values no longer exist).
• Package rename: published as @quadrant-lls/cryptochanges (update import path / registry).
• Typed errors: exchange methods throw ExchangeError subclasses; legacy error.message format is preserved. Prefer instanceof OrderNotFound / AuthenticationError / etc. over string matching.
• fetchOrderByClientOrderId: native lookup on Binance, Bybit, OKX, MEXC, and WEEX; other exchanges scan open orders only (filled/canceled orders may not be returned).
• HTTP retry: enabled for all transport calls; POST retries require a client-order-id field in the payload.
• Test commands: npm test runs unit tests only (no API keys). Use npm run test:integration for live exchange suites.

clientOrderId

All spot order creation methods accept an optional clientOrderId?: string as the last argument:

• createLimitBuyOrder(pair, amount, price, clientOrderId?)
• createLimitSellOrder(pair, amount, price, clientOrderId?)
• createBatch(pair, orders) where each orders[i] may include clientOrderId?: string

If clientOrderId is provided, the library validates it per exchange and sends it to the corresponding native field. If it is omitted, the exchange module generates a client id for that specific request.

Recovery by client id

• New method: fetchOrderByClientOrderId(pair, clientOrderId).
• Default behaviour is “not supported”; each exchange overrides it where possible.
• Native lookup: Binance, Bybit, OKX, MEXC, WEEX query the exchange order API by client id, then fall back to open-orders scan.
• Open orders only: all other exchanges filter fetchOpenOrders; filled/canceled orders may not be returned.

Native client id fields (spot)

The following mapping is used when clientOrderId is provided:

• Binance / BingX / Bitrue / MEXC / WEEX: newClientOrderId
• Bybit: orderLinkId
• OKX: clOrdId
• Gate: text (must include t- prefix)
• Kucoin / Bitget: clientOid
• HTX: client-order-id
• LBank: custom_id
• XT: clientOrderId
• BloFin: client_order_id
• Coinstore: clOrdId

Typed errors

All exchange methods throw an ExchangeError (extends Error) and one of its subclasses:

• OrderNotFound
• InsufficientFunds
• InvalidOrder
• RateLimitExceeded
• AuthenticationError
• NetworkError
• ExchangeNotAvailable
• NotSupportedError

Backward compatibility:

• error.message keeps the legacy format: ExchangeId: <id>, msg: <native payload>
• Message-based consumer code will keep working.

Migration:

• Prefer err instanceof OrderNotFound / RateLimitExceeded / etc.

Transport retry (HTTP)

HTTP requests now use shared retry logic for transient failures:

• Retries 429 and 5xx plus common network errors
• Exponential backoff with jitter
• Retry-After header is honoured when present (capped to the configured max delay)

POST (order creation) is retried only when the outgoing request includes a client-order-id field, to keep retries idempotent.

WEEX WebSocket

WEEX spot now supports real-time feeds:

• initOrderBookWs(pair) (depth15 snapshots+delta)
• initTickerWs(pair) (24hr ticker; last price)
• getOrderBookWs(pair) → { bids, asks, updated }
• getLastPriceWs(pair) → last price number

Testing

Unit tests (no API keys):

npm test
# or
npm run test:unit

Integration tests hit real exchange APIs. Copy .env.example to .env and fill in credentials for exchanges you want to test:

cp .env.example .env
# edit .env — set {EXCHANGE}_API_KEY / _API_SECRET / _API_PASSWORD per exchange
npm run test:integration

Run everything (unit + integration):

npm run test:all

Suites without credentials for an exchange are skipped automatically.

• Read-only (default): SMOKE_WRITE=0 — orderbook, klines, balance, open orders, websocket.
• Write path: SMOKE_WRITE=1 — also creates far-from-market limit orders and cancels them (requires sufficient balance).

Single-exchange smoke script:

EXCHANGE=WEEX npm run smoke:spot
SMOKE_WRITE=1 EXCHANGE=WEEX npm run smoke:spot