@vesper85/strategy-sdk 0.1.0

package/dist/types/osiris.d.ts

@@ -0,0 +1,414 @@
+import type { OHLCV, TAParams } from "@vesper85/technical-indicators";
+import type { GammaMarket, Event as GammaEvent, Tag, Team, Sport, Series, Comment as GammaComment, SearchResults, PaginatedResponse, MarketFilters, EventFilters, EventPaginationFilters, PaginationParams, SearchParams } from "polymarket-gamma";
+import type { ClearinghouseState, SpotMeta, SpotClearinghouseState, SpotMetaAndAssetCtxs, Meta, MetaAndAssetCtxs, UserFunding, UserNonFundingLedgerUpdates, FundingHistory, PredictedFundings, PerpsAtOpenInterestCap, PerpDexLimits, AllMids, UserOpenOrders, FrontendOpenOrders, UserFills, UserRateLimit, OrderStatus, L2Book, CandleSnapshot, HistoricalOrder, TwapSliceFill, SubAccount, VaultDetails, VaultEquity, UserRole, Delegation, DelegatorSummary, DelegatorHistoryEntry, DelegatorReward, ValidatorSummary, VaultSummary, UserFees, PortfolioPeriods, PreTransferCheck, Referral, ExtraAgent, LegalCheck, TwapHistory, MultiSigSigners, BuilderFeeApproval, UserOrderHistory } from "hyperliquid";
+export interface OsirisState {
+    get(key: string): Promise<any>;
+    set(key: string, value: any): Promise<void>;
+}
+/**
+ * Order side for Polymarket trades
+ */
+export type PolymarketOrderSide = 'BUY' | 'SELL';
+/**
+ * Parameters for creating a limit order
+ */
+export interface PolymarketLimitOrderParams {
+    /** Token ID of the outcome token */
+    tokenId: string;
+    /** Price per share (0-1 range) */
+    price: number;
+    /** Order side */
+    side: PolymarketOrderSide;
+    /** Number of shares */
+    size: number;
+    /** Fee rate in basis points (optional, default 0) */
+    feeRateBps?: string;
+    /** Time in force (optional) */
+    expiration?: number;
+}
+/**
+ * Parameters for creating a market order
+ */
+export interface PolymarketMarketOrderParams {
+    /** Token ID of the outcome token */
+    tokenId: string;
+    /** Amount in USDC to spend (for BUY) or shares to sell (for SELL) */
+    amount: number;
+    /** Order side */
+    side: PolymarketOrderSide;
+    /** Slippage tolerance as a decimal (e.g., 0.05 for 5%) */
+    slippageTolerance?: number;
+}
+/**
+ * Response from order operations
+ */
+export interface PolymarketOrderResponse {
+    success: boolean;
+    /** Order ID if successful */
+    orderId?: string;
+    /** Transaction hash if applicable */
+    transactionHash?: string;
+    /** Error message if failed */
+    errorMsg?: string;
+}
+/**
+ * Open order information
+ */
+export interface PolymarketOpenOrder {
+    id: string;
+    market: string;
+    asset_id: string;
+    side: string;
+    original_size: string;
+    size_matched: string;
+    price: string;
+    outcome: string;
+    owner: string;
+    timestamp: number;
+    expiration: number;
+    order_type: string;
+}
+/**
+ * Response from cancel operations
+ */
+export interface PolymarketCancelResponse {
+    /** Successfully canceled order IDs */
+    canceled: string[];
+    /** Orders that couldn't be canceled with reasons */
+    not_canceled: Record<string, string>;
+}
+/**
+ * Order book entry
+ */
+export interface PolymarketOrderBookEntry {
+    price: string;
+    size: string;
+}
+/**
+ * Order book structure
+ */
+export interface PolymarketOrderBook {
+    market: string;
+    asset_id: string;
+    bids: PolymarketOrderBookEntry[];
+    asks: PolymarketOrderBookEntry[];
+    hash: string;
+    timestamp: string;
+}
+/**
+ * Result from setting up approvals
+ */
+export interface PolymarketApprovalResult {
+    /** USDC approval transaction hash (if approval was needed) */
+    usdcApprovalTx?: string;
+    /** CTF approval transaction hash (if approval was needed) */
+    ctfApprovalTx?: string;
+    /** Whether USDC was already approved */
+    usdcWasAlreadyApproved: boolean;
+    /** Whether CTF was already approved */
+    ctfWasAlreadyApproved: boolean;
+}
+/**
+ * Options for Polymarket client
+ *
+ * When using OsirisSigner, orders are placed via MCP tools which require
+ * MCP-specific authentication tokens (separate from backend OAuth tokens).
+ */
+export interface PolymarketClientOptions {
+    /** Chain ID (default: 137 for Polygon mainnet) */
+    chainId?: number;
+    /** Auto-approve tokens before trades (default: false) */
+    autoApprove?: boolean;
+    /** CLOB API host (default: https://clob.polymarket.com) */
+    clobHost?: string;
+    /**
+     * MCP server URL for order placement via MCP tools
+     * Default: https://gateway.backend.osirislabs.xyz/@osiris/polymarket/mcp
+     */
+    mcpUrl?: string;
+    /**
+     * MCP OAuth access token for authenticated MCP calls.
+     * IMPORTANT: This must be an MCP-specific token obtained through the Osiris Hub
+     * OAuth flow for MCP packages (via /hub/authorize endpoint with MCP scopes).
+     * This is NOT the same as the general backend access token.
+     * Required scopes: osiris:auth, osiris:auth:action
+     */
+    mcpAccessToken?: string;
+    /**
+     * Flag to explicitly enable MCP mode for order placement.
+     * When true, orders are placed via MCP tools instead of direct CLOB client.
+     * Auto-detected based on signer type if not provided (enabled for OsirisSigner).
+     */
+    useMcpForOrders?: boolean;
+}
+/**
+ * Technical Analysis API
+ * Provides methods for calculating technical indicators
+ */
+export interface TechnicalAnalysisAPI {
+    calculate(indicator: string, data: OHLCV[], params?: TAParams & {
+        component?: string;
+    }): number | number[];
+}
+/**
+ * Polymarket-specific API
+ * Combines data, account, and execution methods for Polymarket markets
+ */
+export interface PolymarketAPI {
+    getPrice(ticker: string): Promise<number>;
+    getIndicator(ticker: string, indicator: string, params?: any): Promise<number>;
+    search(params: SearchParams): Promise<SearchResults>;
+    getMarket(idOrSlug: string): Promise<GammaMarket>;
+    getMarkets(filters?: MarketFilters & {
+        end_date_min?: string;
+        end_date_max?: string;
+        start_date_min?: string;
+        start_date_max?: string;
+        liquidity_num_min?: number;
+        liquidity_num_max?: number;
+        volume_num_min?: number;
+        volume_num_max?: number;
+        limit?: number;
+        offset?: number;
+        order?: string;
+        ascending?: boolean;
+        closed?: boolean;
+    }): Promise<GammaMarket[]>;
+    getMarketTags(marketId: string): Promise<Tag[]>;
+    getEvent(idOrSlug: string): Promise<GammaEvent>;
+    getEvents(filters?: EventFilters): Promise<GammaEvent[]>;
+    getEventTags(eventId: string): Promise<Tag[]>;
+    getEventsPaginated(filters?: EventPaginationFilters): Promise<PaginatedResponse<GammaEvent>>;
+    getTags(params?: PaginationParams): Promise<Tag[]>;
+    getTag(idOrSlug: string): Promise<Tag>;
+    getRelatedTags(idOrSlug: string): Promise<Tag[]>;
+    getRelatedTagsTags(idOrSlug: string): Promise<Tag[]>;
+    getTeams(params?: PaginationParams): Promise<Team[]>;
+    getSports(params?: PaginationParams): Promise<Sport[]>;
+    getSeries(params?: PaginationParams): Promise<Series[]>;
+    getSeriesById(seriesId: string): Promise<Series>;
+    getComments(params?: PaginationParams): Promise<GammaComment[]>;
+    getComment(commentId: string): Promise<GammaComment>;
+    getCommentsByUser(userAddress: string, params?: PaginationParams): Promise<GammaComment[]>;
+    getPositions(user: string, params?: any): Promise<any[]>;
+    getTrades(user: string, params?: any): Promise<any[]>;
+    getActivity(user: string, params?: any): Promise<any[]>;
+    getTopHolders(marketId: string): Promise<any[]>;
+    getPortfolioValue(user: string): Promise<number>;
+    getClosedPositions(user: string, params?: any): Promise<any[]>;
+    getTradedMarketsCount(user: string): Promise<number>;
+    getOpenInterest(marketId: string): Promise<number>;
+    getPosition(ticker: string): Promise<any | null>;
+    /**
+     * Initialize the CLOB trading client
+     * This generates API credentials and sets up the client for trading
+     * Must be called before placing orders
+     */
+    initializeTradingClient(): Promise<void>;
+    /**
+     * Check if the trading client is initialized
+     */
+    isTradingClientInitialized(): boolean;
+    /**
+     * Get current USDC allowance for the CTF Exchange contract
+     * @returns Current allowance in wei (as bigint)
+     */
+    getUsdcAllowance(): Promise<bigint>;
+    /**
+     * Approve USDC spending for the CTF Exchange contract
+     * @param amount Amount to approve in wei (defaults to max uint256)
+     * @returns Transaction hash
+     */
+    approveUsdc(amount?: bigint): Promise<string>;
+    /**
+     * Check if CTF (Conditional Tokens) are approved for the CTF Exchange
+     * @returns True if approved for all
+     */
+    isCtfApprovedForAll(): Promise<boolean>;
+    /**
+     * Approve CTF (Conditional Tokens) for the CTF Exchange contract
+     * @returns Transaction hash
+     */
+    approveCtf(): Promise<string>;
+    /**
+     * Set up all required approvals for trading
+     * @param options Approval options
+     * @returns Result containing transaction hashes
+     */
+    setupApprovals(options?: {
+        usdcAmount?: bigint;
+    }): Promise<PolymarketApprovalResult>;
+    /**
+     * Create and post a limit order
+     * @param params Order parameters
+     * @returns Order response
+     */
+    createLimitOrder(params: PolymarketLimitOrderParams): Promise<PolymarketOrderResponse>;
+    /**
+     * Create and post a market order (executes immediately at best price)
+     * @param params Order parameters
+     * @returns Order response
+     */
+    createMarketOrder(params: PolymarketMarketOrderParams): Promise<PolymarketOrderResponse>;
+    /**
+     * Get all open orders for the user
+     * @returns Array of open orders
+     */
+    getOpenOrders(): Promise<PolymarketOpenOrder[]>;
+    /**
+     * Cancel a specific order
+     * @param orderId Order ID to cancel
+     * @returns Cancel response
+     */
+    cancelOrder(orderId: string): Promise<PolymarketCancelResponse>;
+    /**
+     * Cancel multiple orders
+     * @param orderIds Array of order IDs to cancel
+     * @returns Cancel response
+     */
+    cancelOrders(orderIds: string[]): Promise<PolymarketCancelResponse>;
+    /**
+     * Cancel all open orders
+     * @returns Cancel response
+     */
+    cancelAllOrders(): Promise<PolymarketCancelResponse>;
+    /**
+     * Get the order book for a specific token
+     * @param tokenId Token ID
+     * @returns Order book data
+     */
+    getOrderBook(tokenId: string): Promise<PolymarketOrderBook>;
+    /**
+     * Place a limit buy order
+     * @param tokenId Token ID of the outcome
+     * @param price Price per share (0-1 range)
+     * @param size Number of shares to buy
+     * @returns Order response
+     */
+    buyLimit(tokenId: string, price: number, size: number): Promise<PolymarketOrderResponse>;
+    /**
+     * Place a limit sell order
+     * @param tokenId Token ID of the outcome
+     * @param price Price per share (0-1 range)
+     * @param size Number of shares to sell
+     * @returns Order response
+     */
+    sellLimit(tokenId: string, price: number, size: number): Promise<PolymarketOrderResponse>;
+    /**
+     * Place a market buy order (executes immediately at best price)
+     * @param tokenId Token ID of the outcome
+     * @param amount Amount in USDC to spend
+     * @param slippage Slippage tolerance as decimal (e.g., 0.05 for 5%). Default: 0.05
+     * @returns Order response
+     */
+    buyMarket(tokenId: string, amount: number, slippage?: number): Promise<PolymarketOrderResponse>;
+    /**
+     * Place a market sell order (executes immediately at best price)
+     * @param tokenId Token ID of the outcome
+     * @param size Number of shares to sell
+     * @param slippage Slippage tolerance as decimal (e.g., 0.05 for 5%). Default: 0.05
+     * @returns Order response
+     */
+    sellMarket(tokenId: string, size: number, slippage?: number): Promise<PolymarketOrderResponse>;
+    /**
+     * Buy shares of an outcome token (uses market order)
+     * @param tokenId Token ID of the outcome
+     * @param size Amount in USDC to spend
+     * @deprecated Use buyMarket() instead
+     */
+    buy(tokenId: string, size: number): Promise<void>;
+    /**
+     * Sell shares of an outcome token (uses market order)
+     * @param tokenId Token ID of the outcome
+     * @param size Number of shares to sell
+     * @deprecated Use sellMarket() instead
+     */
+    sell(tokenId: string, size: number): Promise<void>;
+}
+/**
+ * Hyperliquid-specific API
+ * Combines data, account, and execution methods for Hyperliquid markets
+ */
+export interface HyperliquidAPI {
+    getPrice(ticker: string): Promise<number>;
+    getIndicator(ticker: string, indicator: string, params?: any): Promise<number>;
+    getSpotMeta(): Promise<SpotMeta>;
+    getSpotClearinghouseState(user: string): Promise<SpotClearinghouseState>;
+    getSpotMetaAndAssetCtxs(): Promise<SpotMetaAndAssetCtxs>;
+    getTokenDetails(tokenId: string): Promise<any>;
+    getSpotDeployState(user: string): Promise<any>;
+    getMeta(): Promise<Meta>;
+    getMetaAndAssetCtxs(): Promise<MetaAndAssetCtxs>;
+    getClearinghouseState(user: string): Promise<ClearinghouseState>;
+    getUserFunding(user: string, startTime: number, endTime?: number): Promise<UserFunding>;
+    getUserNonFundingLedgerUpdates(user: string, startTime: number, endTime?: number): Promise<UserNonFundingLedgerUpdates>;
+    getFundingHistory(coin: string, startTime: number, endTime?: number): Promise<FundingHistory>;
+    getPredictedFundings(): Promise<PredictedFundings>;
+    getPerpsAtOpenInterestCap(): Promise<PerpsAtOpenInterestCap>;
+    getPerpDexLimits(dex: string): Promise<PerpDexLimits>;
+    getAssetIndex(assetName: string): Promise<number | undefined>;
+    getInternalName(exchangeName: string): Promise<string | undefined>;
+    getAllAssets(): Promise<{
+        perp: string[];
+        spot: string[];
+    }>;
+    getAllMids(): Promise<AllMids>;
+    getUserOpenOrders(user: string): Promise<UserOpenOrders>;
+    getFrontendOpenOrders(user: string): Promise<FrontendOpenOrders>;
+    getUserFills(user: string): Promise<UserFills>;
+    getUserFillsByTime(user: string, startTime: number, endTime: number): Promise<UserFills>;
+    getUserRateLimit(user: string): Promise<UserRateLimit>;
+    getOrderStatus(user: string, oid: number | string): Promise<OrderStatus>;
+    getL2Book(coin: string): Promise<L2Book>;
+    getCandleSnapshot(coin: string, interval: string, startTime: number, endTime: number): Promise<CandleSnapshot>;
+    getMaxBuilderFee(user: string, builder: string): Promise<number>;
+    getHistoricalOrders(user: string): Promise<HistoricalOrder[]>;
+    getUserTwapSliceFills(user: string): Promise<TwapSliceFill[]>;
+    getSubAccounts(user: string): Promise<SubAccount[]>;
+    getVaultDetails(vaultAddress: string, user?: string): Promise<VaultDetails>;
+    getUserVaultEquities(user: string): Promise<VaultEquity[]>;
+    getUserRole(user: string): Promise<UserRole>;
+    getDelegations(user: string): Promise<Delegation[]>;
+    getDelegatorSummary(user: string): Promise<DelegatorSummary>;
+    getDelegatorHistory(user: string): Promise<DelegatorHistoryEntry[]>;
+    getDelegatorRewards(user: string): Promise<DelegatorReward[]>;
+    validatorSummaries(): Promise<ValidatorSummary[]>;
+    vaultSummaries(): Promise<VaultSummary[]>;
+    userFees(user: string): Promise<UserFees>;
+    portfolio(user: string): Promise<PortfolioPeriods>;
+    preTransferCheck(user: string, source: string): Promise<PreTransferCheck>;
+    referral(user: string): Promise<Referral>;
+    extraAgents(user: string): Promise<ExtraAgent[]>;
+    isVip(user: string): Promise<boolean>;
+    legalCheck(user: string): Promise<LegalCheck>;
+    userTwapSliceFillsByTime(user: string, startTime: number, endTime?: number): Promise<TwapSliceFill[]>;
+    twapHistory(user: string): Promise<TwapHistory[]>;
+    userToMultiSigSigners(user: string): Promise<MultiSigSigners | null>;
+    getBuilderFeeApproval(user: string, builderAddress: string): Promise<BuilderFeeApproval>;
+    getUserOrderHistory(user: string, startTime: number, endTime?: number): Promise<UserOrderHistory>;
+    getPosition(ticker: string): Promise<ClearinghouseState['assetPositions'][0] | null>;
+    getPositions(): Promise<ClearinghouseState['assetPositions']>;
+}
+/**
+ * Signer interface for transaction signing
+ */
+export interface SignerAPI {
+    signTransaction(transaction: string | any, chain: string, walletAddress: string): Promise<string>;
+    signTypedData(typedData: any, chain: string, walletAddress: string): Promise<string>;
+    signMessage(message: string | Uint8Array, chain: string, walletAddress: string): Promise<string>;
+    getAddress(): string | undefined;
+    getPrivateKey(): string | undefined;
+}
+/**
+ * Osiris Context
+ * Provides market-specific APIs based on the strategy's configured market
+ */
+export interface OsirisContext {
+    polymarket?: PolymarketAPI;
+    hyperliquid?: HyperliquidAPI;
+    ta: TechnicalAnalysisAPI;
+    state: OsirisState;
+    signer: SignerAPI;
+    log: (message: string, meta?: any) => void;
+}
+//# sourceMappingURL=osiris.d.ts.map

