@metaflux/fluxaction 0.1.3

package/examples/main.ts

@@ -0,0 +1,77 @@
+import 'dotenv/config'
+import { FluxAction } from '../src'
+import type { TrailingStopOrder, TakeProfitOrder, StopLossOrder } from '../src/core/logicalOrders'
+
+async function main() {
+  const flux = new FluxAction({
+    gate: {
+      apiKey: process.env.GATE_API_KEY || '',
+      secret: process.env.GATE_SECRET_KEY || '',
+    },
+    risk: { pollIntervalMs: 500 },
+  })
+
+  await flux.init()
+
+  const symbol = 'BTC/USDT'
+  const exchangeId = 'gate-spot'
+  const quoteCost = 10
+
+  console.log('[test] openSpotPosition', { exchangeId, symbol, quoteCost })
+  const { orderId, filledBase, avgPrice } = await flux.openSpotPosition({
+    exchangeId,
+    symbol,
+    quoteCost,
+  })
+  console.log('[test] opened', { orderId, filledBase, avgPrice })
+
+  const sellQty = filledBase * 0.9
+  const tpPrice = avgPrice * 1.04
+  const slPrice = avgPrice * 0.9 
+
+  const baseId = `${exchangeId}:${symbol}:${Date.now()}`
+
+  const tp: TakeProfitOrder = {
+    id: baseId + ':tp',
+    exchangeId,
+    symbol,
+    side: 'sell',
+    qty: sellQty,
+    kind: 'take-profit',
+    triggerPrice: tpPrice,
+  }
+
+  const ts: TrailingStopOrder = {
+    id: baseId + ':ts',
+    exchangeId,
+    symbol,
+    side: 'sell',
+    qty: sellQty,
+    kind: 'trailing-stop',
+    callbackRate: 0.04,
+    activationPrice: avgPrice,
+    highWatermark: avgPrice,
+  }
+
+  const sl: StopLossOrder = {
+    id: baseId + ':sl',
+    exchangeId,
+    symbol,
+    side: 'sell',
+    qty: sellQty,
+    kind: 'stop-loss',
+    triggerPrice: slPrice,
+  }
+
+  await flux.placeTakeProfit(tp)
+  await flux.placeTrailingStop(ts)
+  await flux.placeStopLoss(sl)
+
+  console.log('[test] TP, SL & trailing registered', { sellQty, tpPrice, slPrice })
+  console.log('[test] waiting RiskManager to act... (keep process running)')
+}
+
+main().catch((e) => {
+  console.error('[test] error', e)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@metaflux/fluxaction",
+  "version": "0.1.3",
+  "description": "Programmatic spot trading actions (TP/SL/trailing) for crypto exchanges",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "ts-node examples/main.ts"
+  },
+  "keywords": [
+    "trading-bot",
+    "crypto",
+    "ccxt",
+    "risk-management",
+    "take-profit",
+    "stop-loss",
+    "trailing-stop"
+  ],
+  "author": "wancareri",
+  "license": "MIT",
+  "dependencies": {
+    "ccxt": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.0"
+  }
+}

package/src/core/RiskManager.ts

