@clawnch/clawncher-sdk 0.1.2 → 0.1.3

package/dist/wayfinder.d.ts

@@ -0,0 +1,175 @@
+/**
+ * WayfinderClient - Cross-chain DeFi via Wayfinder Paths
+ *
+ * Two-tier integration:
+ * - Tier 1 (REST): Swap quotes, token resolution, balances, pool data.
+ *   Always available — calls the Wayfinder API directly.
+ * - Tier 2 (CLI bridge): Execute swaps, run strategies, Hyperliquid trading.
+ *   Requires Python 3.12+ and the wayfinder-paths pip package installed locally.
+ *   Shells out to the `wayfinder` CLI for operations that need local tx signing.
+ *
+ * @example
+ * ```typescript
+ * import { WayfinderClient } from '@clawnch/clawncher-sdk';
+ *
+ * const wf = new WayfinderClient({
+ *   apiKey: 'wk_...',
+ * });
+ *
+ * // Tier 1: Get a cross-chain swap quote (no Python needed)
+ * const quote = await wf.quoteSwap({
+ *   fromToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC on Ethereum
+ *   toToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',   // USDC on Base
+ *   fromChain: 1,
+ *   toChain: 8453,
+ *   fromWallet: '0x...',
+ *   amount: '5000000', // 5 USDC in raw units (6 decimals)
+ * });
+ * console.log('Best route:', quote.bestQuote?.provider);
+ *
+ * // Tier 1: Get multi-chain balances
+ * const balances = await wf.getBalances('0x...');
+ * console.log('Total value:', balances.totalValueUsd);
+ *
+ * // Tier 2: Execute a swap (requires Python + wayfinder-paths)
+ * const status = await wf.checkPython();
+ * if (status.wayfinderInstalled) {
+ *   const result = await wf.executeSwap({
+ *     kind: 'swap',
+ *     walletLabel: 'main',
+ *     amount: '5',
+ *     fromToken: 'usd-coin',
+ *     toToken: 'ethereum',
+ *   });
+ *   console.log('Tx:', result.result?.effects);
+ * }
+ * ```
+ */
+import type { WayfinderConfig, PythonStatus, WayfinderTokenDetail, WayfinderTokenSearchResult, WayfinderQuoteParams, WayfinderQuoteResponse, WayfinderBalancesResponse, WayfinderActivityResponse, WayfinderPool, WayfinderFundingEntry, WayfinderCandle, WayfinderHyperLendMarket, WayfinderStrategyInfo, WayfinderStrategyStatus, WayfinderStrategyParams, WayfinderStrategyResult, WayfinderExecuteParams, WayfinderExecuteResult } from './wayfinder-types.js';
+export declare class WayfinderError extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+export declare class WayfinderClient {
+    private readonly apiKey;
+    private readonly apiUrl;
+    private readonly timeout;
+    private readonly pythonPathOverride?;
+    private pythonStatusCache;
+    constructor(config: WayfinderConfig);
+    /**
+     * Check whether Python 3 and wayfinder-paths are available.
+     * Results are cached after the first call.
+     */
+    checkPython(): Promise<PythonStatus>;
+    /**
+     * Clear the cached Python status (e.g. after installing wayfinder-paths).
+     */
+    clearPythonCache(): void;
+    /**
+     * Resolve a token by name, symbol, address, or CoinGecko ID.
+     *
+     * @param query - Token identifier (e.g. "USDC", "0xA0b8...", "usd-coin")
+     * @param chainId - Optional chain ID filter
+     * @param marketData - Include market data (price, market cap)
+     */
+    resolveToken(query: string, chainId?: number, marketData?: boolean): Promise<WayfinderTokenDetail>;
+    /**
+     * Fuzzy search for tokens across chains.
+     *
+     * @param query - Search term
+     * @param chain - Chain code (e.g. "base", "ethereum")
+     */
+    searchTokens(query: string, chain: string): Promise<WayfinderTokenSearchResult[]>;
+    /**
+     * Get the gas token for a chain.
+     *
+     * @param chain - Chain code (e.g. "base", "ethereum")
+     */
+    getGasToken(chain: string): Promise<WayfinderTokenDetail>;
+    /**
+     * Get a cross-chain swap quote via the BRAP aggregator.
+     * Compares routes from multiple providers (LiFi, Squid, etc.)
+     * and returns the best option.
+     *
+     * @param params - Quote parameters (tokens, chains, amount in WEI)
+     */
+    quoteSwap(params: WayfinderQuoteParams): Promise<WayfinderQuoteResponse>;
+    /**
+     * Get enriched multi-chain wallet balances.
+     *
+     * @param walletAddress - Ethereum wallet address
+     * @param excludeSpam - Exclude spam tokens (default: true)
+     */
+    getBalances(walletAddress: string, excludeSpam?: boolean): Promise<WayfinderBalancesResponse>;
+    /**
+     * Get wallet transaction activity.
+     *
+     * @param walletAddress - Ethereum wallet address
+     * @param limit - Max results (default: 20)
+     * @param offset - Pagination offset
+     */
+    getWalletActivity(walletAddress: string, limit?: number, offset?: number): Promise<WayfinderActivityResponse>;
+    /**
+     * Get DeFi pool data (Moonwell, Aave, Morpho, etc.)
+     *
+     * @param chainId - Optional chain ID filter
+     * @param protocol - Optional protocol filter (e.g. "moonwell", "aave")
+     */
+    getPools(chainId?: number, protocol?: string): Promise<WayfinderPool[]>;
+    /**
+     * Get Hyperliquid funding rate history.
+     *
+     * @param coin - Coin symbol (e.g. "BTC", "ETH")
+     * @param startMs - Start timestamp in milliseconds
+     * @param endMs - End timestamp in milliseconds
+     */
+    getHyperliquidFunding(coin: string, startMs?: number, endMs?: number): Promise<WayfinderFundingEntry[]>;
+    /**
+     * Get Hyperliquid OHLCV candle data.
+     *
+     * @param coin - Coin symbol
+     * @param interval - Candle interval (e.g. "1h", "4h", "1d")
+     * @param startMs - Start timestamp in milliseconds
+     * @param endMs - End timestamp in milliseconds
+     */
+    getHyperliquidCandles(coin: string, interval: string, startMs?: number, endMs?: number): Promise<WayfinderCandle[]>;
+    /**
+     * Get HyperLend stable market data.
+     */
+    getHyperLendMarkets(): Promise<WayfinderHyperLendMarket[]>;
+    /**
+     * Execute a swap, send, or Hyperliquid deposit via the Wayfinder CLI.
+     * Signs transactions locally using wallets from wayfinder config.json.
+     *
+     * Requires Python 3.12+ and wayfinder-paths installed.
+     */
+    executeSwap(params: WayfinderExecuteParams): Promise<WayfinderExecuteResult>;
+    /**
+     * Run a Wayfinder strategy action (status, deposit, update, exit, etc.)
+     *
+     * Requires Python 3.12+ and wayfinder-paths installed.
+     */
+    runStrategy(params: WayfinderStrategyParams): Promise<WayfinderStrategyResult>;
+    /**
+     * List available Wayfinder strategies.
+     *
+     * Requires Python 3.12+ and wayfinder-paths installed.
+     */
+    listStrategies(): Promise<WayfinderStrategyInfo[]>;
+    /**
+     * Get the status of a specific strategy.
+     *
+     * Requires Python 3.12+ and wayfinder-paths installed.
+     */
+    getStrategyStatus(name: string): Promise<WayfinderStrategyStatus>;
+    private restRequest;
+    private cliExec;
+    private parseTokenDetail;
+    private parseFuzzySearchResults;
+    private parseBRAPQuoteResponse;
+    private parseBalancesResponse;
+    private parseStrategyList;
+}
+//# sourceMappingURL=wayfinder.d.ts.map

package/dist/wayfinder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wayfinder.d.ts","sourceRoot":"","sources":["../src/wayfinder.ts"],"names":[],"mappings":"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"}