@exagent/sdk 0.1.21 → 0.2.0

package/package.json

@@ -1,37 +1,24 @@
 {
   "name": "@exagent/sdk",
-  "version": "0.1.21",
-  "description": "TypeScript SDK for Exagent",
+  "version": "0.2.0",
+  "type": "module",
   "main": "dist/index.js",
-  "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
+      "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     }
   },
-  "files": [
-    "dist"
-  ],
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "test": "vitest",
-    "lint": "eslint src/",
-    "clean": "rm -rf dist"
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch"
   },
   "dependencies": {
-    "viem": "^2.21.0"
+    "zod": "^3.22.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^2.0.0"
-  },
-  "peerDependencies": {
-    "viem": "^2.0.0"
+    "typescript": "^5.6.0"
   }
 }

package/src/client.ts

@@ -0,0 +1,79 @@
+import type { AgentProfile, TradeSignal } from './types.js';
+
+export interface ExagentClientConfig {
+  baseUrl: string;
+  token: string;
+}
+
+export class ExagentClient {
+  private baseUrl: string;
+  private token: string;
+
+  constructor(config: ExagentClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, '');
+    this.token = config.token;
+  }
+
+  private async request<T>(path: string, options: RequestInit = {}): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const res = await fetch(url, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.token}`,
+        ...options.headers,
+      },
+    });
+
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`API error ${res.status}: ${body}`);
+    }
+
+    return res.json() as Promise<T>;
+  }
+
+  async getMe(): Promise<Record<string, unknown>> {
+    return this.request('/v1/auth/me');
+  }
+
+  async listAgents(): Promise<AgentProfile[]> {
+    return this.request('/v1/agents');
+  }
+
+  async getAgent(agentId: string): Promise<AgentProfile> {
+    return this.request(`/v1/agents/${agentId}`);
+  }
+
+  async createAgent(data: {
+    name: string;
+    description?: string;
+    config: Record<string, unknown>;
+  }): Promise<AgentProfile> {
+    return this.request('/v1/agents', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+  }
+
+  async reportTradeSignal(agentId: string, signal: TradeSignal): Promise<void> {
+    await this.request(`/v1/agents/${agentId}/signals`, {
+      method: 'POST',
+      body: JSON.stringify(signal),
+    });
+  }
+
+  getWebSocketUrl(): string {
+    const wsBase = this.baseUrl
+      .replace(/^http:/, 'ws:')
+      .replace(/^https:/, 'wss:');
+    return `${wsBase}/ws/agent`;
+  }
+
+  getDashboardWebSocketUrl(): string {
+    const wsBase = this.baseUrl
+      .replace(/^http:/, 'ws:')
+      .replace(/^https:/, 'wss:');
+    return `${wsBase}/ws/dashboard`;
+  }
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+export { ExagentClient } from './client.js';
+export type { ExagentClientConfig } from './client.js';
+
+export type {
+  AgentProfile,
+  AgentStatus,
+  AgentConfig,
+  LLMConfig,
+  LLMProvider,
+  LLMMessage,
+  LLMResponse,
+  LLMAdapter,
+  LLMMetadata,
+  StrategyConfig,
+  StrategyContext,
+  StrategyFunction,
+  StrategyStore,
+  StrategyTemplate,
+  TradingConfig,
+  RelayConfig,
+  VenueConfig,
+  TradeSignal,
+  PerpTradeSignal,
+  PredictionTradeSignal,
+  MarketData,
+  OHLCV,
+  TrackedPosition,
+  TradeRecord,
+  PositionSummary,
+  RiskParams,
+  PaperTrade,
+  PaperPortfolio,
+  PaperMetrics,
+  AgentMode,
+  CommandType,
+  MessageType,
+  MessageLevel,
+  RelayCommand,
+  AgentStatusPayload,
+  AgentRelayMessage,
+  HeartbeatMessage,
+  TradeSignalMessage,
+  AgentToAPIMessage,
+  APIToAgentMessage,
+  APIToDashboardMessage,
+} from './types.js';
+
+export { tradeSignalSchema, tradingConfigSchema } from './types.js';

package/src/types.ts

@@ -0,0 +1,468 @@
+import { z } from 'zod';
+
+// ─── Agent Identity ──────────────────────────────────────────────
+
+export interface AgentProfile {
+  id: string;
+  userId: string;
+  name: string;
+  description?: string;
+  status: AgentStatus;
+  config: AgentConfig;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type AgentStatus = 'online' | 'idle' | 'trading' | 'error' | 'offline';
+
+// ─── Agent Configuration ─────────────────────────────────────────
+
+export interface AgentConfig {
+  llm: LLMConfig;
+  strategy: StrategyConfig;
+  trading: TradingConfig;
+  relay: RelayConfig;
+  venues?: VenueConfig;
+}
+
+export interface LLMConfig {
+  provider: LLMProvider;
+  model?: string;
+  apiKey?: string;
+  endpoint?: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export type LLMProvider =
+  | 'openai'
+  | 'anthropic'
+  | 'google'
+  | 'deepseek'
+  | 'mistral'
+  | 'groq'
+  | 'together'
+  | 'ollama';
+
+export interface StrategyConfig {
+  file?: string;
+  template?: string;
+}
+
+export interface TradingConfig {
+  mode: 'live' | 'paper';
+  timeHorizon: 'intraday' | 'swing' | 'position';
+  maxPositionSizeBps: number;
+  maxDailyLossBps: number;
+  maxConcurrentPositions: number;
+  tradingIntervalMs: number;
+  maxSlippageBps: number;
+  minTradeValueUSD: number;
+  initialCapitalUSD?: number;
+}
+
+export interface RelayConfig {
+  url: string;
+  heartbeatIntervalMs?: number;
+  reconnectMaxAttempts?: number;
+}
+
+export interface VenueConfig {
+  hyperliquid?: {
+    enabled: boolean;
+    maxLeverage?: number;
+    maxNotionalUSD?: number;
+  };
+  polymarket?: {
+    enabled: boolean;
+    maxNotionalUSD?: number;
+    maxExposureUSD?: number;
+  };
+  spot?: {
+    enabled: boolean;
+    chains?: string[];
+  };
+}
+
+// ─── Trade Signals ───────────────────────────────────────────────
+
+export interface TradeSignal {
+  venue: string;
+  chain?: string;
+  symbol: string;
+  side: 'long' | 'short' | 'buy' | 'sell';
+  size: number;
+  price: number;
+  fee: number;
+  venueFillId: string;
+  venueTimestamp: string;
+  leverage?: number;
+  orderType?: string;
+  confidence?: number;
+  reasoning?: string;
+}
+
+export interface PerpTradeSignal {
+  action: 'open_long' | 'open_short' | 'close_long' | 'close_short' | 'hold';
+  instrument: string;
+  size: number;
+  price: number;
+  leverage: number;
+  orderType: 'limit' | 'market';
+  reduceOnly: boolean;
+  confidence: number;
+  reasoning?: string;
+}
+
+export interface PredictionTradeSignal {
+  action: 'buy_yes' | 'buy_no' | 'sell_yes' | 'sell_no' | 'hold';
+  marketConditionId: string;
+  marketQuestion: string;
+  outcomeIndex: number;
+  amount: number;
+  limitPrice: number;
+  confidence: number;
+  reasoning?: string;
+}
+
+// ─── LLM Types ───────────────────────────────────────────────────
+
+export interface LLMMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+
+export interface LLMResponse {
+  content: string;
+  tokens?: { input: number; output: number };
+}
+
+export interface LLMAdapter {
+  chat(messages: LLMMessage[]): Promise<LLMResponse>;
+  getMetadata(): LLMMetadata;
+}
+
+export interface LLMMetadata {
+  provider: string;
+  model: string;
+  maxTokens?: number;
+}
+
+// ─── Strategy Types ──────────────────────────────────────────────
+
+export interface StrategyContext {
+  llm: LLMAdapter;
+  market: MarketData;
+  position: PositionSummary;
+  store: StrategyStore;
+  config: TradingConfig;
+  log: (message: string) => void;
+}
+
+export type StrategyFunction = (context: StrategyContext) => Promise<TradeSignal[]>;
+
+export interface StrategyStore {
+  get<T>(key: string): T | undefined;
+  set<T>(key: string, value: T): void;
+  delete(key: string): void;
+  keys(): string[];
+}
+
+export interface StrategyTemplate {
+  id: string;
+  name: string;
+  description: string;
+  category: 'momentum' | 'value' | 'arbitrage' | 'market_making' | 'custom';
+  venues: string[];
+  riskLevel: 'conservative' | 'moderate' | 'aggressive';
+  code: string;
+  systemPrompt: string;
+}
+
+// ─── Market Data ─────────────────────────────────────────────────
+
+export interface MarketData {
+  getPrice(symbol: string): number | undefined;
+  getPrices(): Record<string, number>;
+  getOHLCV(symbol: string, timeframe: string): OHLCV[];
+}
+
+export interface OHLCV {
+  timestamp: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
+}
+
+// ─── Position Tracking ──────────────────────────────────────────
+
+export interface TrackedPosition {
+  token: string;
+  quantity: number;
+  costBasisPerUnit: number;
+  entryTimestamp: number;
+  venue?: string;
+  chain?: string;
+}
+
+export interface TradeRecord {
+  token: string;
+  action: 'buy' | 'sell';
+  quantity: number;
+  price: number;
+  fee: number;
+  timestamp: number;
+  venue?: string;
+  chain?: string;
+  venueFillId?: string;
+}
+
+export interface PositionSummary {
+  openPositions: TrackedPosition[];
+  totalUnrealizedPnL: number;
+  totalRealizedPnL: number;
+}
+
+// ─── Risk ────────────────────────────────────────────────────────
+
+export interface RiskParams {
+  maxPositionSizeBps: number;
+  maxDailyLossBps: number;
+  maxConcurrentPositions: number;
+  maxSlippageBps: number;
+  minTradeValueUSD: number;
+  confidenceThreshold?: number;
+}
+
+// ─── Paper Trading ───────────────────────────────────────────────
+
+export interface PaperTrade {
+  id: string;
+  symbol: string;
+  side: 'buy' | 'sell';
+  size: number;
+  entryPrice: number;
+  exitPrice?: number;
+  fee: number;
+  pnl?: number;
+  timestamp: number;
+  venue: string;
+}
+
+export interface PaperPortfolio {
+  cash: number;
+  positions: Map<string, { quantity: number; avgPrice: number }>;
+  equity: number;
+  trades: PaperTrade[];
+  equityCurve: { timestamp: number; equity: number }[];
+}
+
+export interface PaperMetrics {
+  totalReturn: number;
+  sharpeRatio: number;
+  maxDrawdown: number;
+  winRate: number;
+  profitFactor: number;
+  totalTrades: number;
+}
+
+// ─── Relay Protocol ──────────────────────────────────────────────
+
+export type AgentMode = 'idle' | 'trading' | 'paper' | 'paused';
+
+export type CommandType =
+  | 'start_trading'
+  | 'stop_trading'
+  | 'pause_trading'
+  | 'update_risk_params'
+  | 'update_strategy'
+  | 'reload_config'
+  | 'get_status'
+  | 'close_all_positions'
+  | 'shutdown';
+
+export type MessageType =
+  | 'trade_executed'
+  | 'perp_fill'
+  | 'prediction_fill'
+  | 'spot_fill'
+  | 'bridge_fill'
+  | 'strategy_decision'
+  | 'risk_blocked'
+  | 'error'
+  | 'info'
+  | 'funds_low'
+  | 'daily_limit_hit'
+  | 'started'
+  | 'stopped';
+
+export type MessageLevel = 'info' | 'warning' | 'error' | 'success';
+
+export interface RelayCommand {
+  id: string;
+  type: CommandType;
+  params?: Record<string, unknown>;
+}
+
+export interface AgentStatusPayload {
+  mode: AgentMode;
+  agentId: string;
+  walletAddress?: string;
+  sdkVersion?: string;
+  cycleCount?: number;
+  lastCycleAt?: number;
+  tradingIntervalMs?: number;
+  portfolioValue?: number;
+  llm?: {
+    provider: string;
+    model: string;
+    dailyTokens?: number;
+    totalTokens?: number;
+    dailyCalls?: number;
+    totalCalls?: number;
+    dailyBudgetExceeded?: boolean;
+  };
+  risk?: {
+    dailyPnL: number;
+    dailyLossLimit: number;
+    isLimitHit: boolean;
+  };
+  positions?: {
+    openPositions: number;
+    totalUnrealizedPnL: number;
+    totalRealizedPnL: number;
+  };
+  paper?: {
+    active: boolean;
+    simulatedValue: number;
+    simulatedPnLPct: number;
+  };
+  venues?: {
+    hyperliquid?: { enabled: boolean; trading: boolean };
+    polymarket?: { enabled: boolean; trading: boolean };
+    spot?: { enabled: boolean; trading: boolean };
+    bridge?: { enabled: boolean };
+  };
+  diagnostics?: {
+    uptime?: number;
+    uptimeHuman?: string;
+    memoryMB?: number;
+    cycleStats?: {
+      total: number;
+      succeeded: number;
+      failed: number;
+      successRate: number;
+      avgCycleMs: number;
+      lastCycleMs: number;
+    };
+    lastCycleTimings?: {
+      totalMs: number;
+      priceRefreshMs: number;
+      strategyMs: number;
+      riskFilterMs: number;
+      executionMs: number;
+    };
+    errorCounts?: Record<string, number>;
+    recentErrors?: Array<{ category: string; message: string; timestamp: number }>;
+    llmStats?: {
+      totalCalls: number;
+      avgLatencyMs: number;
+      errorRate: number;
+      recentCalls: number;
+    };
+    signalQueue?: {
+      pending: number;
+      flushedTotal: number;
+    };
+  };
+}
+
+export interface AgentRelayMessage {
+  type: 'message';
+  agentId: string;
+  messageType: MessageType;
+  level: MessageLevel;
+  title: string;
+  body: string;
+  data?: Record<string, unknown>;
+  timestamp: number;
+}
+
+export interface HeartbeatMessage {
+  type: 'heartbeat';
+  agentId: string;
+  status: AgentStatusPayload;
+  timestamp: number;
+}
+
+export interface TradeSignalMessage {
+  type: 'trade_signal';
+  agentId: string;
+  signal: TradeSignal;
+  timestamp: number;
+}
+
+export interface CommandAckMessage {
+  type: 'command_ack';
+  agentId: string;
+  commandId: string;
+  success: boolean;
+  message?: string;
+  timestamp: number;
+}
+
+// WebSocket message union (agent → API)
+export type AgentToAPIMessage =
+  | { type: 'auth'; agentId: string; token: string }
+  | HeartbeatMessage
+  | AgentRelayMessage
+  | TradeSignalMessage
+  | CommandAckMessage;
+
+// WebSocket message union (API → agent)
+export type APIToAgentMessage =
+  | { type: 'auth_success'; agentId: string }
+  | { type: 'auth_error'; error: string }
+  | { type: 'command'; command: RelayCommand }
+  | { type: 'pong' };
+
+// WebSocket message union (API → dashboard)
+export type APIToDashboardMessage =
+  | { type: 'agent_status'; agentId: string; status: AgentStatusPayload }
+  | { type: 'agent_message'; message: AgentRelayMessage }
+  | { type: 'agent_connected'; agentId: string }
+  | { type: 'agent_disconnected'; agentId: string }
+  | { type: 'trade_signal'; agentId: string; signal: TradeSignal }
+  | { type: 'command_ack'; agentId: string; commandId: string; success: boolean; message?: string };
+
+// ─── Validation Schemas ──────────────────────────────────────────
+
+export const tradeSignalSchema = z.object({
+  venue: z.string(),
+  chain: z.string().optional(),
+  symbol: z.string(),
+  side: z.enum(['long', 'short', 'buy', 'sell']),
+  size: z.number().positive(),
+  price: z.number().positive(),
+  fee: z.number().min(0),
+  venueFillId: z.string(),
+  venueTimestamp: z.string(),
+  leverage: z.number().optional(),
+  orderType: z.string().optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  reasoning: z.string().optional(),
+});
+
+export const tradingConfigSchema = z.object({
+  mode: z.enum(['live', 'paper']).default('paper'),
+  timeHorizon: z.enum(['intraday', 'swing', 'position']).default('swing'),
+  maxPositionSizeBps: z.number().min(100).max(10000).default(2000),
+  maxDailyLossBps: z.number().min(0).max(10000).default(500),
+  maxConcurrentPositions: z.number().min(1).max(100).default(5),
+  tradingIntervalMs: z.number().min(1000).default(60000),
+  maxSlippageBps: z.number().min(10).max(1000).default(100),
+  minTradeValueUSD: z.number().min(0).default(10),
+  initialCapitalUSD: z.number().optional(),
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}