@@ -0,0 +1,205 @@
+import type { ExchangeAdapter } from './exchange'
+import type {
+  LogicalOrder,
+  TakeProfitOrder,
+  StopLossOrder,
+  TrailingStopOrder,
+} from './logicalOrders'
+
+export interface RiskManagerConfig {
+  exchanges: Record<string, ExchangeAdapter>
+  pollIntervalMs?: number
+}
+
+export class RiskManager {
+  private cfg: RiskManagerConfig
+  private orders = new Map<string, LogicalOrder>()
+  private started = false
+
+  constructor(cfg: RiskManagerConfig) {
+    this.cfg = cfg
+  }
+
+  registerExchange(ex: ExchangeAdapter) {
+    this.cfg.exchanges[ex.id] = ex
+  }
+
+  async placeTakeProfit(o: TakeProfitOrder) {
+    this.orders.set(o.id, o)
+    const ex = this.cfg.exchanges[o.exchangeId]
+    if (!ex) throw new Error(`no exchange ${o.exchangeId}`)
+    if (ex.capabilities.spot.nativeTakeProfit) {
+      // TODO
+    } else {
+      this.startPolling()
+    }
+  }
+
+  async placeStopLoss(o: StopLossOrder) {
+    this.orders.set(o.id, o)
+    const ex = this.cfg.exchanges[o.exchangeId]
+    if (!ex) throw new Error(`no exchange ${o.exchangeId}`)
+    if (ex.capabilities.spot.nativeStopLoss) {
+      // TODO
+    } else {
+      this.startPolling()
+    }
+  }
+
+  async placeTrailingStop(o: TrailingStopOrder) {
+    this.orders.set(o.id, o)
+    const ex = this.cfg.exchanges[o.exchangeId]
+    if (!ex) throw new Error(`no exchange ${o.exchangeId}`)
+    if (ex.capabilities.spot.nativeTrailingStop) {
+      // TODO
+    } else {
+      this.startPolling()
+    }
+  }
+
+  async cancel(id: string) {
+    this.orders.delete(id)
+  }
+
+  getActiveOrders(): LogicalOrder[] {
+    return [...this.orders.values()]
+  }
+
+  private startPolling() {
+    if (this.started) return
+    this.started = true
+    const interval = this.cfg.pollIntervalMs ?? 3_000
+    setInterval(() => {
+      this.tick().catch((e) => {
+        console.error('[RiskManager] tick error', e)
+      })
+    }, interval)
+  }
+
+  private async tick() {
+    const grouped: Record<string, Record<string, LogicalOrder[]>> = {}
+    for (const o of this.orders.values()) {
+      if (!grouped[o.exchangeId]) grouped[o.exchangeId] = {}
+      if (!grouped[o.exchangeId][o.symbol]) grouped[o.exchangeId][o.symbol] = []
+      grouped[o.exchangeId][o.symbol].push(o)
+    }
+
+    for (const [exId, bySymbol] of Object.entries(grouped)) {
+      const ex = this.cfg.exchanges[exId]
+      if (!ex) continue
+      for (const [symbol, orders] of Object.entries(bySymbol)) {
+        await this.processForSymbol(ex, symbol, orders)
+      }
+    }
+  }
+
+  private async processForSymbol(
+    ex: ExchangeAdapter,
+    symbol: string,
+    orders: LogicalOrder[],
+  ) {
+    const ticker = await ex.fetchTicker(symbol)
+    const price = ticker.last
+    if (!price || price <= 0) return
+
+    for (const o of orders) {
+      if (o.kind === 'take-profit') {
+        const tp = o as TakeProfitOrder
+        if (o.side === 'sell' && price >= tp.triggerPrice) {
+          console.log('[RiskManager] TP condition hit', {
+            id: o.id,
+            price,
+            triggerPrice: tp.triggerPrice,
+          })
+          await this.executeAndClear(ex, o, price)
+        }
+      } else if (o.kind === 'stop-loss') {
+        const sl = o as StopLossOrder
+        if (o.side === 'sell' && price <= sl.triggerPrice) {
+          console.log('[RiskManager] SL condition hit', {
+            id: o.id,
+            price,
+            triggerPrice: sl.triggerPrice,
+          })
+          await this.executeAndClear(ex, o, price)
+        }
+      } else if (o.kind === 'trailing-stop') {
+        const ts = o as TrailingStopOrder
+        if (!ts.highWatermark || price > ts.highWatermark) {
+          ts.highWatermark = price
+          this.orders.set(o.id, ts)
+          continue
+        }
+        const drop = (ts.highWatermark - price) / ts.highWatermark
+        
+        if (drop >= ts.callbackRate) {
+          console.log('[RiskManager] TRAILING condition hit', {
+            id: o.id,
+            price,
+            highWatermark: ts.highWatermark,
+            drop,
+          })
+          await this.executeAndClear(ex, o, price)
+        }
+      }
+    }
+  }
+
+  private async executeAndClear(
+    ex: ExchangeAdapter,
+    o: LogicalOrder,
+    price: number,
+) {
+    console.log('[RiskManager] EXIT', {
+      exchangeId: ex.id,
+      symbol: o.symbol,
+      kind: o.kind,
+      side: o.side,
+      qty: o.qty,
+      price,
+    })
+
+    this.orders.delete(o.id)
+
+    if (o.side === 'sell') {
+        for (const [id, ord] of this.orders.entries()) {
+        if (ord.exchangeId === o.exchangeId && ord.symbol === o.symbol && ord.side === 'sell') {
+            this.orders.delete(id)
+        }
+        }
+    }
+
+    const bal = await ex.fetchBalance()
+    const base = o.symbol.split('/')[0]
+    const free = bal[base]?.free ?? 0
+    const rawQty = Math.min(o.qty, free * 0.995)
+
+    if (rawQty <= 0) {
+        console.warn('[RiskManager] skip exit: qty <= 0', { symbol: o.symbol, base, free, requested: o.qty })
+        return
+    }
+
+    if (o.side === 'sell') {
+        try {
+        await ex.marketSellSpot(o.symbol, rawQty)
+        } catch (e: any) {
+        const msg = String(e.message || '')
+        if (msg.includes('too small') && msg.includes('Your order size')) {
+            console.warn('[RiskManager] sell failed: below exchange min size', {
+            symbol: o.symbol,
+            base,
+            free,
+            requested: o.qty,
+            rawQty,
+            error: msg,
+            })
+            return
+        }
+        throw e
+        }
+    } else {
+        const quoteCost = price * rawQty
+        await ex.marketBuySpot(o.symbol, quoteCost)
+    }
+    }
+}

