@metaflux/fluxaction 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaflux/fluxaction",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Programmatic spot trading actions (TP/SL/trailing) for crypto exchanges",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "start": "ts-node examples/main.ts"
+    "test:spot": "ts-node scripts/spot.ts",
+    "test:futures": "ts-node scripts/futures.ts"
   },
   "keywords": [
     "trading-bot",
@@ -23,7 +24,8 @@
   "author": "wancareri",
   "license": "MIT",
   "dependencies": {
-    "ccxt": "^4.4.0"
+    "ccxt": "^4.4.0",
+    "dotenv": "^17.2.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/scripts/futures.ts

@@ -0,0 +1,80 @@
+try { require('dotenv').config() } catch {}
+
+import { FluxAction } from '../src'
+import type { TakeProfitOrder, StopLossOrder, TrailingStopOrder } from '../src/core/logicalOrders'
+
+async function main() {
+  const apiKey = process.env.GATE_API_KEY || ''
+  const secret = process.env.GATE_SECRET_KEY || ''
+  if (!apiKey || !secret) throw new Error('Missing GATE_API_KEY / GATE_SECRET_KEY')
+
+  const flux = new FluxAction({
+    gate: { apiKey, secret },
+    risk: { pollIntervalMs: 300 },
+  })
+
+  await flux.init()
+
+  const exchangeId = 'gate-futures'
+  const symbol = 'BTC/USDT:USDT'
+  const costUSDT = 15
+
+  const open = await flux.openFuturesPosition({
+    exchangeId,
+    symbol,
+    side: 'short',
+    costUSDT,
+    leverage: 3,
+    price: null, // market
+  })
+  console.log('[futures] opened', open)
+
+  const baseId = `${exchangeId}:${symbol}:${Date.now()}`
+
+  const tp: TakeProfitOrder = {
+    id: baseId + ':tp',
+    exchangeId,
+    market: 'futures',
+    symbol,
+    kind: 'take-profit',
+    triggerPrice: 10_000_000,
+    positionSide: 'long',
+    exitMode: 'all',
+  }
+
+  const sl: StopLossOrder = {
+    id: baseId + ':sl',
+    exchangeId,
+    market: 'futures',
+    symbol,
+    kind: 'stop-loss',
+    triggerPrice: 1,
+    positionSide: 'long',
+    exitMode: 'all',
+  }
+
+  const ts: TrailingStopOrder = {
+    id: baseId + ':ts',
+    exchangeId,
+    market: 'futures',
+    symbol,
+    kind: 'trailing-stop',
+    callbackRate: 0.03,
+    activationPrice: undefined,
+    highWatermark: undefined,
+    positionSide: 'long',
+    exitMode: 'all',
+  }
+
+  await flux.placeTakeProfit(tp)
+  await flux.placeStopLoss(sl)
+  await flux.placeTrailingStop(ts)
+
+  console.log('[futures] exits registered', flux.getActiveLogicalOrders().map((o) => o.id))
+  while (true) await new Promise((r) => setTimeout(r, 60_000))
+}
+
+main().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})

package/scripts/spot.ts