package/dist/types/strategy.d.ts

@@ -0,0 +1,35 @@
+import type { OsirisContext } from "./osiris";
+import type { EventSubscription, StrategyEvent } from "./event-types";
+/**
+ * Strategy interface supporting both tick-based and event-based execution
+ *
+ * Tick-based strategies: Implement shouldTrigger() and onTrigger()
+ * Event-based strategies: Implement subscriptions[] and onEvent()
+ *
+ * These modes are mutually exclusive - a strategy should use one or the other.
+ */
+export interface CodeStrategy {
+    /**
+     * Called on each tick to determine if the strategy should execute
+     * @returns true if onTrigger should be called
+     */
+    shouldTrigger?(osiris: OsirisContext): Promise<boolean>;
+    /**
+     * Called when shouldTrigger returns true
+     * Contains the main strategy logic for tick-based execution
+     */
+    onTrigger?(osiris: OsirisContext): Promise<void>;
+    /**
+     * List of events this strategy wants to subscribe to
+     * The EventRunner will subscribe to these events on the WebSocket connection
+     */
+    subscriptions?: EventSubscription[];
+    /**
+     * Called when a subscribed event is received
+     * Contains the main strategy logic for event-based execution
+     * @param event The event that triggered this call
+     * @param osiris The context with market APIs and utilities
+     */
+    onEvent?(event: StrategyEvent, osiris: OsirisContext): Promise<void>;
+}
+//# sourceMappingURL=strategy.d.ts.map