package/src/core/exchange.ts

@@ -0,0 +1,87 @@
+export type MarketType = 'spot' | 'futures'
+export type Side = 'buy' | 'sell'
+export type PositionSide = 'long' | 'short'
+
+export interface MarketInfo {
+  symbol: string
+  base: string
+  quote: string
+  type: MarketType
+  precisionAmount?: number
+  precisionPrice?: number
+  minCost?: number
+  minAmount?: number
+}
+
+export interface OrderInfo {
+  id: string
+  symbol: string
+  side: Side
+  type: 'market' | 'limit'
+  price?: number
+  amount: number
+  status: string
+  raw: any
+}
+
+export interface PositionInfo {
+  symbol: string
+  side: PositionSide
+  size: number
+  entryPrice: number
+  raw: any
+}
+
+export interface ExchangeCapabilities {
+  spot: {
+    nativeTakeProfit: boolean
+    nativeStopLoss: boolean
+    nativeTrailingStop: boolean
+  }
+  futures: {
+    nativeTakeProfit: boolean
+    nativeStopLoss: boolean
+    nativeTrailingStop: boolean
+  }
+}
+
+export interface ExchangeAdapter {
+  readonly id: string
+  readonly label: string
+  readonly capabilities: ExchangeCapabilities
+
+  loadMarkets(): Promise<void>
+
+  hasSpotMarket(symbol: string): boolean
+  hasFuturesMarket(symbol: string): boolean
+  getMarket(symbol: string): MarketInfo | undefined
+
+  fetchTicker(symbol: string): Promise<{ last: number }>
+  fetchBalance(): Promise<Record<string, { free: number; used: number; total: number }>>
+  fetchOpenOrders(symbol?: string): Promise<OrderInfo[]>
+  cancelOrder(symbol: string, orderId: string): Promise<void>
+
+  marketBuySpot(symbol: string, quoteCost: number): Promise<OrderInfo>
+  marketSellSpot(symbol: string, baseAmount: number): Promise<OrderInfo>
+  limitOrderSpot(
+    symbol: string,
+    side: Side,
+    baseAmount: number,
+    price: number,
+  ): Promise<OrderInfo>
+
+  openFutures(params: {
+    symbol: string
+    side: PositionSide
+    costUSDT: number
+    leverage?: number
+  }): Promise<OrderInfo>
+
+  closeFutures(params: {
+    symbol: string
+    side: PositionSide
+    costUSDT?: number
+  }): Promise<OrderInfo>
+
+  fetchPositions?(symbol?: string): Promise<PositionInfo[]>
+}

