@metaflux/fluxaction 0.1.3

package/dist/core/RiskManager.d.ts

@@ -0,0 +1,22 @@
+import type { ExchangeAdapter } from './exchange';
+import type { LogicalOrder, TakeProfitOrder, StopLossOrder, TrailingStopOrder } from './logicalOrders';
+export interface RiskManagerConfig {
+    exchanges: Record<string, ExchangeAdapter>;
+    pollIntervalMs?: number;
+}
+export declare class RiskManager {
+    private cfg;
+    private orders;
+    private started;
+    constructor(cfg: RiskManagerConfig);
+    registerExchange(ex: ExchangeAdapter): void;
+    placeTakeProfit(o: TakeProfitOrder): Promise<void>;
+    placeStopLoss(o: StopLossOrder): Promise<void>;
+    placeTrailingStop(o: TrailingStopOrder): Promise<void>;
+    cancel(id: string): Promise<void>;
+    getActiveOrders(): LogicalOrder[];
+    private startPolling;
+    private tick;
+    private processForSymbol;
+    private executeAndClear;
+}

package/dist/core/RiskManager.js

@@ -0,0 +1,179 @@
+export class RiskManager {
+    constructor(cfg) {
+        this.orders = new Map();
+        this.started = false;
+        this.cfg = cfg;
+    }
+    registerExchange(ex) {
+        this.cfg.exchanges[ex.id] = ex;
+    }
+    async placeTakeProfit(o) {
+        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) {
+        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) {
+        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) {
+        this.orders.delete(id);
+    }
+    getActiveOrders() {
+        return [...this.orders.values()];
+    }
+    startPolling() {
+        if (this.started)
+            return;
+        this.started = true;
+        const interval = this.cfg.pollIntervalMs ?? 3000;
+        setInterval(() => {
+            this.tick().catch((e) => {
+                console.error('[RiskManager] tick error', e);
+            });
+        }, interval);
+    }
+    async tick() {
+        const grouped = {};
+        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);
+            }
+        }
+    }
+    async processForSymbol(ex, symbol, orders) {
+        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;
+                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;
+                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;
+                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);
+                }
+            }
+        }
+    }
+    async executeAndClear(ex, o, price) {
+        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) {
+                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/dist/core/exchange.d.ts

@@ -0,0 +1,76 @@
+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/dist/core/exchange.js

@@ -0,0 +1 @@
+export {};

package/dist/core/logicalOrders.d.ts

@@ -0,0 +1,23 @@
+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/dist/core/logicalOrders.js

@@ -0,0 +1 @@
+export {};

package/dist/core/results.d.ts

@@ -0,0 +1,18 @@
+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/dist/core/results.js

@@ -0,0 +1 @@
+export {};

package/dist/exchanges/GateSpotAdapter.d.ts

@@ -0,0 +1,33 @@
+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 declare class GateSpotAdapter implements ExchangeAdapter {
+    readonly id: string;
+    readonly label: string;
+    readonly capabilities: ExchangeCapabilities;
+    private ex;
+    constructor(cfg: GateSpotAdapterConfig);
+    loadMarkets(): Promise<void>;
+    hasSpotMarket(symbol: string): boolean;
+    hasFuturesMarket(): boolean;
+    getMarket(symbol: string): MarketInfo | undefined;
+    private roundAmount;
+    private roundPrice;
+    private mapOrder;
+    fetchTicker(symbol: string): Promise<{
+        last: number;
+    }>;
+    fetchBalance(): Promise<any>;
+    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: 'buy' | 'sell', baseAmount: number, price: number): Promise<OrderInfo>;
+    openFutures(): Promise<OrderInfo>;
+    closeFutures(): Promise<OrderInfo>;
+    fetchPositions(): Promise<PositionInfo[]>;
+}

package/dist/exchanges/GateSpotAdapter.js

