@runesx/api-client 0.2.0 → 0.4.0

package/README.md

@@ -1,24 +1,25 @@
 # RunesX API Client
 
-A Node.js client for interacting with the RunesX platform API and WebSocket, enabling developers to build bots or scripts for real-time trading, liquidity management, and data monitoring.
+A Node.js client for interacting with the RunesX platform API and WebSocket, enabling developers to build bots or scripts for real-time trading, liquidity management, withdrawals, deposits, and data monitoring.
 
 ## Features
-- **WebSocket Integration**: Connect to the RunesX Socket.IO server to listen for real-time events like `pools_updated`, `coins_updated`, `wallets_updated`, `user_shares_updated`, and chat messages (`yard_message`).
-- **API Access**: Perform HTTP requests for wallet data, swaps, and liquidity operations.
-- **Store Management**: Manage coin, pool, wallet, and user share data with built-in buffering for WebSocket updates.
-- **Swap Estimation**: Estimate swap outcomes using DFS or BFS pathfinding algorithms.
-- **Liquidity Management**: Estimate, deposit, and withdraw liquidity for trading pairs.
-- **Monitoring**: Periodically monitor pool, wallet, and user share states.
+
+- **WebSocket Integration**: Real-time events for pools, coins, chains, wallets, user shares, operations, deposits, withdrawals, candlesticks, volume, and chat
+- **Full REST API**: Complete HTTP API coverage for all public and private endpoints
+- **Store Management**: Automatic real-time state management for pools, coins, chains, wallets, and user shares with buffering for out-of-order updates
+- **Swap Estimation**: Client-side swap estimation using DFS or BFS pathfinding algorithms
+- **Liquidity Management**: Estimate, deposit, and withdraw liquidity with RUNES compliance checking
+- **Withdrawal Flow**: Full multi-step withdrawal verification (PIN, email, 2FA)
+- **Price Utilities**: Calculate token prices in RUNES and USD
+- **Event System**: Register callbacks for any WebSocket event
 
 ## Installation
+
 ```bash
 npm install @runesx/api-client
 ```
 
-## Usage
-
-1. Initialize the Client
-Create and initialize the client with your API key and endpoint URLs. This connects to the WebSocket and fetches initial data for pools, coins, wallets, and user shares.
+## Quick Start
 
 ```javascript
 import { createRunesXClient } from '@runesx/api-client';
@@ -30,497 +31,681 @@ const client = createRunesXClient({
 });
 
 async function main() {
-  try {
-    const { pools, coins, wallets, userShares } = await client.initialize();
-    console.log('Initialized with:', {
-      poolCount: pools.length,
-      coinCount: coins.length,
-      walletCount: wallets.length,
-      userShareCount: userShares.length,
-    });
-  } catch (error) {
-    console.error('Initialization failed:', error.message);
-  }
+  const { pools, coins, chains, wallets, userShares } = await client.initialize();
+  console.log(`Connected: ${pools.length} pools, ${coins.length} coins, ${wallets.length} wallets`);
+
+  // Listen for real-time events
+  client.on('operationUpdate', (operation) => {
+    console.log('New operation:', operation);
+  });
+
+  // Get prices
+  const prices = await client.getPrices();
+  console.log('Prices:', prices);
 }
 
-main();
+main().catch(console.error);
+```
+
+## Configuration
+
+```javascript
+const client = createRunesXClient({
+  apiKey: 'your-api-key',           // Required. Your RunesX API key
+  apiUrl: 'https://www.runesx.xyz/api',  // Optional. Default: http://localhost:3010
+  socketUrl: 'https://www.runesx.xyz/api', // Optional. Default: http://localhost:3010
+});
 ```
 
-2. Accessing Store Data
-Retrieve data from the internal stores for pools, coins, wallets, and user shares.
+You can also set these via environment variables:
+- `API_KEY` - Your API key
+- `API_URL` - API base URL
+- `SOCKET_URL` - WebSocket URL
+
+## API Key Scopes
+
+When generating an API key, you can assign specific scopes:
+
+| Scope | Description |
+|-------|-------------|
+| `read` | Read-only access to user data (wallets, shares, operations, transactions) |
+| `swap` | Execute token swaps |
+| `liquidity_deposit` | Deposit liquidity to pools |
+| `liquidity_withdraw` | Withdraw liquidity from pools |
+| `wallet_withdraw` | Withdraw to external addresses |
+| `chat` | Access yard/chat features |
+
+---
+
+## Store Data (Real-time via WebSocket)
+
+After `initialize()`, the client maintains real-time stores updated via WebSocket. These are always up-to-date.
+
+### Pools
 
-### Get All Pools
 ```javascript
-const pools = client.getPools();
-console.log('Available pools:', pools.map(pool => ({
-  id: pool.id,
-  pair: `${pool.coinA.ticker}/${pool.coinB.ticker}`,
-  reserveA: pool.reserveA,
-  reserveB: pool.reserveB,
-})));
+const pools = client.getPools();           // All pools
+const pool = client.getPool(poolId);       // Pool by ID
 ```
 