package/src/core/logicalOrders.ts

@@ -0,0 +1,31 @@
+export type LogicalOrderKind = 'take-profit' | 'stop-loss' | 'trailing-stop'
+
+export interface LogicalOrderBase {
+  id: string
+  exchangeId: string
+  symbol: string
+  side: 'buy' | 'sell'
+  qty: number
+}
+
+export interface TakeProfitOrder extends LogicalOrderBase {
+  kind: 'take-profit'
+  triggerPrice: number
+}
+
+export interface StopLossOrder extends LogicalOrderBase {
+  kind: 'stop-loss'
+  triggerPrice: number
+}
+
+export interface TrailingStopOrder extends LogicalOrderBase {
+  kind: 'trailing-stop'
+  callbackRate: number 
+  activationPrice?: number
+  highWatermark?: number
+}
+
+export type LogicalOrder =
+  | TakeProfitOrder
+  | StopLossOrder
+  | TrailingStopOrder

package/src/core/results.ts

@@ -0,0 +1,20 @@
+export interface SpotListingExecutionStep {
+  at: number
+  level: 'info' | 'warn' | 'error'
+  message: string
+  context?: any
+}
+
+export interface SpotListingExecutionLog {
+  exchangeId: string
+  symbol: string
+  steps: SpotListingExecutionStep[]
+  error?: string
+}
+
+export interface SpotListingResult {
+  ticker: string
+  normalizedSymbol: string
+  perExchangeBudget: number
+  executions: SpotListingExecutionLog[]
+}

package/src/exchanges/GateSpotAdapter.ts