@@ -0,0 +1,84 @@
+try { require('dotenv').config() } catch {}
+
+import { FluxAction } from '../src'
+import type { TakeProfitOrder, StopLossOrder, TrailingStopOrder } from '../src/core/logicalOrders'
+
+async function main() {
+  const apiKey = process.env.GATE_API_KEY || ''
+  const secret = process.env.GATE_SECRET_KEY || ''
+  if (!apiKey || !secret) throw new Error('Missing GATE_API_KEY / GATE_SECRET_KEY')
+
+  const flux = new FluxAction({
+    gate: { apiKey, secret },
+    risk: { pollIntervalMs: 300 },
+  })
+
+  await flux.init()
+
+  const exchangeId = 'gate-spot'
+  const symbol = 'DOGE/USDT'
+  const quoteCost = 15
+
+  const open = await flux.openSpotPosition({ exchangeId, symbol, quoteCost })
+  console.log('[spot] opened', open)
+
+  const { baseQty } = await flux.quoteToBaseQty({ exchangeId, symbol, quoteCost: 3, price: open.avgPrice || undefined })
+  const limitOrder = await flux.placeSpotLimit({
+    exchangeId,
+    symbol,
+    side: 'sell',
+    baseQty,
+    price: (open.avgPrice || 0) * 1.1,
+  })
+  console.log('[spot] limit sell placed', limitOrder)
+
+  const qty = open.filledBase * 0.7
+  const baseId = `${exchangeId}:${symbol}:${Date.now()}`
+
+  const tp: TakeProfitOrder = {
+    id: baseId + ':tp',
+    exchangeId,
+    market: 'spot',
+    symbol,
+    side: 'sell',
+    qty,
+    kind: 'take-profit',
+    triggerPrice: open.avgPrice * 1.02,
+  }
+
+  const sl: StopLossOrder = {
+    id: baseId + ':sl',
+    exchangeId,
+    market: 'spot',
+    symbol,
+    side: 'sell',
+    qty,
+    kind: 'stop-loss',
+    triggerPrice: open.avgPrice * 0.95,
+  }
+
+  const ts: TrailingStopOrder = {
+    id: baseId + ':ts',
+    exchangeId,
+    market: 'spot',
+    symbol,
+    side: 'sell',
+    qty,
+    kind: 'trailing-stop',
+    callbackRate: 0.02,
+    activationPrice: open.avgPrice,
+    highWatermark: open.avgPrice,
+  }
+
+  await flux.placeTakeProfit(tp)
+  await flux.placeStopLoss(sl)
+  await flux.placeTrailingStop(ts)
+
+  console.log('[spot] exits registered', flux.getActiveLogicalOrders().map((o) => o.id))
+  while (true) await new Promise((r) => setTimeout(r, 60_000))
+}
+
+main().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})

package/src/FluxAction.ts