-### Get a Specific Pool
+Pool object:
 ```javascript
-const pool = client.getPool(1);
-console.log('Pool 1:', pool ? {
-  pair: `${pool.coinA.ticker}/${pool.coinB.ticker}`,
-  reserveA: pool.reserveA,
-  reserveB: pool.reserveB,
-} : 'Pool not found');
+{
+  id, reserveA, reserveB, totalShares, activeLiquidityProviders,
+  runesCompliant, lpFeeRate, treasuryFeeRate,
+  coinA: { id, ticker, dp, projectName },
+  coinB: { id, ticker, dp, projectName },
+  liquidityShares: [...],
+  updatedAt
+}
 ```
 
-### Get All Coins
+### Coins
+
 ```javascript
-const coins = client.getCoins();
-console.log('Available coins:', coins.map(coin => ({
-  ticker: coin.ticker,
-  projectName: coin.projectName,
-  status: coin.status,
-})));
+const coins = client.getCoins();                // All coins
+const coin = client.getCoinByTicker('RUNES');    // Coin by ticker
 ```
 
-### Get a Coin by Ticker
+### Chains
+
 ```javascript
-const coin = client.getCoinByTicker('xRUNES');
-console.log('xRUNES coin:', coin ? {
-  ticker: coin.ticker,
-  dp: coin.dp,
-  projectName: coin.projectName,
-} : 'Coin not found');
+const chains = client.getChains();                   // All chains
+const chain = client.getChainByName('RuneBase');     // Chain by name
 ```
 
-### Get All Wallets
+### Wallets
+
 ```javascript
-const wallets = client.getWallets();
-console.log('Wallets:', wallets.map(wallet => ({
-  ticker: wallet.ticker,
-  available: wallet.available,
-  locked: wallet.locked,
-})));
+const wallets = client.getWallets();                  // All wallets
+const wallet = client.getWalletByTicker('RUNES');    // Wallet by ticker
+// wallet.available, wallet.locked
 ```
 
-### Get a Wallet by Ticker
+### User Shares
+
 ```javascript
-const wallet = client.getWalletByTicker('xRUNES');
-console.log('xRUNES wallet:', wallet ? {
-  ticker: wallet.ticker,
-  available: wallet.available,
-} : 'Wallet not found');
+const shares = client.getUserShares();                    // All shares
+const share = client.getUserShareByPoolId(poolId);       // Share by pool
+// share.shares, share.poolId
 ```
 
-### Get All User Shares
+---
+
+## REST API Methods
+
+### Public Endpoints (No Auth Required)
+
+#### System Status
+
 ```javascript
-const userShares = client.getUserShares();
-console.log('User shares:', userShares.map(share => ({
-  poolId: share.poolId,
-  shares: share.shares,
-})));
+const status = await client.getStatus();
+// { apiVersion, apiStatus, ratatoskrVersion, ratatoskrStatus }
 ```
 
-### Get User Shares by Pool ID
+#### Coins (via API)
+
 ```javascript
-const share = client.getUserShareByPoolId(1);
-console.log('Shares for pool 1:', share ? {
-  poolId: share.poolId,
-  shares: share.shares,
-} : 'No shares found');
+const coins = await client.getCoinsApi();      // All coins
+const coin = await client.getCoinApi('RUNES'); // Single coin with chain details
 ```
 
-3. Estimating and Executing a Swap
-Estimate and execute a swap between two tokens, such as 0.1 xRUNES to XLM, with slippage tolerance.
+#### Pools (via API)
 
 ```javascript
-import { BigNumber } from 'bignumber.js';
+const pools = await client.getPoolsApi();                      // All pools
+const pool = await client.getPoolByPair('RUNES', 'USDC');     // Specific pool
+const shares = await client.getPoolLiquidityShares(poolId);   // Pool's liquidity shares
+```
 
