@runesx/api-client 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runesx/api-client",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "A Node.js client for interacting with the RunesX platform API and WebSocket",
   "main": "src/index.mjs",
   "type": "module",
@@ -13,23 +13,23 @@
     "test": "jest"
   },
   "dependencies": {
-    "axios": "^1.13.5",
-    "bignumber.js": "^9.1.2",
+    "axios": "^1.13.6",
+    "bignumber.js": "^10.0.2",
     "socket.io-client": "^4.8.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.11.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/npm": "^13.1.4",
+    "@semantic-release/npm": "^13.1.5",
     "dotenv": "^17.3.1",
     "eslint": "^9.11.1",
     "eslint-plugin-import": "^2.30.0",
     "eslint-plugin-n": "^17.24.0",
     "eslint-plugin-promise": "^7.1.0",
-    "globals": "^17.3.0",
-    "jest": "^30.2.0",
-    "nodemon": "^3.1.11",
+    "globals": "^17.4.0",
+    "jest": "^30.3.0",
+    "nodemon": "^3.1.14",
     "semantic-release": "^25.0.3"
   },
   "files": [

package/src/api.mjs

@@ -341,6 +341,73 @@ export function createApi(config) {
     }
   }
 
+  // ---- Orders endpoints ----
+
+  async function placeOrder({ pair, side, price, quantity, timeInForce, inverted, idempotencyKey }) {
+    try {
+      const key = idempotencyKey || randomUUID();
+      const body = { pair, side, price, quantity, timeInForce };
+      if (inverted !== undefined && inverted !== null) {
+        body.inverted = inverted;
+      }
+      const response = await api.post('/orders', body, {
+        headers: { 'x-idempotency-key': key },
+      });
+      return response.data;
+    } catch (error) {
+      throw new Error(error.response?.data?.error || 'Failed to place order');
+    }
+  }
+
+  async function cancelOrder(orderId, { idempotencyKey } = {}) {
+    try {
+      const headers = {};
+      if (idempotencyKey) {
+        headers['x-idempotency-key'] = idempotencyKey;
+      }
+      const response = await api.delete(`/orders/${encodeURIComponent(orderId)}`, { headers });
+      return response.data;
+    } catch (error) {
+      throw new Error(error.response?.data?.error || 'Failed to cancel order');
+    }
+  }
+
+  async function getOrders({ pair, status, limit, offset } = {}) {
+    try {
+      const params = {};
+      if (pair) { params.pair = pair; }
+      if (status) { params.status = status; }
+      if (limit) { params.limit = limit; }
+      if (offset !== undefined && offset !== null) { params.offset = offset; }
+      const response = await api.get('/orders', { params });
+      return response.data;
+    } catch (error) {
+      throw new Error(error.response?.data?.error || 'Failed to fetch orders');
+    }
+  }
+
+  async function getOrderBookApi(pair, { levels } = {}) {
+    try {
+      const params = {};
+      if (levels) { params.levels = levels; }
+      const response = await api.get(`/orders/book/${encodeURIComponent(pair)}`, { params });
+      return response.data;
+    } catch (error) {
+      throw new Error(error.response?.data?.error || 'Failed to fetch order book');
+    }
+  }
+
+  async function getTrades(pair, { limit } = {}) {
+    try {
+      const params = {};
+      if (limit) { params.limit = limit; }
+      const response = await api.get(`/orders/trades/${encodeURIComponent(pair)}`, { params });
+      return response.data;
+    } catch (error) {
+      throw new Error(error.response?.data?.error || 'Failed to fetch trades');
+    }
+  }
+
   async function deleteYardMessage(messageId) {
     try {
       const response = await api.delete(`/yard/messages/${encodeURIComponent(messageId)}`);
@@ -385,5 +452,11 @@ export function createApi(config) {
     getTransactionHistory,
     getUserOperations,
     deleteYardMessage,
+    // Orders
+    placeOrder,
+    cancelOrder,
+    getOrders,
+    getOrderBookApi,
+    getTrades,
   };
 }

package/src/index.mjs

@@ -7,6 +7,9 @@ import { getCoins, getCoinByTicker } from './store/coinStore.mjs';
 import { getChains, getChainByName } from './store/chainStore.mjs';
 import { getWallets as getWalletsStore, getWalletByTicker } from './store/walletStore.mjs';
 import { getUserShares, getUserShareByPoolId } from './store/userSharesStore.mjs';
+import { getAllOrderBooks, getOrderBook, getOrderBookPairs, getUserOrders } from './store/orderbookStore.mjs';
+import { getMarkets, getMarketByCoinKey, getMarketByCoins } from './store/marketStore.mjs';
+import { getClobFees } from './store/exchangeConfigStore.mjs';
 import { waitForStores } from './waitForStores.mjs';
 import { estimateLiquidityFrontend, checkRunesLiquidityFrontend, calculateShareAmounts, estimateDepositShares } from './utils/liquidityUtils.mjs';
 import { estimateSwap } from './utils/swapUtils.mjs';
@@ -23,9 +26,9 @@ export function createRunesXClient(options = {}) {
       throw new Error('API_KEY is required');
     }
     socketHandler = setupSocket(config);
-    const { pools, coins, chains, wallets, userShares } = await waitForStores(socketHandler.socket);
+    const { pools, coins, chains, wallets, userShares, orderbooks } = await waitForStores(socketHandler.socket);
     initialized = true;
-    return { pools, coins, chains, wallets, userShares };
+    return { pools, coins, chains, wallets, userShares, orderbooks };
   }
 
   function ensureInitialized() {
@@ -54,6 +57,12 @@ export function createRunesXClient(options = {}) {
     getWalletByTicker,
     getUserShares,
     getUserShareByPoolId,
+    getAllOrderBooks,
+    getOrderBook,
+    getOrderBookPairs,
+    getUserOrders,
+    getMarkets,
+    getMarketByCoins,
 
     // ---- Event callbacks ----
     on: (event, callback) => {
@@ -133,13 +142,20 @@ export function createRunesXClient(options = {}) {
     getVolumePool: api.getVolumePool,
     getBucketsPools: api.getBucketsPools,
 
+    // ---- Orders API (auth required for place/cancel/getOrders, public for book/trades) ----
+    placeOrder: api.placeOrder,
+    cancelOrder: api.cancelOrder,
+    getOrders: api.getOrders,
+    getOrderBookApi: api.getOrderBookApi,
+    getTrades: api.getTrades,
+
     // ---- Yard (chat) API ----
     getYardMessages: api.getYardMessages,
     deleteYardMessage: api.deleteYardMessage,
 
     // ---- Client-side estimation utilities ----
     estimateSwap: (inputCoin, outputCoin, amountIn, maxHops = 6, algorithm = 'dfs') =>
-      estimateSwap(inputCoin, outputCoin, amountIn, getPools(), getCoins(), maxHops, algorithm),
+      estimateSwap(inputCoin, outputCoin, amountIn, getPools(), getCoins(), maxHops, algorithm, getAllOrderBooks(), getUserOrders(), getClobFees(), getMarketByCoinKey()),
     estimateLiquidityFrontend,
     estimateDepositShares: ({ pool, amountA, amountB, slippagePercent } = {}) =>
       estimateDepositShares({ pool, amountA, amountB, slippagePercent }),

package/src/socket.mjs

@@ -6,6 +6,9 @@ import { setInitialCoins, updateCoin, resetCoins } from './store/coinStore.mjs';
 import { setInitialChains, updateChain, resetChains } from './store/chainStore.mjs';
 import { setInitialWallets, updateWallet, resetWallets } from './store/walletStore.mjs';
 import { setInitialUserShares, updateUserShare, resetUserShares } from './store/userSharesStore.mjs';
+import { setInitialOrderBooks, updateOrderBook, resetOrderBooks, setUserOrders, updateUserOrder } from './store/orderbookStore.mjs';
+import { setInitialMarkets, addOrUpdateMarket, resetMarkets } from './store/marketStore.mjs';
+import { setExchangeConfig } from './store/exchangeConfigStore.mjs';
 
 export function setupSocket(config) {
   const socket = io(config.socketUrl, {
@@ -53,6 +56,8 @@ export function setupSocket(config) {
       resetChains();
       resetWallets();
       resetUserShares();
+      resetOrderBooks();
+      resetMarkets();
     }
     emit('connect_error', err);
   });
@@ -65,6 +70,7 @@ export function setupSocket(config) {
     resetChains();
     resetWallets();
     resetUserShares();
+    resetMarkets();
     emit('disconnect', reason);
   });
 
@@ -86,6 +92,7 @@ export function setupSocket(config) {
       resetChains();
       resetWallets();
       resetUserShares();
+      resetOrderBooks();
     }
     emit('reconnect_error', err);
   });
@@ -97,6 +104,26 @@ export function setupSocket(config) {
 
   // ---- Public room events ----
 
+  socket.on('exchange_config', (config) => {
+    setExchangeConfig(config);
+    emit('exchange_config', config);
+  });
+
+  socket.on('markets_initial', (data) => {
+    setInitialMarkets(data);
+    emit('markets_initial', data);
+  });
+
+  socket.on('market_created', (data) => {
+    addOrUpdateMarket(data);
+    emit('market_created', data);
+  });
+
+  socket.on('market_updated', (data) => {
+    addOrUpdateMarket(data);
+    emit('market_updated', data);
+  });
+
   socket.on('pools_updated', ({ pools, isInitial }) => {
     if (isInitial) {
       setInitialPools(pools);
@@ -140,6 +167,32 @@ export function setupSocket(config) {
     emit('status_updated', data);
   });
 
+  socket.on('orderbooks_initial', ({ books, isInitial }) => {
+    if (isInitial) {
+      setInitialOrderBooks(books);
+    }
+    emit('orderbooks_initial', { books, isInitial });
+  });
+
+  socket.on('orderbook_updated', ({ pair, bids, asks }) => {
+    updateOrderBook(pair, bids, asks);
+    emit('orderbook_updated', { pair, bids, asks });
+  });
+
+  socket.on('user_orders_initial', (orders) => {
+    setUserOrders(orders);
+    emit('user_orders_initial', orders);
+  });
+
+  socket.on('order_updated', (data) => {
+    updateUserOrder(data);
+    emit('order_updated', data);
+  });
+
+  socket.on('clob_trade', (trade) => {
+    emit('clob_trade', trade);
+  });
+
   socket.on('volumeUpdate', (data) => {
     emit('volumeUpdate', data);
   });

package/src/store/coinStore.mjs

@@ -1,4 +1,4 @@
-import { BigNumber } from 'bignumber.js';
+import { SafeBigNumber as BigNumber } from '../utils/safeBigNumber.mjs';
 
 const coinStore = {
   coins: new Map(), // Store coin data by coin ID

package/src/store/exchangeConfigStore.mjs

@@ -0,0 +1,48 @@
+// src/store/exchangeConfigStore.mjs
+// Exchange configuration received from the backend via socket.
+// Keeps fee rates, depth limits, etc. in sync without hardcoding.
+
+const exchangeConfigStore = {
+  clobFees: {
+    takerFeeRate: '0.002', // sensible default until backend config arrives
+    makerFeeRate: '0.001',
+    maxFillBatch: 50,
+    maxFillTotal: 500,
+  },
+};
+
+const setExchangeConfig = (config) => {
+  const { clobFees } = config;
+  if (clobFees) {
+    if (clobFees.takerFeeRate !== null && clobFees.takerFeeRate !== undefined) {
+      exchangeConfigStore.clobFees.takerFeeRate = clobFees.takerFeeRate;
+    }
+    if (clobFees.makerFeeRate !== null && clobFees.makerFeeRate !== undefined) {
+      exchangeConfigStore.clobFees.makerFeeRate = clobFees.makerFeeRate;
+    }
+    if (clobFees.maxFillBatch !== null && clobFees.maxFillBatch !== undefined) {
+      exchangeConfigStore.clobFees.maxFillBatch = clobFees.maxFillBatch;
+    }
+    if (clobFees.maxFillTotal !== null && clobFees.maxFillTotal !== undefined) {
+      exchangeConfigStore.clobFees.maxFillTotal = clobFees.maxFillTotal;
+    }
+  }
+};
+
+const getClobFees = () => exchangeConfigStore.clobFees;
+
+const resetExchangeConfig = () => {
+  exchangeConfigStore.clobFees = {
+    takerFeeRate: '0.002',
+    makerFeeRate: '0.001',
+    maxFillBatch: 50,
+    maxFillTotal: 500,
+  };
+};
+
+export {
+  exchangeConfigStore,
+  setExchangeConfig,
+  getClobFees,
+  resetExchangeConfig,
+};

package/src/store/marketStore.mjs

@@ -0,0 +1,57 @@
+// src/store/marketStore.mjs
+// Stores admin-defined markets received from the backend via socket.
+// Markets define the canonical pair direction (e.g., "RUNES-DOG" not "DOG-RUNES").
+
+let markets = [];
+let byCoinKey = {};
+
+function buildCoinKey(coinIdA, coinIdB) {
+  return coinIdA < coinIdB ? `${coinIdA}|${coinIdB}` : `${coinIdB}|${coinIdA}`;
+}
+
+function rebuildLookup() {
+  const lookup = {};
+  for (const m of markets) {
+    const key = buildCoinKey(m.baseCoinId, m.quoteCoinId);
+    lookup[key] = m;
+  }
+  byCoinKey = lookup;
+}
+
+export function setInitialMarkets(list) {
+  markets = list || [];
+  rebuildLookup();
+}
+
+export function addOrUpdateMarket(market) {
+  const idx = markets.findIndex((m) => m.id === market.id);
+  if (idx >= 0) {
+    markets[idx] = { ...markets[idx], ...market };
+  } else {
+    markets.push(market);
+  }
+  rebuildLookup();
+}
+
+export function getMarkets() {
+  return markets;
+}
+
+export function getMarketByCoinKey() {
+  return byCoinKey;
+}
+
+/**
+ * Look up a market by two coin IDs (order-independent).
+ * @param {string} coinIdA
+ * @param {string} coinIdB
+ * @returns {Object|undefined}
+ */
+export function getMarketByCoins(coinIdA, coinIdB) {
+  return byCoinKey[buildCoinKey(coinIdA, coinIdB)];
+}
+
+export function resetMarkets() {
+  markets = [];
+  byCoinKey = {};
+}

package/src/store/orderbookStore.mjs

@@ -0,0 +1,99 @@
+const orderbookStore = {
+  books: new Map(), // pair -> { bids: [[price, qty], ...], asks: [[price, qty], ...] }
+  isInitialReceived: false,
+  pendingUpdates: [],
+  userOrders: [], // User's open CLOB orders (across all pairs)
+};
+
+// Initialize all order books with initial data
+const setInitialOrderBooks = (books) => {
+  orderbookStore.books.clear();
+  for (const [pair, depth] of Object.entries(books)) {
+    orderbookStore.books.set(pair, {
+      bids: depth.bids || [],
+      asks: depth.asks || [],
+    });
+  }
+  orderbookStore.isInitialReceived = true;
+
+  // Process buffered updates
+  if (orderbookStore.pendingUpdates.length > 0) {
+    orderbookStore.pendingUpdates.forEach(({ pair, bids, asks }) => {
+      updateOrderBook(pair, bids, asks);
+    });
+    orderbookStore.pendingUpdates = [];
+  }
+};
+
+// Update a single order book
+const updateOrderBook = (pair, bids, asks) => {
+  if (!orderbookStore.isInitialReceived) {
+    orderbookStore.pendingUpdates.push({ pair, bids, asks });
+    return;
+  }
+  orderbookStore.books.set(pair, {
+    bids: bids || [],
+    asks: asks || [],
+  });
+};
+
+// Get all order books as a plain object { [pair]: { bids, asks } }
+const getAllOrderBooks = () => {
+  const result = {};
+  for (const [pair, depth] of orderbookStore.books) {
+    result[pair] = depth;
+  }
+  return result;
+};
+
+// Get a specific order book by pair
+const getOrderBook = (pair) => {
+  return orderbookStore.books.get(pair) || { bids: [], asks: [] };
+};
+
+// Get all pairs with active order books
+const getOrderBookPairs = () => {
+  return [...orderbookStore.books.keys()];
+};
+
+// Set user's open orders (received on connect)
+const setUserOrders = (orders) => {
+  orderbookStore.userOrders = orders || [];
+};
+
+// Update a single user order (from order_updated event)
+const updateUserOrder = (data) => {
+  if (data.refresh) {return;} // caller should refetch
+  const order = data.order;
+  if (!order) {return;}
+  const idx = orderbookStore.userOrders.findIndex((o) => o.id === order.id);
+  if (idx >= 0) {
+    orderbookStore.userOrders[idx] = { ...orderbookStore.userOrders[idx], ...order };
+  } else {
+    orderbookStore.userOrders.unshift(order);
+  }
+};
+
+// Get user's open orders
+const getUserOrders = () => orderbookStore.userOrders;
+
+// Reset store on disconnect or error
+const resetOrderBooks = () => {
+  orderbookStore.books.clear();
+  orderbookStore.isInitialReceived = false;
+  orderbookStore.pendingUpdates = [];
+  orderbookStore.userOrders = [];
+};
+
+export {
+  orderbookStore,
+  setInitialOrderBooks,
+  updateOrderBook,
+  getAllOrderBooks,
+  getOrderBook,
+  getOrderBookPairs,
+  setUserOrders,
+  updateUserOrder,
+  getUserOrders,
+  resetOrderBooks,
+};

package/src/store/poolStore.mjs

@@ -1,4 +1,4 @@
-import { BigNumber } from 'bignumber.js';
+import { SafeBigNumber as BigNumber } from '../utils/safeBigNumber.mjs';
 
 const poolStore = {
   pools: new Map(), // Store pool data by pool ID

package/src/store/userSharesStore.mjs

@@ -1,5 +1,5 @@
 // src/store/userSharesStore.mjs
-import { BigNumber } from 'bignumber.js';
+import { SafeBigNumber as BigNumber } from '../utils/safeBigNumber.mjs';
 
 const userSharesStore = {
   userShares: new Map(),

package/src/store/walletStore.mjs

@@ -1,4 +1,4 @@
-import { BigNumber } from 'bignumber.js';
+import { SafeBigNumber as BigNumber } from '../utils/safeBigNumber.mjs';
 
 const walletStore = {
   wallets: new Map(), // Store wallet data by ticker

package/src/utils/liquidityUtils.mjs

@@ -1,6 +1,5 @@
 // src/utils/liquidityUtils.mjs
-import { BigNumber } from 'bignumber.js';
-
+import { SafeBigNumber as BigNumber } from './safeBigNumber.mjs';
 import { getRunesPriceUSD, getTokenPriceInRunes } from './swapUtils.mjs';
 
 export function normalizeTokenPairFrontend(coinA, coinB, pools) {
@@ -111,7 +110,7 @@ export function getPoolRatioFrontend(pool) {
   return reserveADecimal.div(reserveBDecimal);
 }
 
-export function estimateLiquidityFrontend({ coinA, coinB, amountA, amountB, pools, coins }) {
+export function estimateLiquidityFrontend({ coinA, coinB, amountA, amountB, pools }) {
   if ((amountA === null && amountB === null) || (amountA !== null && amountB !== null)) {
     throw new Error('Provide either amountA or amountB, but not both or neither');
   }

package/src/utils/priceUtils.mjs

@@ -1,9 +1,10 @@
 // src/utils/priceUtils.mjs
-import { BigNumber } from 'bignumber.js';
 
 import { getPools } from '../store/poolStore.mjs';
 import { getCoinByTicker } from '../store/coinStore.mjs';
 
+import { SafeBigNumber as BigNumber } from './safeBigNumber.mjs';
+
 export function createPriceUtils() {
   const getRunesPriceUSD = () => {
     const pools = getPools();

package/src/utils/safeBigNumber.mjs

@@ -0,0 +1,11 @@
+// src/utils/safeBigNumber.mjs
+// Isolated BigNumber constructor aligned with the backend's SafeBigNumber
+// (runesx-api/src/utils/safeBigNumber.mjs). Uses the same DECIMAL_PLACES=40
+// and EXPONENTIAL_AT=[-100, 100] configuration to ensure estimation arithmetic
+// matches backend financial calculations.
+import BigNumber from 'bignumber.js';
+
+export const SafeBigNumber = BigNumber.clone({
+  DECIMAL_PLACES: 40,
+  EXPONENTIAL_AT: [-100, 100],
+});