@clawnch/clawncher-sdk 0.3.2 → 0.3.3

package/dist/hummingbot-types.d.ts

@@ -0,0 +1,702 @@
+/**
+ * Hummingbot SDK Types
+ *
+ * Types for interacting with the Hummingbot API server for automated
+ * cryptocurrency trading, market making, and portfolio management
+ * across 40+ exchange connectors.
+ *
+ * @see https://github.com/hummingbot/hummingbot
+ * @see https://github.com/hummingbot/mcp
+ */
+export interface HummingbotConfig {
+    /** Hummingbot API server URL (default: http://localhost:8000) */
+    apiUrl?: string;
+    /** API username (default: admin) */
+    username?: string;
+    /** API password (default: admin) */
+    password?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Delay between retries in milliseconds (default: 2000) */
+    retryDelay?: number;
+}
+export interface HummingbotServerConfig {
+    /** Server name */
+    name: string;
+    /** API URL */
+    url: string;
+    /** API username */
+    username: string;
+    /** API password */
+    password: string;
+    /** Whether this is the default server */
+    isDefault: boolean;
+}
+export interface HummingbotConnectorField {
+    /** Field name */
+    name: string;
+    /** Field type */
+    type: string;
+    /** Whether the field is required */
+    required: boolean;
+    /** Field description */
+    description?: string;
+}
+export interface HummingbotConnectorInfo {
+    /** Connector name (e.g. 'binance', 'binance_perpetual') */
+    name: string;
+    /** Required credential fields */
+    fields: HummingbotConnectorField[];
+}
+export interface HummingbotSetupConnectorRequest {
+    /** Action: 'setup' or 'delete' */
+    action?: 'setup' | 'delete';
+    /** Exchange connector name */
+    connector?: string;
+    /** Credentials object */
+    credentials?: Record<string, string>;
+    /** Account name */
+    account?: string;
+    /** Confirm override of existing connector */
+    confirmOverride?: boolean;
+}
+export interface HummingbotTokenBalance {
+    /** Token symbol */
+    token: string;
+    /** Available balance */
+    available: number;
+    /** Frozen/locked balance */
+    frozen: number;
+    /** Total balance */
+    total: number;
+    /** Balance value in USD */
+    valueUsd?: number;
+}
+export interface HummingbotPerpPosition {
+    /** Trading pair */
+    tradingPair: string;
+    /** Position side: LONG or SHORT */
+    side: 'LONG' | 'SHORT';
+    /** Position amount */
+    amount: number;
+    /** Entry price */
+    entryPrice: number;
+    /** Mark price */
+    markPrice: number;
+    /** Unrealized PnL */
+    unrealizedPnl: number;
+    /** Leverage */
+    leverage: number;
+    /** Connector name */
+    connector: string;
+    /** Account name */
+    account: string;
+}
+export interface HummingbotLPPosition {
+    /** Pool address */
+    poolAddress: string;
+    /** Position address/NFT ID */
+    positionAddress: string;
+    /** Trading pair */
+    tradingPair: string;
+    /** Lower price range */
+    lowerPrice: number;
+    /** Upper price range */
+    upperPrice: number;
+    /** Current price */
+    currentPrice: number;
+    /** Base token amount */
+    baseAmount: number;
+    /** Quote token amount */
+    quoteAmount: number;
+    /** Uncollected base fees */
+    uncollectedBaseFees: number;
+    /** Uncollected quote fees */
+    uncollectedQuoteFees: number;
+    /** Whether position is in range */
+    inRange: boolean;
+    /** Connector name */
+    connector: string;
+    /** Network */
+    network: string;
+}
+export interface HummingbotActiveOrder {
+    /** Order ID */
+    orderId: string;
+    /** Trading pair */
+    tradingPair: string;
+    /** Order type */
+    orderType: string;
+    /** Trade side */
+    side: 'BUY' | 'SELL';
+    /** Order amount */
+    amount: number;
+    /** Order price */
+    price: number;
+    /** Filled amount */
+    filledAmount: number;
+    /** Order status */
+    status: string;
+    /** Connector name */
+    connector: string;
+    /** Account name */
+    account: string;
+}
+export interface HummingbotPortfolioOverview {
+    /** Token balances across all exchanges */
+    balances: HummingbotTokenBalance[];
+    /** Open perpetual positions */
+    perpPositions: HummingbotPerpPosition[];
+    /** LP (CLMM) positions */
+    lpPositions: HummingbotLPPosition[];
+    /** Active orders */
+    activeOrders: HummingbotActiveOrder[];
+    /** Raw formatted output from the API */
+    formattedOutput: string;
+}
+export interface HummingbotPortfolioRequest {
+    /** Filter by account names */
+    accountNames?: string[];
+    /** Filter by connector names */
+    connectorNames?: string[];
+    /** Include token balances */
+    includeBalances?: boolean;
+    /** Include perpetual positions */
+    includePerpPositions?: boolean;
+    /** Include LP positions */
+    includeLPPositions?: boolean;
+    /** Include active orders */
+    includeActiveOrders?: boolean;
+    /** Show balances as distribution percentages */
+    asDistribution?: boolean;
+    /** Force refresh from exchanges */
+    refresh?: boolean;
+}
+export type HummingbotOrderType = 'MARKET' | 'LIMIT' | 'LIMIT_MAKER';
+export type HummingbotTradeType = 'BUY' | 'SELL';
+export type HummingbotPositionAction = 'OPEN' | 'CLOSE';
+export interface HummingbotPlaceOrderRequest {
+    /** Exchange connector name */
+    connectorName: string;
+    /** Trading pair (e.g. 'BTC-USDT') */
+    tradingPair: string;
+    /** Order side */
+    tradeType: HummingbotTradeType;
+    /** Order amount (base currency, or '$100' for USD) */
+    amount: string;
+    /** Order type */
+    orderType?: HummingbotOrderType;
+    /** Price for limit orders */
+    price?: string;
+    /** Position action for perpetuals */
+    positionAction?: HummingbotPositionAction;
+    /** Account name */
+    accountName?: string;
+}
+export interface HummingbotOrderResult {
+    /** Whether the order was placed successfully */
+    success: boolean;
+    /** Order ID */
+    orderId?: string;
+    /** Result message */
+    result: string;
+}
+export interface HummingbotSetLeverageRequest {
+    /** Account name */
+    accountName: string;
+    /** Exchange connector name */
+    connectorName: string;
+    /** Trading pair */
+    tradingPair?: string;
+    /** Position mode */
+    positionMode?: 'HEDGE' | 'ONE-WAY';
+    /** Leverage multiplier */
+    leverage?: number;
+}
+export type HummingbotExecutorType = 'position_executor' | 'dca_executor' | 'grid_executor' | 'order_executor' | 'arbitrage_executor';
+export type HummingbotExecutorStatus = 'RUNNING' | 'TERMINATED';
+export interface HummingbotExecutorConfig {
+    /** Executor type */
+    executorType: HummingbotExecutorType;
+    /** Exchange connector name */
+    connectorName: string;
+    /** Trading pair */
+    tradingPair: string;
+    /** Account name */
+    accountName?: string;
+    /** Additional config specific to executor type */
+    [key: string]: unknown;
+}
+/** Position executor config */
+export interface HummingbotPositionExecutorConfig extends HummingbotExecutorConfig {
+    executorType: 'position_executor';
+    /** Trade side: 1=BUY, 2=SELL */
+    side: 1 | 2;
+    /** Entry price */
+    entryPrice?: number;
+    /** Amount in base currency */
+    amount: number;
+    /** Stop loss percentage (as decimal, e.g. 0.03 = 3%) */
+    stopLoss?: number;
+    /** Take profit percentage */
+    takeProfit?: number;
+    /** Time limit in seconds */
+    timeLimit?: number;
+    /** Order type: 1=MARKET, 2=LIMIT, 3=LIMIT_MAKER */
+    orderType?: 1 | 2 | 3;
+}
+/** Grid executor config */
+export interface HummingbotGridExecutorConfig extends HummingbotExecutorConfig {
+    executorType: 'grid_executor';
+    /** Trade side: 1=BUY (LONG), 2=SELL (SHORT) */
+    side: 1 | 2;
+    /** Start price of grid range */
+    startPrice: number;
+    /** End price of grid range */
+    endPrice: number;
+    /** Limit price (safety boundary) */
+    limitPrice: number;
+    /** Total amount in quote currency */
+    totalAmountQuote: number;
+    /** Number of grid levels */
+    levels?: number;
+    /** Whether to keep position on stop */
+    keepPosition?: boolean;
+}
+/** DCA executor config */
+export interface HummingbotDCAExecutorConfig extends HummingbotExecutorConfig {
+    executorType: 'dca_executor';
+    /** Trade side: 1=BUY, 2=SELL */
+    side: 1 | 2;
+    /** Amounts per level in quote currency */
+    amountsQuote: number[];
+    /** Price intervals between DCA levels (as percentages) */
+    priceIntervals?: number[];
+    /** Time between DCA orders in seconds */
+    timeBetweenOrders?: number;
+    /** Stop loss percentage */
+    stopLoss?: number;
+    /** Take profit percentage */
+    takeProfit?: number;
+}
+/** Order executor config */
+export interface HummingbotOrderExecutorConfig extends HummingbotExecutorConfig {
+    executorType: 'order_executor';
+    /** Trade side: 1=BUY, 2=SELL */
+    side: 1 | 2;
+    /** Amount (base currency, or '$100' for USD) */
+    amount: string;
+    /** Execution strategy: MARKET, LIMIT, LIMIT_MAKER, LIMIT_CHASER */
+    executionStrategy?: string;
+    /** Price for limit orders */
+    price?: number;
+}
+export interface HummingbotExecutorInfo {
+    /** Executor ID */
+    executorId: string;
+    /** Executor type */
+    executorType: HummingbotExecutorType;
+    /** Trading pair */
+    tradingPair: string;
+    /** Status */
+    status: HummingbotExecutorStatus;
+    /** Connector name */
+    connectorName: string;
+    /** Account name */
+    accountName: string;
+    /** PnL in quote currency */
+    pnlQuote?: number;
+    /** PnL percentage */
+    pnlPct?: number;
+    /** Volume traded */
+    volumeTraded?: number;
+    /** Creation timestamp */
+    createdAt?: number;
+    /** Termination timestamp */
+    terminatedAt?: number;
+    /** Raw config */
+    config?: Record<string, unknown>;
+}
+export interface HummingbotManageExecutorsRequest {
+    /** Action to perform */
+    action?: 'create' | 'search' | 'stop' | 'get_logs' | 'get_preferences' | 'save_preferences' | 'reset_preferences' | 'positions_summary' | 'clear_position';
+    /** Executor type (for schema discovery or creation) */
+    executorType?: HummingbotExecutorType;
+    /** Config for creation */
+    executorConfig?: HummingbotExecutorConfig;
+    /** Executor ID for stop/logs */
+    executorId?: string;
+    /** Log level filter */
+    logLevel?: 'ERROR' | 'WARNING' | 'INFO' | 'DEBUG';
+    /** Filter by account names */
+    accountNames?: string[];
+    /** Filter by connector names */
+    connectorNames?: string[];
+    /** Filter by trading pairs */
+    tradingPairs?: string[];
+    /** Filter by executor types */
+    executorTypes?: HummingbotExecutorType[];
+    /** Filter by status */
+    status?: HummingbotExecutorStatus;
+    /** Pagination cursor */
+    cursor?: string;
+    /** Max results */
+    limit?: number;
+    /** Keep position when stopping */
+    keepPosition?: boolean;
+    /** Save config as default */
+    saveAsDefault?: boolean;
+    /** Preferences markdown content */
+    preferencesContent?: string;
+    /** Account name for creation */
+    accountName?: string;
+    /** Connector name for position filtering */
+    connectorName?: string;
+    /** Trading pair for position filtering */
+    tradingPair?: string;
+}
+export type HummingbotMarketDataType = 'prices' | 'candles' | 'funding_rate' | 'order_book';
+export type HummingbotCandleInterval = '1m' | '5m' | '15m' | '30m' | '1h' | '4h' | '1d';
+export interface HummingbotPriceData {
+    /** Trading pair */
+    tradingPair: string;
+    /** Mid price */
+    midPrice: number;
+    /** Best ask */
+    bestAsk: number;
+    /** Best bid */
+    bestBid: number;
+    /** Timestamp */
+    timestamp: string;
+}
+export interface HummingbotCandle {
+    /** Timestamp */
+    timestamp: string;
+    /** Open price */
+    open: number;
+    /** High price */
+    high: number;
+    /** Low price */
+    low: number;
+    /** Close price */
+    close: number;
+    /** Volume */
+    volume: number;
+}
+export interface HummingbotCandlesResponse {
+    /** Connector name */
+    connectorName: string;
+    /** Trading pair */
+    tradingPair: string;
+    /** Candle interval */
+    interval: HummingbotCandleInterval;
+    /** Total candles */
+    totalCandles: number;
+    /** Candle data */
+    candles: HummingbotCandle[];
+    /** Raw formatted table */
+    candlesTable: string;
+}
+export interface HummingbotFundingRate {
+    /** Trading pair */
+    tradingPair: string;
+    /** Connector name */
+    connectorName: string;
+    /** Funding rate percentage */
+    fundingRatePct: number;
+    /** Mark price */
+    markPrice: number;
+    /** Index price */
+    indexPrice: number;
+    /** Next funding time */
+    nextFundingTime: string;
+}
+export type HummingbotOrderBookQueryType = 'snapshot' | 'volume_for_price' | 'price_for_volume' | 'quote_volume_for_price' | 'price_for_quote_volume';
+export interface HummingbotOrderBookLevel {
+    /** Price */
+    price: number;
+    /** Amount */
+    amount: number;
+    /** Cumulative amount */
+    cumulativeAmount?: number;
+}
+export interface HummingbotOrderBookSnapshot {
+    /** Trading pair */
+    tradingPair: string;
+    /** Connector name */
+    connectorName: string;
+    /** Timestamp */
+    timestamp: string;
+    /** Bids */
+    bids: HummingbotOrderBookLevel[];
+    /** Asks */
+    asks: HummingbotOrderBookLevel[];
+}
+export interface HummingbotMarketDataRequest {
+    /** Data type */
+    dataType: HummingbotMarketDataType;
+    /** Connector name */
+    connectorName: string;
+    /** Trading pairs (for 'prices') */
+    tradingPairs?: string[];
+    /** Trading pair (for candles, funding, order book) */
+    tradingPair?: string;
+    /** Candle interval */
+    interval?: HummingbotCandleInterval;
+    /** Days of historical data */
+    days?: number;
+    /** Order book query type */
+    queryType?: HummingbotOrderBookQueryType;
+    /** Order book query value */
+    queryValue?: number;
+    /** Order book side */
+    isBuy?: boolean;
+}
+export type HummingbotControllerType = 'directional_trading' | 'market_making' | 'generic';
+export interface HummingbotControllerInfo {
+    /** Controller name */
+    name: string;
+    /** Controller type */
+    type: HummingbotControllerType;
+    /** Description */
+    description?: string;
+    /** Source code */
+    code?: string;
+    /** Number of configs */
+    configCount?: number;
+}
+export interface HummingbotControllerConfig {
+    /** Config name */
+    name: string;
+    /** Controller name */
+    controllerName: string;
+    /** Controller type */
+    controllerType: HummingbotControllerType;
+    /** Config data */
+    data: Record<string, unknown>;
+}
+export interface HummingbotBotInfo {
+    /** Bot name */
+    name: string;
+    /** Bot status */
+    status: string;
+    /** Controllers */
+    controllers: string[];
+    /** Account name */
+    accountName: string;
+    /** Uptime */
+    uptime?: string;
+    /** PnL */
+    pnl?: number;
+}
+export interface HummingbotBotDeployRequest {
+    /** Bot name */
+    botName: string;
+    /** Controller config names */
+    controllersConfig: string[];
+    /** Account name */
+    accountName?: string;
+    /** Max global drawdown in quote currency */
+    maxGlobalDrawdownQuote?: number;
+    /** Max per-controller drawdown */
+    maxControllerDrawdownQuote?: number;
+    /** Docker image */
+    image?: string;
+}
+export interface HummingbotBotLogsRequest {
+    /** Bot name */
+    botName: string;
+    /** Log type filter */
+    logType?: 'error' | 'general' | 'all';
+    /** Max entries */
+    limit?: number;
+    /** Search term */
+    searchTerm?: string;
+}
+export interface HummingbotGatewayStatus {
+    /** Whether Gateway is running */
+    running: boolean;
+    /** Container ID */
+    containerId?: string;
+    /** Status message */
+    status: string;
+}
+export interface HummingbotGatewayStartConfig {
+    /** Gateway passphrase */
+    passphrase: string;
+    /** Docker image */
+    image: string;
+    /** Port (default: 15888) */
+    port?: number;
+    /** Environment variables */
+    environment?: Record<string, string>;
+}
+export interface HummingbotGatewaySwapRequest {
+    /** Action */
+    action: 'quote' | 'execute' | 'search' | 'get_status';
+    /** DEX connector name (e.g. 'jupiter', '0x') */
+    connector?: string;
+    /** Network ID (e.g. 'solana-mainnet-beta') */
+    network?: string;
+    /** Trading pair */
+    tradingPair?: string;
+    /** Trade side */
+    side?: 'BUY' | 'SELL';
+    /** Amount */
+    amount?: string;
+    /** Slippage percentage */
+    slippagePct?: string;
+    /** Wallet address */
+    walletAddress?: string;
+    /** Tx hash for status check */
+    transactionHash?: string;
+}
+export interface HummingbotGatewaySwapQuote {
+    /** Expected price */
+    price: number;
+    /** Expected output amount */
+    expectedAmount: string;
+    /** Gas estimate */
+    gasEstimate?: number;
+    /** Network */
+    network: string;
+    /** Connector */
+    connector: string;
+}
+export interface HummingbotGatewayCLMMRequest {
+    /** Action */
+    action: 'list_pools' | 'get_pool_info' | 'open_position' | 'close_position' | 'collect_fees' | 'get_positions';
+    /** CLMM connector name */
+    connector?: string;
+    /** Network ID */
+    network?: string;
+    /** Pool address */
+    poolAddress?: string;
+    /** Position address */
+    positionAddress?: string;
+    /** Pagination page */
+    page?: number;
+    /** Results limit */
+    limit?: number;
+    /** Search term */
+    searchTerm?: string;
+    /** Sort key */
+    sortKey?: string;
+    /** Sort order */
+    orderBy?: 'asc' | 'desc';
+    /** Wallet address */
+    walletAddress?: string;
+    /** Lower price for open_position */
+    lowerPrice?: string;
+    /** Upper price for open_position */
+    upperPrice?: string;
+    /** Base token amount */
+    baseTokenAmount?: string;
+    /** Quote token amount */
+    quoteTokenAmount?: string;
+    /** Slippage */
+    slippagePct?: string;
+}
+export interface HummingbotCLMMPool {
+    /** Pool address */
+    address: string;
+    /** Base token */
+    baseToken: string;
+    /** Quote token */
+    quoteToken: string;
+    /** Fee rate */
+    feeRate: number;
+    /** TVL in USD */
+    tvlUsd: number;
+    /** 24h volume in USD */
+    volume24hUsd: number;
+    /** Current price */
+    price: number;
+}
+export type HummingbotHistoryDataType = 'orders' | 'perp_positions' | 'clmm_positions';
+export interface HummingbotHistorySearchRequest {
+    /** Data type to search */
+    dataType: HummingbotHistoryDataType;
+    /** Filter by account names */
+    accountNames?: string[];
+    /** Filter by connector names */
+    connectorNames?: string[];
+    /** Filter by trading pairs */
+    tradingPairs?: string[];
+    /** Filter by status */
+    status?: string;
+    /** Start timestamp (seconds) */
+    startTime?: number;
+    /** End timestamp (seconds) */
+    endTime?: number;
+    /** Max results */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+    /** Network filter (CLMM only) */
+    network?: string;
+    /** Wallet address filter (CLMM only) */
+    walletAddress?: string;
+    /** Position addresses (CLMM only) */
+    positionAddresses?: string[];
+}
+export interface HummingbotHistoricalOrder {
+    /** Order ID */
+    orderId: string;
+    /** Trading pair */
+    tradingPair: string;
+    /** Order type */
+    orderType: string;
+    /** Trade side */
+    side: string;
+    /** Amount */
+    amount: number;
+    /** Price */
+    price: number;
+    /** Filled amount */
+    filledAmount: number;
+    /** Status */
+    status: string;
+    /** Connector name */
+    connector: string;
+    /** Account name */
+    account: string;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Update timestamp */
+    updatedAt: number;
+}
+export type HummingbotStrategyTemplate = 'clawnch_initial_liquidity' | 'clawnch_post_launch_mm' | 'clawnch_fee_optimization' | 'clawnch_accumulation' | 'pure_market_making' | 'avellaneda_market_making' | 'grid_trading' | 'dca_buying' | 'twap_execution';
+export interface HummingbotStrategyTemplateConfig {
+    /** Template name */
+    template: HummingbotStrategyTemplate;
+    /** Template description */
+    description: string;
+    /** Executor type used */
+    executorType: HummingbotExecutorType;
+    /** Pre-configured parameters */
+    defaultConfig: Record<string, unknown>;
+    /** Parameters that should be customized */
+    requiredOverrides: string[];
+}
+export interface HummingbotDockerInstance {
+    /** Container name */
+    name: string;
+    /** Container status */
+    status: string;
+    /** Creation time */
+    created: string;
+}
+export interface HummingbotDockerPrerequisites {
+    /** Docker available */
+    docker: boolean;
+    /** Hummingbot image installed */
+    image: boolean;
+    /** Hummingbot MCP server running */
+    mcp: boolean;
+    /** Hummingbot API server running */
+    api: boolean;
+}
+//# sourceMappingURL=hummingbot-types.d.ts.map