@exagent/agent 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,673 @@
+import { z } from 'zod';
+import { Address, Hash } from 'viem';
+import { ExagentClient } from '@exagent/sdk';
+
+declare const LLMProviderSchema: z.ZodEnum<["openai", "anthropic", "google", "deepseek", "mistral", "groq", "together", "ollama", "custom"]>;
+type LLMProvider = z.infer<typeof LLMProviderSchema>;
+declare const LLMConfigSchema: z.ZodObject<{
+    provider: z.ZodEnum<["openai", "anthropic", "google", "deepseek", "mistral", "groq", "together", "ollama", "custom"]>;
+    model: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodDefault<z.ZodNumber>;
+    maxTokens: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    provider: "custom" | "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "ollama";
+    temperature: number;
+    maxTokens: number;
+    model?: string | undefined;
+    apiKey?: string | undefined;
+    endpoint?: string | undefined;
+}, {
+    provider: "custom" | "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "ollama";
+    model?: string | undefined;
+    apiKey?: string | undefined;
+    endpoint?: string | undefined;
+    temperature?: number | undefined;
+    maxTokens?: number | undefined;
+}>;
+type LLMConfig = z.infer<typeof LLMConfigSchema>;
+declare const RiskUniverseSchema: z.ZodEnum<["core", "established", "derivatives", "emerging", "frontier"]>;
+type RiskUniverse = z.infer<typeof RiskUniverseSchema>;
+declare const TradingConfigSchema: z.ZodObject<{
+    timeHorizon: z.ZodDefault<z.ZodEnum<["intraday", "swing", "position"]>>;
+    maxPositionSizeBps: z.ZodDefault<z.ZodNumber>;
+    maxDailyLossBps: z.ZodDefault<z.ZodNumber>;
+    maxConcurrentPositions: z.ZodDefault<z.ZodNumber>;
+    tradingIntervalMs: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    timeHorizon: "intraday" | "swing" | "position";
+    maxPositionSizeBps: number;
+    maxDailyLossBps: number;
+    maxConcurrentPositions: number;
+    tradingIntervalMs: number;
+}, {
+    timeHorizon?: "intraday" | "swing" | "position" | undefined;
+    maxPositionSizeBps?: number | undefined;
+    maxDailyLossBps?: number | undefined;
+    maxConcurrentPositions?: number | undefined;
+    tradingIntervalMs?: number | undefined;
+}>;
+type TradingConfig = z.infer<typeof TradingConfigSchema>;
+declare const VaultPolicySchema: z.ZodEnum<["disabled", "manual", "auto_when_qualified"]>;
+type VaultPolicy = z.infer<typeof VaultPolicySchema>;
+declare const VaultConfigSchema: z.ZodObject<{
+    policy: z.ZodDefault<z.ZodEnum<["disabled", "manual", "auto_when_qualified"]>>;
+    defaultName: z.ZodOptional<z.ZodString>;
+    defaultSymbol: z.ZodOptional<z.ZodString>;
+    feeRecipient: z.ZodOptional<z.ZodString>;
+    preferVaultTrading: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    policy: "disabled" | "manual" | "auto_when_qualified";
+    preferVaultTrading: boolean;
+    defaultName?: string | undefined;
+    defaultSymbol?: string | undefined;
+    feeRecipient?: string | undefined;
+}, {
+    policy?: "disabled" | "manual" | "auto_when_qualified" | undefined;
+    defaultName?: string | undefined;
+    defaultSymbol?: string | undefined;
+    feeRecipient?: string | undefined;
+    preferVaultTrading?: boolean | undefined;
+}>;
+type VaultConfig = z.infer<typeof VaultConfigSchema>;
+declare const AgentConfigSchema: z.ZodObject<{
+    agentId: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+    name: z.ZodString;
+    network: z.ZodDefault<z.ZodEnum<["mainnet", "testnet"]>>;
+    wallet: z.ZodOptional<z.ZodObject<{
+        setup: z.ZodDefault<z.ZodEnum<["generate", "provide"]>>;
+    }, "strip", z.ZodTypeAny, {
+        setup: "generate" | "provide";
+    }, {
+        setup?: "generate" | "provide" | undefined;
+    }>>;
+    llm: z.ZodObject<{
+        provider: z.ZodEnum<["openai", "anthropic", "google", "deepseek", "mistral", "groq", "together", "ollama", "custom"]>;
+        model: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        endpoint: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodDefault<z.ZodNumber>;
+        maxTokens: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        provider: "custom" | "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "ollama";
+        temperature: number;
+        maxTokens: number;
+        model?: string | undefined;
+        apiKey?: string | undefined;
+        endpoint?: string | undefined;
+    }, {
+        provider: "custom" | "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "ollama";
+        model?: string | undefined;
+        apiKey?: string | undefined;
+        endpoint?: string | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+    }>;
+    riskUniverse: z.ZodDefault<z.ZodEnum<["core", "established", "derivatives", "emerging", "frontier"]>>;
+    trading: z.ZodDefault<z.ZodObject<{
+        timeHorizon: z.ZodDefault<z.ZodEnum<["intraday", "swing", "position"]>>;
+        maxPositionSizeBps: z.ZodDefault<z.ZodNumber>;
+        maxDailyLossBps: z.ZodDefault<z.ZodNumber>;
+        maxConcurrentPositions: z.ZodDefault<z.ZodNumber>;
+        tradingIntervalMs: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        timeHorizon: "intraday" | "swing" | "position";
+        maxPositionSizeBps: number;
+        maxDailyLossBps: number;
+        maxConcurrentPositions: number;
+        tradingIntervalMs: number;
+    }, {
+        timeHorizon?: "intraday" | "swing" | "position" | undefined;
+        maxPositionSizeBps?: number | undefined;
+        maxDailyLossBps?: number | undefined;
+        maxConcurrentPositions?: number | undefined;
+        tradingIntervalMs?: number | undefined;
+    }>>;
+    vault: z.ZodDefault<z.ZodObject<{
+        policy: z.ZodDefault<z.ZodEnum<["disabled", "manual", "auto_when_qualified"]>>;
+        defaultName: z.ZodOptional<z.ZodString>;
+        defaultSymbol: z.ZodOptional<z.ZodString>;
+        feeRecipient: z.ZodOptional<z.ZodString>;
+        preferVaultTrading: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        policy: "disabled" | "manual" | "auto_when_qualified";
+        preferVaultTrading: boolean;
+        defaultName?: string | undefined;
+        defaultSymbol?: string | undefined;
+        feeRecipient?: string | undefined;
+    }, {
+        policy?: "disabled" | "manual" | "auto_when_qualified" | undefined;
+        defaultName?: string | undefined;
+        defaultSymbol?: string | undefined;
+        feeRecipient?: string | undefined;
+        preferVaultTrading?: boolean | undefined;
+    }>>;
+    allowedTokens: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    agentId: string | number;
+    name: string;
+    network: "mainnet" | "testnet";
+    llm: {
+        provider: "custom" | "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "ollama";
+        temperature: number;
+        maxTokens: number;
+        model?: string | undefined;
+        apiKey?: string | undefined;
+        endpoint?: string | undefined;
+    };
+    riskUniverse: "core" | "established" | "derivatives" | "emerging" | "frontier";
+    trading: {
+        timeHorizon: "intraday" | "swing" | "position";
+        maxPositionSizeBps: number;
+        maxDailyLossBps: number;
+        maxConcurrentPositions: number;
+        tradingIntervalMs: number;
+    };
+    vault: {
+        policy: "disabled" | "manual" | "auto_when_qualified";
+        preferVaultTrading: boolean;
+        defaultName?: string | undefined;
+        defaultSymbol?: string | undefined;
+        feeRecipient?: string | undefined;
+    };
+    wallet?: {
+        setup: "generate" | "provide";
+    } | undefined;
+    allowedTokens?: string[] | undefined;
+}, {
+    agentId: string | number;
+    name: string;
+    llm: {
+        provider: "custom" | "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "ollama";
+        model?: string | undefined;
+        apiKey?: string | undefined;
+        endpoint?: string | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+    };
+    network?: "mainnet" | "testnet" | undefined;
+    wallet?: {
+        setup?: "generate" | "provide" | undefined;
+    } | undefined;
+    riskUniverse?: "core" | "established" | "derivatives" | "emerging" | "frontier" | undefined;
+    trading?: {
+        timeHorizon?: "intraday" | "swing" | "position" | undefined;
+        maxPositionSizeBps?: number | undefined;
+        maxDailyLossBps?: number | undefined;
+        maxConcurrentPositions?: number | undefined;
+        tradingIntervalMs?: number | undefined;
+    } | undefined;
+    vault?: {
+        policy?: "disabled" | "manual" | "auto_when_qualified" | undefined;
+        defaultName?: string | undefined;
+        defaultSymbol?: string | undefined;
+        feeRecipient?: string | undefined;
+        preferVaultTrading?: boolean | undefined;
+    } | undefined;
+    allowedTokens?: string[] | undefined;
+}>;
+type AgentConfig = z.infer<typeof AgentConfigSchema>;
+interface RuntimeConfig extends AgentConfig {
+    privateKey: `0x${string}`;
+}
+interface MarketData {
+    timestamp: number;
+    prices: Record<string, number>;
+    balances: Record<string, bigint>;
+    portfolioValue: number;
+}
+interface TradeSignal {
+    action: 'buy' | 'sell' | 'hold';
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: bigint;
+    confidence: number;
+    reasoning?: string;
+}
+interface LLMMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface LLMResponse {
+    content: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+type StrategyFunction = (marketData: MarketData, llm: LLMAdapter, config: AgentConfig) => Promise<TradeSignal[]>;
+interface LLMAdapter {
+    chat(messages: LLMMessage[]): Promise<LLMResponse>;
+    getMetadata(): LLMMetadata;
+}
+interface LLMMetadata {
+    provider: LLMProvider;
+    model: string;
+    isLocal: boolean;
+}
+
+/**
+ * Vault Manager for Trading Agents
+ *
+ * Handles vault creation, qualification checking, and vault-aware trading.
+ * Respects the agent's vault policy (disabled, manual, auto_when_qualified).
+ */
+
+interface VaultStatus {
+    hasVault: boolean;
+    vaultAddress: Address | null;
+    totalAssets: bigint;
+    canCreateVault: boolean;
+    cannotCreateReason: string | null;
+    requirementsMet: boolean;
+    requirements: {
+        veXARequired: bigint;
+        burnFee: bigint;
+        isBypassed: boolean;
+    };
+}
+interface VaultManagerConfig {
+    agentId: bigint;
+    agentName: string;
+    network: 'mainnet' | 'testnet';
+    walletKey: `0x${string}`;
+    vaultConfig: VaultConfig;
+}
+/**
+ * Manages vault lifecycle and vault-aware trading for an agent
+ */
+declare class VaultManager {
+    private readonly config;
+    private readonly publicClient;
+    private readonly walletClient;
+    private readonly addresses;
+    private readonly account;
+    private readonly chain;
+    private cachedVaultAddress;
+    private lastVaultCheck;
+    private readonly VAULT_CACHE_TTL;
+    constructor(config: VaultManagerConfig);
+    /**
+     * Get the agent's vault policy
+     */
+    get policy(): VaultPolicy;
+    /**
+     * Check if vault trading is preferred when a vault exists
+     */
+    get preferVaultTrading(): boolean;
+    /**
+     * Get comprehensive vault status
+     */
+    getVaultStatus(): Promise<VaultStatus>;
+    /**
+     * Get vault creation requirements
+     */
+    getRequirements(): Promise<{
+        veXARequired: bigint;
+        burnFee: bigint;
+        isBypassed: boolean;
+    }>;
+    /**
+     * Get the agent's vault address (cached)
+     */
+    getVaultAddress(): Promise<Address | null>;
+    /**
+     * Check if the agent should create a vault based on policy and qualification
+     */
+    shouldCreateVault(): Promise<{
+        should: boolean;
+        reason: string;
+    }>;
+    /**
+     * Create a vault for the agent
+     * @returns Vault address if successful
+     */
+    createVault(): Promise<{
+        success: boolean;
+        vaultAddress?: Address;
+        txHash?: Hash;
+        error?: string;
+    }>;
+    /**
+     * Execute a trade through the vault (if it exists and policy allows)
+     * Returns null if should use direct trading instead
+     */
+    executeVaultTrade(params: {
+        tokenIn: Address;
+        tokenOut: Address;
+        amountIn: bigint;
+        minAmountOut: bigint;
+        aggregator: Address;
+        swapData: `0x${string}`;
+        deadline?: bigint;
+    }): Promise<{
+        usedVault: boolean;
+        txHash?: Hash;
+        error?: string;
+    } | null>;
+    /**
+     * Run the auto-creation check (call this periodically in the agent loop)
+     * Only creates vault if policy is 'auto_when_qualified'
+     */
+    checkAndAutoCreateVault(): Promise<{
+        action: 'created' | 'skipped' | 'already_exists' | 'not_qualified';
+        vaultAddress?: Address;
+        reason: string;
+    }>;
+}
+
+/**
+ * Agent Runtime
+ *
+ * The main runtime class that:
+ * 1. Initializes connection to blockchain
+ * 2. Ensures wallet is linked to agent identity
+ * 3. Loads user's strategy
+ * 4. Runs the trading loop
+ */
+declare class AgentRuntime {
+    private config;
+    private client;
+    private llm;
+    private strategy;
+    private executor;
+    private riskManager;
+    private marketData;
+    private vaultManager;
+    private isRunning;
+    private configHash;
+    private lastVaultCheck;
+    private readonly VAULT_CHECK_INTERVAL;
+    constructor(config: RuntimeConfig);
+    /**
+     * Initialize the agent runtime
+     */
+    initialize(): Promise<void>;
+    /**
+     * Initialize the vault manager based on config
+     */
+    private initializeVaultManager;
+    /**
+     * Ensure the current wallet is linked to the agent
+     */
+    private ensureWalletLinked;
+    /**
+     * Sync the LLM config hash to chain for epoch tracking
+     * This ensures trades are attributed to the correct config epoch
+     */
+    private syncConfigHash;
+    /**
+     * Get the current config hash (for trade execution)
+     */
+    getConfigHash(): `0x${string}`;
+    /**
+     * Start the trading loop
+     */
+    run(): Promise<void>;
+    /**
+     * Run a single trading cycle
+     */
+    private runCycle;
+    /**
+     * Check for vault auto-creation based on policy
+     */
+    private checkVaultAutoCreation;
+    /**
+     * Stop the trading loop
+     */
+    stop(): void;
+    /**
+     * Get RPC URL based on network
+     */
+    private getRpcUrl;
+    /**
+     * Default tokens to track
+     */
+    private getDefaultTokens;
+    private sleep;
+    /**
+     * Get current status
+     */
+    getStatus(): {
+        isRunning: boolean;
+        agentId: number;
+        wallet: string;
+        llm: {
+            provider: string;
+            model: string;
+        };
+        configHash: string;
+        risk: {
+            dailyPnL: number;
+            dailyLossLimit: number;
+            isLimitHit: boolean;
+        };
+        vault: {
+            policy: string;
+            hasVault: boolean;
+            vaultAddress: string | null;
+        };
+    };
+    /**
+     * Get detailed vault status (async)
+     */
+    getVaultStatus(): Promise<VaultStatus | null>;
+    /**
+     * Manually trigger vault creation (for 'manual' policy)
+     */
+    createVault(): Promise<{
+        success: boolean;
+        vaultAddress?: string;
+        error?: string;
+    }>;
+}
+
+/**
+ * Load agent configuration from agent-config.json and .env
+ */
+declare function loadConfig(configPath?: string): RuntimeConfig;
+/**
+ * Validate that all required configuration is present
+ */
+declare function validateConfig(config: RuntimeConfig): void;
+/**
+ * Create a sample config for new users
+ */
+declare function createSampleConfig(agentId: number, name: string): AgentConfig;
+
+/**
+ * Base adapter class with common functionality
+ */
+declare abstract class BaseLLMAdapter implements LLMAdapter {
+    protected config: LLMConfig;
+    constructor(config: LLMConfig);
+    abstract chat(messages: LLMMessage[]): Promise<LLMResponse>;
+    getMetadata(): LLMMetadata;
+    /**
+     * Format model name for display
+     */
+    protected getDisplayModel(): string;
+}
+
+/**
+ * Create an LLM adapter based on configuration
+ */
+declare function createLLMAdapter(config: LLMConfig): Promise<LLMAdapter>;
+
+/**
+ * OpenAI LLM Adapter
+ * Also works with OpenAI-compatible APIs (custom endpoints)
+ */
+declare class OpenAIAdapter extends BaseLLMAdapter {
+    private client;
+    constructor(config: LLMConfig);
+    chat(messages: LLMMessage[]): Promise<LLMResponse>;
+}
+
+/**
+ * Anthropic Claude LLM Adapter
+ */
+declare class AnthropicAdapter extends BaseLLMAdapter {
+    private apiKey;
+    private baseUrl;
+    constructor(config: LLMConfig);
+    chat(messages: LLMMessage[]): Promise<LLMResponse>;
+}
+
+/**
+ * Ollama Local LLM Adapter
+ * Runs models locally without API keys
+ */
+declare class OllamaAdapter extends BaseLLMAdapter {
+    private baseUrl;
+    constructor(config: LLMConfig);
+    /**
+     * Check if Ollama is running and the model is available
+     */
+    healthCheck(): Promise<void>;
+    chat(messages: LLMMessage[]): Promise<LLMResponse>;
+    getMetadata(): LLMMetadata;
+}
+
+/**
+ * Load user's custom strategy from strategy.ts or strategy.js
+ * Falls back to default passthrough if not found
+ */
+declare function loadStrategy(strategyPath?: string): Promise<StrategyFunction>;
+/**
+ * Validate a strategy function has the correct signature
+ */
+declare function validateStrategy(fn: unknown): fn is StrategyFunction;
+
+/**
+ * Boilerplate Strategy Templates
+ *
+ * These are example prompts and strategies users can customize.
+ * Each template includes:
+ * - A system prompt for the LLM
+ * - Risk warnings
+ * - Example implementation
+ *
+ * IMPORTANT: These are starting points. Users should customize
+ * the prompts and logic for their specific needs.
+ */
+interface StrategyTemplate {
+    id: string;
+    name: string;
+    description: string;
+    riskLevel: 'low' | 'medium' | 'high' | 'extreme';
+    riskWarnings: string[];
+    systemPrompt: string;
+    exampleCode: string;
+}
+declare const STRATEGY_TEMPLATES: StrategyTemplate[];
+/**
+ * Get a strategy template by ID
+ */
+declare function getStrategyTemplate(id: string): StrategyTemplate | undefined;
+/**
+ * Get all strategy templates
+ */
+declare function getAllStrategyTemplates(): StrategyTemplate[];
+
+/**
+ * Trade Executor
+ * Handles execution of trade signals through the ExagentRouter
+ */
+declare class TradeExecutor {
+    private client;
+    private config;
+    constructor(client: ExagentClient, config: RuntimeConfig);
+    /**
+     * Execute a single trade signal
+     */
+    execute(signal: TradeSignal): Promise<{
+        success: boolean;
+        txHash?: string;
+        error?: string;
+    }>;
+    /**
+     * Execute multiple trade signals
+     * Returns results for each signal
+     */
+    executeAll(signals: TradeSignal[]): Promise<Array<{
+        signal: TradeSignal;
+        success: boolean;
+        txHash?: string;
+        error?: string;
+    }>>;
+    /**
+     * Validate a signal against config limits
+     */
+    private validateSignal;
+    private delay;
+}
+
+/**
+ * Risk Manager
+ * Applies guardrails to trade signals before execution
+ */
+declare class RiskManager {
+    private config;
+    private dailyPnL;
+    private lastResetDate;
+    constructor(config: TradingConfig);
+    /**
+     * Filter signals through risk checks
+     * Returns only signals that pass all guardrails
+     */
+    filterSignals(signals: TradeSignal[], marketData: MarketData): TradeSignal[];
+    /**
+     * Validate individual signal against risk limits
+     */
+    private validateSignal;
+    /**
+     * Check if daily loss limit has been hit
+     */
+    private isDailyLossLimitHit;
+    /**
+     * Estimate USD value of a trade signal
+     */
+    private estimateSignalValue;
+    /**
+     * Update daily PnL after a trade
+     */
+    updatePnL(pnl: number): void;
+    /**
+     * Get current risk status
+     */
+    getStatus(): {
+        dailyPnL: number;
+        dailyLossLimit: number;
+        isLimitHit: boolean;
+    };
+}
+
+/**
+ * Market Data Service
+ * Fetches prices and portfolio data for strategy analysis
+ */
+declare class MarketDataService {
+    private rpcUrl;
+    constructor(rpcUrl: string);
+    /**
+     * Fetch current market data for the agent
+     */
+    fetchMarketData(walletAddress: string, tokenAddresses: string[]): Promise<MarketData>;
+    /**
+     * Fetch token prices from price oracle
+     */
+    private fetchPrices;
+    /**
+     * Fetch token balances from chain
+     */
+    private fetchBalances;
+    /**
+     * Calculate total portfolio value in USD
+     */
+    private calculatePortfolioValue;
+}
+
+export { type AgentConfig, AgentConfigSchema, AgentRuntime, AnthropicAdapter, BaseLLMAdapter, type LLMAdapter, type LLMConfig, LLMConfigSchema, type LLMMessage, type LLMMetadata, type LLMProvider, LLMProviderSchema, type LLMResponse, type MarketData, MarketDataService, OllamaAdapter, OpenAIAdapter, RiskManager, type RiskUniverse, RiskUniverseSchema, type RuntimeConfig, STRATEGY_TEMPLATES, type StrategyFunction, type StrategyTemplate, TradeExecutor, type TradeSignal, type TradingConfig, TradingConfigSchema, type VaultConfig, VaultConfigSchema, VaultManager, type VaultManagerConfig, type VaultPolicy, VaultPolicySchema, type VaultStatus, createLLMAdapter, createSampleConfig, getAllStrategyTemplates, getStrategyTemplate, loadConfig, loadStrategy, validateConfig, validateStrategy };