-async function executeSwap() {
-  try {
-    const inputCoin = client.getCoinByTicker('xRUNES');
-    const outputCoin = client.getCoinByTicker('XLM');
-    if (!inputCoin || !outputCoin) {
-      throw new Error('Required coins not found');
-    }
+#### Prices
 
-    const amountIn = '0.1'; // 0.1 xRUNES
-    const maxHops = 6;
-    const algorithm = 'dfs';
-    const slippageTolerance = '1'; // 1%
-
-    // Estimate swap
-    const swapEstimate = await client.estimateSwap(inputCoin, outputCoin, amountIn, maxHops, algorithm);
-    console.log('Swap estimate:', {
-      input: swapEstimate.input,
-      output: swapEstimate.output,
-      priceImpact: `${(swapEstimate.slippage.priceImpact * 100).toFixed(2)}%`,
-      path: swapEstimate.path,
-    });
-
-    // Calculate minimum output with slippage
-    const amountOutBN = new BigNumber(swapEstimate.output.amount);
-    const minAmountOut = amountOutBN
-      .times(new BigNumber(1).minus(new BigNumber(slippageTolerance).div(100)))
-      .toFixed(outputCoin.dp, BigNumber.ROUND_DOWN);
-
-    // Check wallet balance
-    const wallet = client.getWalletByTicker(inputCoin.ticker);
-    if (!wallet || new BigNumber(wallet.available).lt(amountIn)) {
-      throw new Error(`Insufficient balance for ${inputCoin.ticker}: ${wallet?.available || 0}`);
-    }
+```javascript
+const prices = await client.getPrices();
+// { prices: [{ ticker, projectName, dp, priceInRunes, priceInUSD }], runesPriceUSD, timestamp }
 
-    // Execute swap
-    const swap = await client.postSwap({
-      amountIn,
-      path: swapEstimate.path,
-      minAmountOut,
-    });
-    console.log('Swap executed:', swap.data);
-  } catch (error) {
-    console.error('Swap failed:', error.message);
-  }
-}
+const price = await client.getPrice('RUNES');
+// { ticker, projectName, dp, priceInRunes, priceInUSD, runesPriceUSD, timestamp }
+```
 
-executeSwap();
+#### Candlesticks
+
+```javascript
+const candles = await client.getCandlesticks(poolId, '1h', fromTimestamp, toTimestamp);
+// [{ time, open, high, low, close, volume }]
 ```
 
-4. Managing Liquidity
-Deposit and withdraw liquidity for a trading pair, such as RUNES/XLM.
+Valid timeframes: `1m`, `5m`, `15m`, `1h`, `4h`, `12h`, `1d`, `1w`, `1M`
 
+#### Volume
 
 ```javascript
-import { BigNumber } from 'bignumber.js';
+const total = await client.getVolumeTotal();
+const poolVol = await client.getVolumePool(poolId);
+```
 
-async function manageLiquidity() {
-  try {
-    const coinA = client.getCoinByTicker('RUNES');
-    const coinB = client.getCoinByTicker('XLM');
-    if (!coinA || !coinB) {
-      throw new Error('Required coins not found');
-    }
+#### Buckets
 
-    // Check RUNES compliance
-    const { isCompliant, warnings } = client.checkRunesLiquidityFrontend(coinA, coinB);
-    if (!isCompliant) {
-      console.error('Cannot deposit liquidity:', warnings);
-      return;
-    }
+```javascript
+const buckets = await client.getBucketsPools();
+```
 
-    // Estimate liquidity amounts
-    const amountA = '1'; // 1 RUNES
-    const estimate = await client.estimateLiquidityFrontend({
-      coinA,
-      coinB,
-      amountA,
-      amountB: null,
-      pools: client.getPools(),
-      coins: client.getCoins(),
-    });
-    console.log('Liquidity estimate:', {
-      amountA: estimate.amountA,
-      amountB: estimate.amountB,
-      pair: `${estimate.coinA.ticker}/${estimate.coinB.ticker}`,
-      isPoolEmpty: estimate.isPoolEmpty,
-      flipped: estimate.flipped,
-    });
-
-    // Validate wallet balances
-    const walletA = client.getWalletByTicker(coinA.ticker);
-    const walletB = client.getWalletByTicker(coinB.ticker);
-    if (!walletA || new BigNumber(walletA.available).lt(estimate.amountA)) {
-      throw new Error(`Insufficient balance for ${coinA.ticker}: ${walletA?.available || 0}`);
-    }
-    if (!walletB || new BigNumber(walletB.available).lt(estimate.amountB)) {
-      throw new Error(`Insufficient balance for ${coinB.ticker}: ${walletB?.available || 0}`);
-    }
+#### Operations
 
-    // Deposit liquidity
-    const depositParams = {
-      coinA: { ticker: estimate.coinA.ticker },
-      coinB: { ticker: estimate.coinB.ticker },
-      amountA: estimate.amountA,
-      amountB: estimate.amountB,
-    };
-    const depositResult = await client.depositLiquidity(depositParams);
-    console.log('Liquidity deposited:', {
-      pair: `${depositResult.coinA.ticker}/${depositResult.coinB.ticker}`,
-      amountA: depositResult.amountA,
-      amountB: depositResult.amountB,
-      shares: depositResult.shares,
-      uid: depositResult.uid,
-    });
-
-    // Wait for user shares update
-    await new Promise(resolve => setTimeout(resolve, 5000));
-
-    // Calculate and withdraw shares
-    const updatedUserShares = client.getUserShares();
-    const calculatedShares = client.calculateShareAmounts();
-    const share = calculatedShares.find(
-      s => s.coinA.ticker === depositParams.coinA.ticker && s.coinB.ticker === depositParams.coinB.ticker
-    );
-
-    if (!share) {
-      throw new Error('No shares found for the deposited pool');
-    }
+```javascript
+// Recent operations (public)
+const recent = await client.getRecentOperations({ operationType: 'swap', limit: 20 });
 
-    const sharesToWithdraw = new BigNumber(share.shares).div(2).integerValue(BigNumber.ROUND_DOWN).toString();
-    const withdrawResult = await client.withdrawLiquidity({
-      coinA: { ticker: share.coinA.ticker },
-      coinB: { ticker: share.coinB.ticker },
-      shares: sharesToWithdraw,
-    });
-    console.log('Liquidity withdrawn:', {
-      pair: `${withdrawResult.coinA.ticker}/${withdrawResult.coinB.ticker}`,
-      amountA: withdrawResult.amountA,
-      amountB: withdrawResult.amountB,
-      shares: withdrawResult.shares,
-      uid: withdrawResult.uid,
-    });
-  } catch (error) {
-    console.error('Liquidity operation failed:', error.message);
-  }
-}
+// Pool operations
+const poolOps = await client.getPoolOperations(poolId, { operationType: 'swap' });
+```
+
+Valid operation types: `swap`, `liquidityDeposit`, `liquidityWithdrawal`
 
-manageLiquidity();
+#### Yard Messages
+
+```javascript
+const messages = await client.getYardMessages({ limit: 50 });
+const older = await client.getYardMessages({ before: '2024-01-01T00:00:00Z', limit: 50 });
 ```
 
-5. Monitoring Pools, Wallets, and User Shares
-Set up periodic monitoring for pools, wallets, and user shares, and listen for WebSocket updates.
+### Private Endpoints (Auth Required)
+
+#### Wallets
 
-### Monitor a Specific Pool
 ```javascript
-client.monitorPool(1, 10000); // Monitor pool ID 1 every 10 seconds
+const wallets = await client.getWalletsApi();  // Scope: read
 ```
 
-### Monitor Wallets
+#### Swap (Scope: swap)
+
 ```javascript
-function monitorWallets(interval = 10000) {
-  setInterval(() => {
-    const wallets = client.getWallets();
-    console.log('Wallets:', wallets.length > 0
-      ? wallets.map(wallet => ({
-          ticker: wallet.ticker,
-          available: wallet.available,
-          locked: wallet.locked,
-          updatedAt: wallet.updatedAt,
-        }))
-      : 'No wallets available');
-  }, interval);
-}
+const result = await client.postSwap({
+  amountIn: '1.0',
+  path: [{ from: 'RUNES', to: 'USDC' }],
+  minAmountOut: '0.009',
+  idempotencyKey: 'optional-unique-key',  // Auto-generated if not provided
+});
+```
+
+#### Liquidity (Scope: liquidity_deposit / liquidity_withdraw)
 
-monitorWallets();
+```javascript
+// Deposit
+const deposit = await client.depositLiquidity({
+  tickerA: 'RUNES',
+  tickerB: 'USDC',
+  amountA: '100',
+  amountB: '1.5',
+  minShares: '1000',  // Optional slippage protection
+  idempotencyKey: 'optional-key',
+});
+
+// Withdraw
+const withdraw = await client.withdrawLiquidity({
+  tickerA: 'RUNES',
+  tickerB: 'USDC',
+  shares: '5000',
+  minAmountA: '90',   // Optional slippage protection
+  minAmountB: '1.3',  // Optional slippage protection
+  idempotencyKey: 'optional-key',
+});
+
+// Get user's liquidity shares via API
+const shares = await client.getLiquidityShares();
 ```
 
-### Monitor User Shares
+#### Deposits
+
 ```javascript
-function monitorUserShares(interval = 10000) {
-  setInterval(() => {
-    const userShares = client.getUserShares();
-    console.log('User shares:', userShares.length > 0
-      ? userShares.map(share => ({
-          poolId: share.poolId,
-          shares: share.shares,
-          updatedAt: share.updatedAt,
-        }))
-      : 'No user shares available');
-  }, interval);
-}
+// Get deposit address for a chain
+const { address, memo } = await client.getDepositAddress('RuneBase');
+
+// Get all deposit addresses
+const addresses = await client.getAllDepositAddresses();
+// [{ chainName, address, memo }]
+```
+
+#### Withdrawals (Scope: wallet_withdraw)
+
+The withdrawal process is multi-step:
+
+```javascript
+// 1. Initiate withdrawal
+const initResult = await client.initiateWithdraw({
+  ticker: 'RUNES',
+  chain: 'RuneBase',
+  address: 'RxYz...',
+  amount: '100',
+  memo: null,  // Optional, for chains that require it
+  idempotencyKey: 'optional-key',
+});
+const { pendingWithdrawalId } = initResult.data;
+
+// 2. Verify PIN (shown as image via socket event 'withdrawal_pin_generated')
+await client.verifyWithdrawPin({ pendingWithdrawalId, pinCode: '123456' });
+
+// 3. Send email PIN
+await client.sendWithdrawEmailPin({ pendingWithdrawalId });
+
+// 4. Verify email PIN
+await client.verifyWithdrawEmailPin({ pendingWithdrawalId, emailPinCode: '654321' });
+
+// 5. Verify 2FA (if enabled)
+await client.verifyWithdraw2FA({ pendingWithdrawalId, twoFactorToken: '123456' });
+
+// Check pending withdrawals
+const pending = await client.getPendingWithdrawals();
+
+// Cancel a pending withdrawal
+await client.cancelWithdrawal({ pendingWithdrawalId });
+```
 
-monitorUserShares();
+#### Transaction History (Scope: read)
+
+```javascript
+const history = await client.getTransactionHistory({
+  page: 1,
+  limit: 20,
+  type: 'deposit',    // Optional: 'deposit' or 'withdrawal'
+  status: 'confirmed', // Optional
+});
+// { success, data: { transactions: [...], total, page, pages } }
+```
+
+#### User Operations (Scope: read)
+
+```javascript
+const ops = await client.getUserOperations({
+  operationType: 'swap',  // Optional
+  poolId: '1',            // Optional
+  startTime: '2024-01-01T00:00:00Z', // Optional
+  endTime: '2024-12-31T23:59:59Z',   // Optional
+  page: 1,
+  limit: 50,
+});
+```
+
+#### Yard Moderation (Scope: chat)
+
+```javascript
+// Delete a message (via REST API)
+await client.deleteYardMessage(messageId);
+```
+
+---
+
+## WebSocket Events
+
+### Event Listener System
+
+Use `client.on()` and `client.off()` to register callbacks for any WebSocket event:
+
+```javascript
+// Register a callback
+const handler = (data) => console.log('Pool update:', data);
+client.on('pools_updated', handler);
+
+// Remove a specific callback
+client.off('pools_updated', handler);
+
+// Remove all callbacks for an event
+client.off('pools_updated');
+```
+
+### Available Events
+
+#### Public Events (received after joining public room)
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `pools_updated` | `{ pools, isInitial }` | Pool data updated |
+| `coins_updated` | `{ coins, isInitial }` | Coin data updated |
+| `chains_updated` | `{ chains, isInitial }` | Chain data updated |
+| `buckets_updated` | `{ type, buckets }` | Pool bucket data |
+| `operations_updated` | `[operations]` | Initial recent operations |
+| `recent_yard_messages` | `{ messages, lastReadAt }` | Initial chat messages |
+| `status_updated` | `{ apiVersion, apiStatus, ratatoskrVersion, ratatoskrStatus }` | System status |
+| `volumeUpdate` | `{ type, poolId, timestamp, volume }` | Volume update |
+| `operationUpdate` | `operation` | New operation executed |
+| `yard_message` | `{ id, text, userId, username, role, timestamp }` | New chat message |
+| `message_deleted` | `{ messageId }` | Chat message deleted |
+| `candlestick_updated` | `data` | Candlestick update (requires joining candlestick room) |
+
+#### Private Events (received after joining private room)
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `wallets_updated` | `{ wallets, isInitial }` | Wallet balances updated |
+| `user_shares_updated` | `{ userShares, isInitial }` | Liquidity shares updated |
+| `deposit_address_generated` | `{ requestId, chainName, address, memo }` | Deposit address ready |
+| `deposit_processed` | `{ amount, coin, chain, confirmations, status, credited }` | Deposit confirmation update |
+| `withdrawal_initiated` | `data` | Withdrawal process started |
+| `withdrawal_pin_generated` | `{ pinImage, ticker, amount, pendingWithdrawalId, expiresAt, dp, fee, memoRequired }` | PIN image ready |
+| `withdrawal_updated` | `{ pendingWithdrawalId, expiresAt, stage }` | Withdrawal stage changed |
+| `withdrawal_queued` | `{ pendingWithdrawalId, ticker }` | Withdrawal queued for processing |
+| `withdrawal_processed` | `{ amount, coin, chain, confirmations, status, credited }` | Withdrawal confirmation update |
+| `withdrawal_canceled` | `{ ticker, amount }` | Withdrawal canceled |
+| `withdrawal_expired` | `{ pendingWithdrawalId, ticker, amount }` | Withdrawal expired |
+| `banned` | `{ reason, bannedUntil }` | User banned from yard chat |
+| `yard_read_marked` | `{ lastReadAt }` | Yard marked as read |
+| `session_expired` | `{ message }` | Session expired, reconnect needed |
+
+#### Connection Events
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `connect` | `null` | Connected to server |
+| `disconnect` | `reason` | Disconnected from server |
+| `connect_error` | `error` | Connection error |
+| `reconnect_attempt` | `attempt` | Reconnection attempt number |
+| `reconnect` | `null` | Successfully reconnected |
+| `error` | `error` | Socket error |
+
+### Socket Convenience Methods
+
+#### Candlestick Subscriptions
+
+```javascript
+// Subscribe to candlestick updates for a pool
+client.joinCandlesticks(poolId, '1h');
+
+client.on('candlestick_updated', (data) => {
+  console.log('Candlestick:', data);
+});
+
+// Unsubscribe
+client.leaveCandlesticks(poolId, '1h');
+```
+
+#### Chat (The Yard)
+
+```javascript
+// Send a message (Scope: chat)
+client.sendYardMessage('Hello from my bot!');
+
+// Listen for messages
+client.on('yard_message', (msg) => {
+  console.log(`[${msg.username}]: ${msg.text}`);
+});
+
+// Delete a message (moderator/admin only)
+client.deleteMessage(messageId);
+
+// Mark yard as read
+client.markYardRead();
 ```
 
-### Listen for WebSocket Updates
+### Raw Socket Access
+
+For advanced use cases, access the underlying Socket.IO instance:
+
 ```javascript
 const socket = client.getSocket();
+socket.emit('custom_event', data);
+```
+
+---
 
-socket.on('pools_updated', ({ isInitial }) => {
-  if (isInitial) {
-    const pools = client.getPools();
-    console.log('Initial pools:', pools.map(pool => ({
-      id: pool.id,
-      pair: `${pool.coinA.ticker}/${pool.coinB.ticker}`,
-      reserveA: pool.reserveA,
-      reserveB: pool.reserveB,
-      totalShares: pool.totalShares,
-    })));
-  }
+## Client-Side Utilities
+
+### Swap Estimation
+
+Estimate swap outcomes locally without making API calls:
+
+```javascript
+const inputCoin = client.getCoinByTicker('RUNES');
+const outputCoin = client.getCoinByTicker('USDC');
+
+const estimate = await client.estimateSwap(inputCoin, outputCoin, '100', 6, 'dfs');
+console.log({
+  outputAmount: estimate.output.amount,
+  priceImpact: `${estimate.slippage.priceImpact.toFixed(2)}%`,
+  path: estimate.path,
+  inputPriceUSD: estimate.input.priceUSD,
+  outputPriceUSD: estimate.output.priceUSD,
 });
+```
 
-socket.on('coins_updated', ({ isInitial }) => {
-  if (isInitial) {
-    const coins = client.getCoins();
-    console.log('Initial coins:', coins.map(coin => ({
-      ticker: coin.ticker,
-      projectName: coin.projectName,
-      status: coin.status,
-    })));
-  }
+### Liquidity Estimation
+
+```javascript
+const coinA = client.getCoinByTicker('RUNES');
+const coinB = client.getCoinByTicker('USDC');
+
+// Estimate how much coinB is needed for a given coinA amount
+const estimate = client.estimateLiquidityFrontend({
+  coinA, coinB,
+  amountA: '100',
+  amountB: null,
+  pools: client.getPools(),
+  coins: client.getCoins(),
 });
+console.log(`Need ${estimate.amountB} ${estimate.coinB.ticker} for ${estimate.amountA} ${estimate.coinA.ticker}`);
+```
 
-socket.on('wallets_updated', ({ isInitial }) => {
-  if (isInitial) {
-    const wallets = client.getWallets();
-    console.log('Initial wallets:', wallets.map(wallet => ({
-      ticker: wallet.ticker,
-      available: wallet.available,
-      locked: wallet.locked,
-    })));
-  }
+### Deposit Share Estimation
+
+```javascript
+const pool = client.getPool(poolId);
+const shareEstimate = client.estimateDepositShares({
+  pool,
+  amountA: '100',
+  amountB: '1.5',
+  slippagePercent: 2,
 });
+console.log(`Estimated shares: ${shareEstimate.estimatedShares}, min: ${shareEstimate.minShares}`);
+```
+
+### RUNES Compliance Check
+
+```javascript
+const { isCompliant, warnings } = client.checkRunesLiquidityFrontend(coinA, coinB);
+if (!isCompliant) {
+  console.warn('Pool not RUNES-compliant:', warnings);
+}
+```
+
+### Share Amount Calculation
 
-socket.on('user_shares_updated', ({ isInitial }) => {
-  if (isInitial) {
-    const userShares = client.getUserShares();
-    console.log('Initial user shares:', userShares.map(share => ({
-      poolId: share.poolId,
-      shares: share.shares,
-    })));
-  }
+```javascript
+const shareAmounts = client.calculateShareAmounts();
+shareAmounts.forEach(share => {
+  console.log(`${share.pair}: ${share.amountA} / ${share.amountB} (${share.shares} shares)`);
 });
 ```
 
-6. Cleaning Up
-Disconnect the WebSocket when done to free resources.
+### Price Utilities
 
 ```javascript
-client.disconnect();
+const runesPrice = client.utils.getRunesPriceUSD();
+const tokenPrice = client.utils.getTokenPriceUSD('USDC');
+const priceInRunes = client.utils.getTokenPriceInRunes('USDC');
+const usdValue = client.utils.calculateUSDValue('100', 'RUNES', 2);
+
+// Get prices for multiple tokens
+const prices = client.utils.getPrices(['RUNES', 'USDC', 'XLM']);
 ```
 
-7. Handling Process Termination
-Gracefully handle process termination to ensure cleanup.
+---
+
+## Complete Example: Trading Bot
 
 ```javascript
+import { createRunesXClient } from '@runesx/api-client';
+import { BigNumber } from 'bignumber.js';
+
+const client = createRunesXClient({
+  apiKey: process.env.API_KEY,
+  apiUrl: 'https://www.runesx.xyz/api',
+  socketUrl: 'https://www.runesx.xyz/api',
+});
+
+async function main() {
+  await client.initialize();
+  console.log('Bot started');
+
+  // Monitor for new operations
+  client.on('operationUpdate', (op) => {
+    if (op.operationType === 'swap') {
+      console.log(`Swap: ${op.amountIn} ${op.inputCoin?.ticker} -> ${op.amountOut} ${op.outputCoin?.ticker}`);
+    }
+  });
+
+  // Monitor wallet changes
+  client.on('wallets_updated', ({ isInitial }) => {
+    if (!isInitial) {
+      const wallets = client.getWallets();
+      wallets.forEach(w => {
+        console.log(`${w.ticker}: ${w.available} available, ${w.locked} locked`);
+      });
+    }
+  });
+
+  // Monitor deposit confirmations
+  client.on('deposit_processed', (data) => {
+    if (data.status === 'confirmed' && data.credited) {
+      console.log(`Deposit confirmed: ${data.amount} ${data.coin.ticker}`);
+    }
+  });
+
+  // Example: execute a swap when price is favorable
+  const checkAndSwap = async () => {
+    const inputCoin = client.getCoinByTicker('RUNES');
+    const outputCoin = client.getCoinByTicker('USDC');
+    if (!inputCoin || !outputCoin) { return; }
+
+    const estimate = await client.estimateSwap(inputCoin, outputCoin, '10');
+    const priceImpact = estimate.slippage.priceImpact;
+
+    if (priceImpact < 1) { // Less than 1% price impact
+      const minOut = new BigNumber(estimate.output.amount)
+        .times(0.99)
+        .toFixed(outputCoin.dp, BigNumber.ROUND_DOWN);
+
+      const result = await client.postSwap({
+        amountIn: '10',
+        path: estimate.path,
+        minAmountOut: minOut,
+      });
+      console.log('Swap result:', result);
+    }
+  };
+
+  setInterval(checkAndSwap, 60000);
+}
+
+main().catch(console.error);
+
 process.on('SIGINT', () => {
-  console.log('Shutting down...');
   client.disconnect();
   process.exit(0);
 });
 ```
 
+---
 
 ## API Reference
 
-### `createRunesXClient(options)`
-Creates a client instance.
-- **Parameters**:
-  - `options.apiKey` (string): RunesX API key.
-  - `options.apiUrl` (string, optional): API endpoint (default: `http://localhost:3010`).
-  - `options.socketUrl` (string, optional): WebSocket endpoint (default: `http://localhost:3010`).
-- **Returns**: Object with client methods.
-
-### `initialize()`
-Initializes the client, connecting to the WebSocket and fetching initial data.
-- **Returns**: Promise resolving to `{ pools, coins, wallets, userShares }`.
-
-### `getSocket()`
-Returns the Socket.IO instance.
-- **Returns**: Socket.IO client instance.
-
-### `getPools()`
-Returns all liquidity pools.
-- **Returns**: Array of pool objects.
-
-### `getPool(poolId)`
-Returns a specific pool by ID.
-- **Parameters**:
-  - `poolId` (number): Pool ID.
-- **Returns**: Pool object or undefined.
-
-### `getCoins()`
-Returns all coins.
-- **Returns**: Array of coin objects.
-
-### `getCoinByTicker(ticker)`
-Returns a coin by its ticker.
-- **Parameters**:
-  - `ticker` (string): Coin ticker (e.g., `xRUNES`).
-- **Returns**: Coin object or undefined.
-
-### `getWallets()`
-Returns all wallets.
-- **Returns**: Array of wallet objects.
-
-### `getWalletByTicker(ticker)`
-Returns a wallet by coin ticker.
-- **Parameters**:
-  - `ticker` (string): Coin ticker.
-- **Returns**: Wallet object or undefined.
-
-### `getUserShares()`
-Returns all user shares.
-- **Returns**: Array of user share objects.
-
-### `getUserShareByPoolId(poolId)`
-Returns user shares for a specific pool.
-- **Parameters**:
-  - `poolId` (number): Pool ID.
-- **Returns**: User share object or undefined.
-
-### `postSwap(params)`
-Executes a swap.
-- **Parameters**:
-  - `params.amountIn` (string): Input amount.
-  - `params.path` (array): Array of `{ from, to }` objects defining the swap path.
-  - `params.minAmountOut` (string): Minimum output amount.
-- **Returns**: Promise resolving to swap response.
-
-### `depositLiquidity(params)`
-Deposits liquidity to a pool.
-- **Parameters**:
-  - `params.coinA` (object): `{ ticker }` of first coin.
-  - `params.coinB` (object): `{ ticker }` of second coin.
-  - `params.amountA` (string): Amount of first coin.
-  - `params.amountB` (string): Amount of second coin.
-- **Returns**: Promise resolving to deposit response.
-
-### `withdrawLiquidity(params)`
-Withdraws liquidity from a pool.
-- **Parameters**:
-  - `params.coinA` (object): `{ ticker }` of first coin.
-  - `params.coinB` (object): `{ ticker }` of second coin.
-  - `params.shares` (string): Number of shares to withdraw.
-- **Returns**: Promise resolving to withdrawal response.
-
-### `getWalletsApi()`
-Fetches wallet data via the API.
-- **Returns**: Promise resolving to wallet data.
-
-### `estimateSwap(inputCoin, outputCoin, amountIn, maxHops, algorithm)`
-Estimates a swap outcome.
-- **Parameters**:
-  - `inputCoin` (object): Input coin object.
-  - `outputCoin` (object): Output coin object.
-  - `amountIn` (string): Input amount.
-  - `maxHops` (number, optional): Maximum hops (default: 6).
-  - `algorithm` (string, optional): Pathfinding algorithm (`dfs` or `bfs`, default: `dfs`).
-- **Returns**: Promise resolving to swap estimate.
-
-### `estimateLiquidityFrontend(params)`
-Estimates liquidity amounts for a pool.
-- **Parameters**:
-  - `params.coinA` (object): First coin.
-  - `params.coinB` (object): Second coin.
-  - `params.amountA` (string, optional): Amount of first coin.
-  - `params.amountB` (string, optional): Amount of second coin.
-  - `params.pools` (array): Array of pools.
-  - `params.coins` (array): Array of coins.
-- **Returns**: Liquidity estimate object.
-
-### `checkRunesLiquidityFrontend(coinA, coinB)`
-Checks RUNES compliance for a trading pair.
-- **Parameters**:
-  - `coinA` (object): First coin.
-  - `coinB` (object): Second coin.
-- **Returns**: `{ isCompliant, warnings }`.
-
-### `calculateShareAmounts()`
-Calculates amounts for user shares.
-- **Returns**: Array of share objects with calculated amounts.
-
-### `monitorPool(poolId, interval)`
-Monitors a pool periodically.
-- **Parameters**:
-  - `poolId` (number): Pool ID.
-  - `interval` (number, optional): Interval in milliseconds (default: 10000).
-
-### `disconnect()`
-Disconnects the WebSocket.
+### Client Creation & Lifecycle
+
+| Method | Description |
+|--------|-------------|
+| `createRunesXClient(options)` | Create a client instance |
+| `initialize()` | Connect WebSocket, wait for initial data. Returns `{ pools, coins, chains, wallets, userShares }` |
+| `disconnect()` | Disconnect WebSocket |
+| `getSocket()` | Get raw Socket.IO instance |
+
+### Store Accessors (Real-time Data)
+
+| Method | Returns |
+|--------|---------|
+| `getPools()` | All pools array |
+| `getPool(poolId)` | Pool by ID |
+| `getCoins()` | All coins array |
+| `getCoinByTicker(ticker)` | Coin by ticker |
+| `getChains()` | All chains array |
+| `getChainByName(name)` | Chain by name |
+| `getWallets()` | All wallets array |
+| `getWalletByTicker(ticker)` | Wallet by ticker |
+| `getUserShares()` | All user shares array |
+| `getUserShareByPoolId(poolId)` | User share by pool ID |
+
+### Event System
+
+| Method | Description |
+|--------|-------------|
+| `on(event, callback)` | Register event callback |
+| `off(event, callback?)` | Remove callback (or all for event) |
+
+### Socket Emit Methods
+
+| Method | Description |
+|--------|-------------|
+| `joinCandlesticks(poolId, timeframe)` | Subscribe to candlestick updates |
+| `leaveCandlesticks(poolId, timeframe)` | Unsubscribe from candlestick updates |
+| `sendYardMessage(text)` | Send a chat message (scope: chat) |
+| `deleteMessage(messageId)` | Delete a chat message (mod/admin) |
+| `markYardRead()` | Mark yard as read |
+
+### Public REST API
+
+| Method | Description |
+|--------|-------------|
+| `getStatus()` | System status |
+| `getCoinsApi()` | All coins via API |
+| `getCoinApi(ticker)` | Single coin via API |
+| `getPoolsApi()` | All pools via API |
+| `getPoolByPair(tickerA, tickerB)` | Pool by ticker pair |
+| `getPoolLiquidityShares(poolId)` | Pool liquidity shares |
+| `getPrices()` | All token prices |
+| `getPrice(ticker)` | Single token price |
+| `getCandlesticks(poolId, timeframe, from, to)` | OHLCV candlestick data |
+| `getVolumeTotal()` | Total platform volume |
+| `getVolumePool(poolId)` | Pool volume |
+| `getBucketsPools()` | Pool bucket data |
+| `getRecentOperations({ operationType?, limit? })` | Recent operations |
+| `getPoolOperations(poolId, { operationType?, limit? })` | Pool operations |
+| `getYardMessages({ before?, limit? })` | Chat messages |
+
+### Private REST API
+
+| Method | Scope | Description |
+|--------|-------|-------------|
+| `getWalletsApi()` | read | Wallet balances |
+| `getLiquidityShares()` | read | User's liquidity shares |
+| `postSwap({ amountIn, path, minAmountOut, idempotencyKey? })` | swap | Execute swap |
+| `depositLiquidity({ tickerA, tickerB, amountA, amountB, minShares?, idempotencyKey? })` | liquidity_deposit | Deposit liquidity |
+| `withdrawLiquidity({ tickerA, tickerB, shares, minAmountA?, minAmountB?, idempotencyKey? })` | liquidity_withdraw | Withdraw liquidity |
+| `getDepositAddress(chainName)` | read | Get deposit address |
+| `getAllDepositAddresses()` | read | Get all deposit addresses |
+| `initiateWithdraw({ ticker, chain, address, amount, memo?, idempotencyKey? })` | wallet_withdraw | Start withdrawal |
+| `verifyWithdrawPin({ pendingWithdrawalId, pinCode })` | wallet_withdraw | Verify PIN |
+| `sendWithdrawEmailPin({ pendingWithdrawalId })` | wallet_withdraw | Send email PIN |
+| `verifyWithdrawEmailPin({ pendingWithdrawalId, emailPinCode })` | wallet_withdraw | Verify email PIN |
+| `verifyWithdraw2FA({ pendingWithdrawalId, twoFactorToken })` | wallet_withdraw | Verify 2FA |
+| `getPendingWithdrawals()` | wallet_withdraw | Get pending withdrawals |
+| `cancelWithdrawal({ pendingWithdrawalId })` | wallet_withdraw | Cancel withdrawal |
+| `getTransactionHistory({ page?, limit?, type?, status? })` | read | Transaction history |
+| `getUserOperations({ operationType?, poolId?, startTime?, endTime?, page?, limit? })` | read | User operations |
+| `deleteYardMessage(messageId)` | chat | Delete chat message |
+
+### Client-Side Utilities
+
+| Method | Description |
+|--------|-------------|
+| `estimateSwap(inputCoin, outputCoin, amountIn, maxHops?, algorithm?)` | Estimate swap output locally |
+| `estimateLiquidityFrontend({ coinA, coinB, amountA, amountB, pools, coins })` | Estimate liquidity amounts |
+| `estimateDepositShares({ pool, amountA, amountB, slippagePercent? })` | Estimate deposit shares |
+| `checkRunesLiquidityFrontend(coinA, coinB)` | Check RUNES compliance |
+| `calculateShareAmounts()` | Calculate share token amounts |
+| `monitorPool(poolId, interval?)` | Log pool state periodically |
+| `utils.getRunesPriceUSD()` | RUNES price in USD |
+| `utils.getTokenPriceInRunes(ticker)` | Token price in RUNES |
+| `utils.getTokenPriceUSD(ticker)` | Token price in USD |
+| `utils.getPrices(tickers)` | Multiple token prices |
+| `utils.calculateUSDValue(amount, ticker, decimals?)` | USD value of token amount |
+
+## License
+
+MIT