@@ -0,0 +1,150 @@
+import type { ExchangeAdapter, PositionSide } from './core/exchange'
+import { ExchangeRegistry } from './services/ExchangeRegistry'
+import { InMemoryOrderStore } from './risk/OrderStore'
+import { RiskEngine } from './risk/RiskEngine'
+import { RiskScheduler } from './risk/RiskScheduler'
+import type {
+  TakeProfitOrder,
+  StopLossOrder,
+  TrailingStopOrder,
+  LogicalOrder,
+} from './core/logicalOrders'
+import { GateSpotAdapter, GateFuturesAdapter } from './exchanges/gate'
+import { GateClient } from './clients/GateClient'
+
+export interface FluxActionConfig {
+  gate?: { apiKey: string; secret: string }
+  gateFutures?: { enabled?: boolean; settle?: 'usdt' | 'btc'; defaultLeverage?: number }
+  risk?: { pollIntervalMs?: number; autoStart?: boolean }
+}
+
+export class FluxAction {
+  private registry = new ExchangeRegistry()
+  private riskEngine: RiskEngine
+  private riskScheduler: RiskScheduler
+
+  readonly gate: GateClient
+
+  constructor(cfg: FluxActionConfig) {
+    if (cfg.gate) {
+      this.registry.register(new GateSpotAdapter({
+        id: 'gate-spot',
+        apiKey: cfg.gate.apiKey,
+        secret: cfg.gate.secret,
+      }))
+
+      const wantFutures = cfg.gateFutures?.enabled ?? true
+      if (wantFutures) {
+        this.registry.register(new GateFuturesAdapter({
+          id: 'gate-futures',
+          apiKey: cfg.gate.apiKey,
+          secret: cfg.gate.secret,
+          settle: cfg.gateFutures?.settle ?? 'usdt',
+          defaultLeverage: cfg.gateFutures?.defaultLeverage,
+        }))
+      }
+    }
+
+    const store = new InMemoryOrderStore()
+    this.riskEngine = new RiskEngine(store, this.registry.asRecord())
+    this.riskScheduler = new RiskScheduler(this.riskEngine, cfg.risk?.pollIntervalMs ?? 3000)
+    if (cfg.risk?.autoStart) this.riskScheduler.start()
+
+    this.gate = new GateClient(this, { spot: 'gate-spot', futures: 'gate-futures' })
+  }
+
+  async init(): Promise<void> {
+    await Promise.all(this.registry.list().map((a) => a.loadMarkets()))
+  }
+
+  getExchange(id: string): ExchangeAdapter | undefined {
+    return this.registry.get(id)
+  }
+
+  // --------- converters ----------
+  async quoteToBaseQty(params: { exchangeId: string; symbol: string; quoteCost: number; price?: number }) {
+    const ex = this.registry.require(params.exchangeId)
+    const baseQty = await ex.quoteToBaseQty({ symbol: params.symbol, quoteCost: params.quoteCost, price: params.price })
+    return { baseQty }
+  }
+
+  async baseQtyToQuote(params: { exchangeId: string; symbol: string; baseQty: number; price?: number }) {
+    const ex = this.registry.require(params.exchangeId)
+    const quoteCost = await ex.baseQtyToQuote({ symbol: params.symbol, baseQty: params.baseQty, price: params.price })
+    return { quoteCost }
+  }
+
+  // --------- universal spot ----------
+  async openSpotPosition(params: { exchangeId: string; symbol: string; quoteCost: number }) {
+    const ex = this.registry.require(params.exchangeId)
+    const order = await ex.marketBuySpot(params.symbol, params.quoteCost)
+    return { orderId: order.id, filledBase: order.amount, avgPrice: order.price ?? 0 }
+  }
+
+  async closeSpotMarket(params: { exchangeId: string; symbol: string; baseQty: number }) {
+    const ex = this.registry.require(params.exchangeId)
+    const order = await ex.marketSellSpot(params.symbol, params.baseQty)
+    return { orderId: order.id }
+  }
+
+  async placeSpotLimit(params: { exchangeId: string; symbol: string; side: 'buy'|'sell'; baseQty: number; price: number }) {
+    const ex = this.registry.require(params.exchangeId)
+    const order = await ex.limitOrderSpot(params.symbol, params.side, params.baseQty, params.price)
+    return { orderId: order.id }
+  }
+
+  // --------- universal futures ----------
+  async openFuturesPosition(params: {
+    exchangeId: string
+    symbol: string
+    side: PositionSide
+    costUSDT: number
+    leverage?: number
+    price?: number | null // null/undefined => market
+  }) {
+    const ex = this.registry.require(params.exchangeId)
+    const order = await ex.openFutures({
+      symbol: params.symbol,
+      side: params.side,
+      costUSDT: params.costUSDT,
+      leverage: params.leverage,
+      price: params.price,
+    })
+    return { orderId: order.id }
+  }
+
+  async closeFuturesPosition(params: {
+    exchangeId: string
+    symbol: string
+    side: PositionSide
+    closeMode: 'all'|'cost'
+    costUSDT?: number
+  }) {
+    const ex = this.registry.require(params.exchangeId)
+    const order = await ex.closeFutures({
+      symbol: params.symbol,
+      side: params.side,
+      closeMode: params.closeMode,
+      costUSDT: params.costUSDT,
+    })
+    return { orderId: order.id }
+  }
+
+  // --------- risk ----------
+  async placeTakeProfit(o: TakeProfitOrder) { this.placeLogical(o); return { id: o.id } }
+  async placeStopLoss(o: StopLossOrder) { this.placeLogical(o); return { id: o.id } }
+  async placeTrailingStop(o: TrailingStopOrder) { this.placeLogical(o); return { id: o.id } }
+
+  async cancelLogical(id: string) { this.riskEngine.cancel(id) }
+  getActiveLogicalOrders(): LogicalOrder[] { return this.riskEngine.list() }
+
+  startRiskPolling() { this.riskScheduler.start() }
+  stopRiskPolling() { this.riskScheduler.stop() }
+
+  private placeLogical(o: LogicalOrder) {
+    const ex = this.registry.get(o.exchangeId)
+    if (!ex) throw new Error(`no exchange ${o.exchangeId}`)
+    this.riskEngine.place(o)
+    this.riskScheduler.start()
+  }
+}

package/src/clients/GateClient.ts