@@ -0,0 +1,193 @@
+import ccxt, { type gateio as GateCcxt } from 'ccxt'
+import {
+  type ExchangeAdapter,
+  type ExchangeCapabilities,
+  type MarketInfo,
+  type OrderInfo,
+  type PositionInfo,
+} from '../core/exchange'
+
+export interface GateSpotAdapterConfig {
+  id: string
+  label?: string
+  apiKey: string
+  secret: string
+}
+
+export class GateSpotAdapter implements ExchangeAdapter {
+  readonly id: string
+  readonly label: string
+  readonly capabilities: ExchangeCapabilities
+  private ex: GateCcxt
+
+  constructor(cfg: GateSpotAdapterConfig) {
+    this.id = cfg.id
+    this.label = cfg.label ?? 'gate-spot'
+
+    this.ex = new ccxt.gateio({
+      apiKey: cfg.apiKey,
+      secret: cfg.secret,
+      enableRateLimit: true,
+      options: {
+        defaultType: 'spot',
+        createMarketBuyOrderRequiresPrice: false,
+      },
+    }) as GateCcxt
+
+    this.capabilities = {
+      spot: {
+        nativeTakeProfit: false,
+        nativeStopLoss: false,
+        nativeTrailingStop: false,
+      },
+      futures: {
+        nativeTakeProfit: false,
+        nativeStopLoss: false,
+        nativeTrailingStop: false,
+      },
+    }
+  }
+
+  async loadMarkets(): Promise<void> {
+    await this.ex.loadMarkets()
+  }
+
+  hasSpotMarket(symbol: string): boolean {
+    const m = this.ex.markets?.[symbol]
+    return !!m && m.type === 'spot'
+  }
+
+  hasFuturesMarket(): boolean {
+    return false
+  }
+
+  getMarket(symbol: string): MarketInfo | undefined {
+    const m = this.ex.markets?.[symbol]
+    if (!m) return undefined
+    return {
+      symbol: m.symbol,
+      base: m.base,
+      quote: m.quote,
+      type: m.type as any,
+      precisionAmount: m.precision?.amount,
+      precisionPrice: m.precision?.price,
+      minCost: m.limits?.cost?.min,
+      minAmount: m.limits?.amount?.min,
+    }
+  }
+
+  private roundAmount(symbol: string, amount: number): number {
+    const m = this.ex.markets?.[symbol]
+    if (!m) return amount
+    return Number(this.ex.amountToPrecision(symbol, amount))
+  }
+
+  private roundPrice(symbol: string, price: number): number {
+    const m = this.ex.markets?.[symbol]
+    if (!m) return price
+    return Number(this.ex.priceToPrecision(symbol, price))
+  }
+
+  private mapOrder(symbol: string, o: any): OrderInfo {
+    const price = o.price ?? o.average ?? o.avgPrice
+
+    let baseAmount: number
+    if (price && o.cost) {
+      baseAmount = o.cost / price
+    } else if (price && o.amount) {
+      baseAmount = o.amount / price
+    } else if (typeof o.amount === 'number' && o.amount > 0) {
+      baseAmount = o.amount
+    } else {
+      baseAmount = 0
+    }
+
+    return {
+      id: o.id,
+      symbol,
+      side: o.side,
+      type: o.type,
+      price,
+      amount: baseAmount,
+      status: o.status,
+      raw: o,
+    }
+  }
+
+  async fetchTicker(symbol: string): Promise<{ last: number }> {
+    const t = await this.ex.fetchTicker(symbol)
+    return { last: t.last ?? 0 }
+  }
+
+  async fetchBalance() {
+    const bal = await this.ex.fetchBalance()
+    return bal as any
+  }
+
+  async fetchOpenOrders(symbol?: string): Promise<OrderInfo[]> {
+    const orders = await this.ex.fetchOpenOrders(symbol)
+    return orders.map((o: any) => this.mapOrder(o.symbol, o))
+  }
+
+  async cancelOrder(symbol: string, orderId: string): Promise<void> {
+    await this.ex.cancelOrder(orderId, symbol)
+  }
+
+  async marketBuySpot(symbol: string, quoteCost: number): Promise<OrderInfo> {
+    const ticker = await this.fetchTicker(symbol)
+    if (!ticker.last || ticker.last <= 0) {
+      throw new Error(`gate-spot invalid price for ${symbol}: ${ticker.last}`)
+    }
+
+    const m = this.getMarket(symbol)
+    if (m?.minCost && quoteCost < m.minCost) {
+      throw new Error(
+        `gate-spot buy violates minCost: ${quoteCost} < ${m.minCost} ${m.quote}`,
+      )
+    }
+
+    const order = await this.ex.createMarketBuyOrderWithCost(symbol, quoteCost, {
+      createMarketBuyOrderRequiresPrice: false,
+    })
+    return this.mapOrder(symbol, order)
+  }
+
+  async marketSellSpot(symbol: string, baseAmount: number): Promise<OrderInfo> {
+    const amount = this.roundAmount(symbol, baseAmount)
+    if (!amount || amount <= 0) {
+      throw new Error(`gate-spot sell amount too small for ${symbol}: ${amount}`)
+    }
+
+    const order = await this.ex.createOrder(symbol, 'market', 'sell', amount)
+    return this.mapOrder(symbol, order)
+  }
+
+  async limitOrderSpot(
+    symbol: string,
+    side: 'buy' | 'sell',
+    baseAmount: number,
+    price: number,
+  ): Promise<OrderInfo> {
+    const amount = this.roundAmount(symbol, baseAmount)
+    const p = this.roundPrice(symbol, price)
+
+    if (!amount || amount <= 0) {
+      throw new Error(`gate-spot limit amount too small for ${symbol}: ${amount}`)
+    }
+
+    const order = await this.ex.createOrder(symbol, 'limit', side, amount, p)
+    return this.mapOrder(symbol, order)
+  }
+
+  async openFutures(): Promise<OrderInfo> {
+    throw new Error('gate-spot: futures not supported')
+  }
+
+  async closeFutures(): Promise<OrderInfo> {
+    throw new Error('gate-spot: futures not supported')
+  }
+
+  async fetchPositions(): Promise<PositionInfo[]> {
+    return []
+  }
+}