@@ -0,0 +1,146 @@
+import ccxt from 'ccxt';
+export class GateSpotAdapter {
+    constructor(cfg) {
+        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,
+            },
+        });
+        this.capabilities = {
+            spot: {
+                nativeTakeProfit: false,
+                nativeStopLoss: false,
+                nativeTrailingStop: false,
+            },
+            futures: {
+                nativeTakeProfit: false,
+                nativeStopLoss: false,
+                nativeTrailingStop: false,
+            },
+        };
+    }
+    async loadMarkets() {
+        await this.ex.loadMarkets();
+    }
+    hasSpotMarket(symbol) {
+        const m = this.ex.markets?.[symbol];
+        return !!m && m.type === 'spot';
+    }
+    hasFuturesMarket() {
+        return false;
+    }
+    getMarket(symbol) {
+        const m = this.ex.markets?.[symbol];
+        if (!m)
+            return undefined;
+        return {
+            symbol: m.symbol,
+            base: m.base,
+            quote: m.quote,
+            type: m.type,
+            precisionAmount: m.precision?.amount,
+            precisionPrice: m.precision?.price,
+            minCost: m.limits?.cost?.min,
+            minAmount: m.limits?.amount?.min,
+        };
+    }
+    roundAmount(symbol, amount) {
+        const m = this.ex.markets?.[symbol];
+        if (!m)
+            return amount;
+        return Number(this.ex.amountToPrecision(symbol, amount));
+    }
+    roundPrice(symbol, price) {
+        const m = this.ex.markets?.[symbol];
+        if (!m)
+            return price;
+        return Number(this.ex.priceToPrecision(symbol, price));
+    }
+    mapOrder(symbol, o) {
+        const price = o.price ?? o.average ?? o.avgPrice;
+        let baseAmount;
+        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) {
+        const t = await this.ex.fetchTicker(symbol);
+        return { last: t.last ?? 0 };
+    }
+    async fetchBalance() {
+        const bal = await this.ex.fetchBalance();
+        return bal;
+    }
+    async fetchOpenOrders(symbol) {
+        const orders = await this.ex.fetchOpenOrders(symbol);
+        return orders.map((o) => this.mapOrder(o.symbol, o));
+    }
+    async cancelOrder(symbol, orderId) {
+        await this.ex.cancelOrder(orderId, symbol);
+    }
+    async marketBuySpot(symbol, quoteCost) {
+        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, baseAmount) {
+        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, side, baseAmount, price) {
+        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() {
+        throw new Error('gate-spot: futures not supported');
+    }
+    async closeFutures() {
+        throw new Error('gate-spot: futures not supported');
+    }
+    async fetchPositions() {
+        return [];
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import type { ExchangeAdapter } from './core/exchange';
+import { type TakeProfitOrder, type StopLossOrder, type TrailingStopOrder } from './core/logicalOrders';
+export interface FluxActionConfig {
+    okx?: {
+        apiKey: string;
+        secret: string;
+        passphrase: string;
+        isDemo?: boolean;
+    };
+    gate?: {
+        apiKey: string;
+        secret: string;
+    };
+    risk?: {
+        pollIntervalMs?: number;
+    };
+}
+export declare class FluxAction {
+    private adapters;
+    private risk;
+    constructor(cfg: FluxActionConfig);
+    init(): Promise<void>;
+    getExchange(id: string): ExchangeAdapter | undefined;
+    openSpotPosition(params: {
+        exchangeId: string;
+        symbol: string;
+        quoteCost: number;
+    }): Promise<{
+        orderId: string;
+        filledBase: number;
+        avgPrice: number;
+    }>;
+    closeSpotMarket(params: {
+        exchangeId: string;
+        symbol: string;
+        baseQty: number;
+    }): Promise<{
+        orderId: string;
+    }>;
+    placeSpotLimit(params: {
+        exchangeId: string;
+        symbol: string;
+        side: 'buy' | 'sell';
+        baseQty: number;
+        price: number;
+    }): Promise<{
+        orderId: string;
+    }>;
+    placeTakeProfit(o: TakeProfitOrder): Promise<{
+        id: string;
+    }>;
+    placeStopLoss(o: StopLossOrder): Promise<{
+        id: string;
+    }>;
+    placeTrailingStop(o: TrailingStopOrder): Promise<{
+        id: string;
+    }>;
+    cancelLogical(id: string): Promise<void>;
+    getActiveLogicalOrders(): import("./core/logicalOrders").LogicalOrder[];
+    private requireExchange;
+}
+export { RiskManager, type RiskManagerConfig } from './core/RiskManager';
+export type { ExchangeAdapter, ExchangeCapabilities, MarketInfo, OrderInfo, PositionInfo, } from './core/exchange';
+export { GateSpotAdapter, type GateSpotAdapterConfig, } from './exchanges/GateSpotAdapter';

package/dist/index.js

@@ -0,0 +1,70 @@
+import { RiskManager } from './core/RiskManager';
+import { GateSpotAdapter } from './exchanges/GateSpotAdapter';
+export class FluxAction {
+    constructor(cfg) {
+        this.adapters = {};
+        if (cfg.gate) {
+            const gate = new GateSpotAdapter({
+                id: 'gate-spot',
+                apiKey: cfg.gate.apiKey,
+                secret: cfg.gate.secret,
+            });
+            this.adapters[gate.id] = gate;
+        }
+        this.risk = new RiskManager({
+            exchanges: this.adapters,
+            pollIntervalMs: cfg.risk?.pollIntervalMs,
+        });
+    }
+    async init() {
+        await Promise.all(Object.values(this.adapters).map((a) => a.loadMarkets()));
+    }
+    getExchange(id) {
+        return this.adapters[id];
+    }
+    async openSpotPosition(params) {
+        const ex = this.requireExchange(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) {
+        const ex = this.requireExchange(params.exchangeId);
+        const order = await ex.marketSellSpot(params.symbol, params.baseQty);
+        return { orderId: order.id };
+    }
+    async placeSpotLimit(params) {
+        const ex = this.requireExchange(params.exchangeId);
+        const order = await ex.limitOrderSpot(params.symbol, params.side, params.baseQty, params.price);
+        return { orderId: order.id };
+    }
+    async placeTakeProfit(o) {
+        await this.risk.placeTakeProfit(o);
+        return { id: o.id };
+    }
+    async placeStopLoss(o) {
+        await this.risk.placeStopLoss(o);
+        return { id: o.id };
+    }
+    async placeTrailingStop(o) {
+        await this.risk.placeTrailingStop(o);
+        return { id: o.id };
+    }
+    async cancelLogical(id) {
+        await this.risk.cancel(id);
+    }
+    getActiveLogicalOrders() {
+        return this.risk.getActiveOrders();
+    }
+    requireExchange(id) {
+        const ex = this.adapters[id];
+        if (!ex)
+            throw new Error(`Exchange ${id} is not configured`);
+        return ex;
+    }
+}
+export { RiskManager } from './core/RiskManager';
+export { GateSpotAdapter, } from './exchanges/GateSpotAdapter';