package/dist/utils/logger.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Simple logger interface for the SDK
+ * Users can provide their own logger implementation or use the console logger
+ */
+export interface Logger {
+    info(message: string, meta?: any): void;
+    error(message: string, error?: any): void;
+    warning(message: string, meta?: any): void;
+    debug(message: string, meta?: any): void;
+}
+/**
+ * Creates a simple console logger that matches the Logger interface
+ */
+export declare function createConsoleLogger(): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@vesper85/strategy-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "SDK for writing and running trading strategies with Polymarket and Hyperliquid integrations",
+  "keywords": [
+    "trading",
+    "strategy",
+    "polymarket",
+    "hyperliquid",
+    "trading-bot",
+    "osiris"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "!**/*.map"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup && npm run types",
+    "types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "build:watch": "tsup --watch",
+    "dev": "tsup --watch",
+    "lint": "eslint \"src/**/*.ts*\"",
+    "lint:fix": "eslint \"src/**/*.ts*\" --fix",
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "npm run build && changeset publish"
+  },
+  "dependencies": {
+    "@vesper85/technical-indicators": "^0.1.0",
+    "@polymarket/clob-client": "^4.6.0",
+    "axios": "^1.7.9",
+    "ethers": "^6.13.4",
+    "hyperliquid": "^1.7.7",
+    "polymarket-gamma": "^0.4.0",
+    "redis": "^4.7.0",
+    "superjson": "^2.2.6",
+    "viem": "^2.30.1"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@osiris-ai/eslint-config": "workspace:*",
+    "@osiris-ai/typescript-config": "workspace:*",
+    "@types/node": "^22.10.1",
+    "eslint": "^8.37.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FetcchX/legion-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FetcchX/legion-sdk/issues"
+  },
+  "homepage": "https://github.com/FetcchX/legion-sdk#readme"
+}