@@ -0,0 +1,52 @@
+import type { PositionSide } from '../core/exchange'
+import type { FluxAction } from '../FluxAction'
+
+export class GateClient {
+  constructor(
+    private flux: FluxAction,
+    private ids: { spot: string; futures: string },
+  ) {}
+
+  // converters
+  quoteToBaseQty(params: { symbol: string; quoteCost: number; price?: number }) {
+    return this.flux.quoteToBaseQty({ exchangeId: this.ids.spot, ...params })
+  }
+
+  baseQtyToQuote(params: { symbol: string; baseQty: number; price?: number }) {
+    return this.flux.baseQtyToQuote({ exchangeId: this.ids.spot, ...params })
+  }
+
+  // spot
+  openSpotPosition(params: { symbol: string; quoteCost: number }) {
+    return this.flux.openSpotPosition({ exchangeId: this.ids.spot, ...params })
+  }
+
+  closeSpotMarket(params: { symbol: string; baseQty: number }) {
+    return this.flux.closeSpotMarket({ exchangeId: this.ids.spot, ...params })
+  }
+
+  placeSpotLimit(params: { symbol: string; side: 'buy' | 'sell'; baseQty: number; price: number }) {
+    return this.flux.placeSpotLimit({ exchangeId: this.ids.spot, ...params })
+  }
+
+  // futures
+  openFuturesPosition(params: {
+    symbol: string
+    side: PositionSide
+    costUSDT: number
+    leverage?: number
+    price?: number | null // null/undefined => market
+  }) {
+    return this.flux.openFuturesPosition({ exchangeId: this.ids.futures, ...params })
+  }
+
+  closeFuturesPosition(params: { symbol: string; side: PositionSide; closeMode?: 'all' | 'cost'; costUSDT?: number }) {
+    return this.flux.closeFuturesPosition({
+      exchangeId: this.ids.futures,
+      symbol: params.symbol,
+      side: params.side,
+      closeMode: params.closeMode ?? 'all',
+      costUSDT: params.costUSDT,
+    })
+  }
+}

package/src/core/exchange.ts

@@ -61,6 +61,11 @@ export interface ExchangeAdapter {
   fetchOpenOrders(symbol?: string): Promise<OrderInfo[]>
   cancelOrder(symbol: string, orderId: string): Promise<void>
 
+  // helpers
+  quoteToBaseQty(params: { symbol: string; quoteCost: number; price?: number }): Promise<number>
+  baseQtyToQuote(params: { symbol: string; baseQty: number; price?: number }): Promise<number>
+
+  // spot
   marketBuySpot(symbol: string, quoteCost: number): Promise<OrderInfo>
   marketSellSpot(symbol: string, baseAmount: number): Promise<OrderInfo>
   limitOrderSpot(
@@ -70,16 +75,19 @@ export interface ExchangeAdapter {
     price: number,
   ): Promise<OrderInfo>
 
+  // futures
   openFutures(params: {
     symbol: string
     side: PositionSide
     costUSDT: number
     leverage?: number
+    price?: number | null 
   }): Promise<OrderInfo>
 
   closeFutures(params: {
     symbol: string
     side: PositionSide
+    closeMode: 'all' | 'cost'
     costUSDT?: number
   }): Promise<OrderInfo>
 

package/src/core/logicalOrders.ts

@@ -1,11 +1,28 @@
 export type LogicalOrderKind = 'take-profit' | 'stop-loss' | 'trailing-stop'
+export type MarketScope = 'spot' | 'futures'
+export type FuturesPositionSide = 'long' | 'short'
+
+export type ExitMode = 'all' // MVP: закрываем всю позицию по symbol
 
 export interface LogicalOrderBase {
   id: string
   exchangeId: string
+  market: MarketScope
   symbol: string
-  side: 'buy' | 'sell'
-  qty: number
+
+  kind: LogicalOrderKind
+
+  // trigger side semantics:
+  // - spot: side 'sell' обычно означает выход из long spot позиции
+  // - futures: мы используем positionSide + exitMode
+  side?: 'buy' | 'sell'
+
+  // spot
+  qty?: number // base qty
+
+  // futures
+  positionSide?: FuturesPositionSide
+  exitMode?: ExitMode
 }
 
 export interface TakeProfitOrder extends LogicalOrderBase {
@@ -20,12 +37,9 @@ export interface StopLossOrder extends LogicalOrderBase {
 
 export interface TrailingStopOrder extends LogicalOrderBase {
   kind: 'trailing-stop'
-  callbackRate: number 
+  callbackRate: number
   activationPrice?: number
   highWatermark?: number
 }
 
-export type LogicalOrder =
-  | TakeProfitOrder
-  | StopLossOrder
-  | TrailingStopOrder
+export type LogicalOrder = TakeProfitOrder | StopLossOrder | TrailingStopOrder

package/src/core/orders.ts

@@ -0,0 +1,7 @@
+export type OrderKind = 'market' | 'limit'
+
+export type MarketOrLimit =
+  | { kind: 'market' }
+  | { kind: 'limit'; price: number }
+
+export type SpotSide = 'buy' | 'sell'