@clawnch/clawncher-sdk 0.1.3 → 0.3.0

package/README.md

@@ -319,6 +319,174 @@ import {
 } from '@clawnch/clawncher-sdk';
 ```
 
+## Uniswap V4 Trading API
+
+Execute swaps via the Uniswap Trading API with automatic Permit2 approval handling. Supports all 15 Uniswap chains.
+
+```typescript
+import { UniswapTradingApi } from '@clawnch/clawncher-sdk';
+
+const trading = new UniswapTradingApi({
+  wallet,
+  publicClient,
+  chainId: 8453,
+  apiKey: process.env.UNISWAP_API_KEY,
+  slippageBps: 50, // 0.5%
+});
+
+// Full swap: check_approval → quote → swap (handles Permit2 automatically)
+const result = await trading.swap({
+  tokenIn: NATIVE_TOKEN_ADDRESS,
+  tokenOut: '0xTokenAddress...',
+  amount: parseEther('0.01'),
+});
+console.log('Tx:', result.txHash);
+
+// Quote only (no execution)
+const quote = await trading.getQuote({
+  tokenIn: NATIVE_TOKEN_ADDRESS,
+  tokenOut: '0xTokenAddress...',
+  amount: parseEther('0.01'),
+});
+console.log('Output:', quote.quoteAmount, 'Impact:', quote.priceImpact);
+
+// Generate Uniswap app deep link
+const link = trading.getSwapDeepLink({
+  tokenIn: NATIVE_TOKEN_ADDRESS,
+  tokenOut: '0xTokenAddress...',
+  amount: parseEther('0.1'),
+});
+```
+
+The Trading API uses a 3-step flow: `POST /check_approval` → `POST /quote` → `POST /swap`. The `swap()` method handles all three steps including Permit2 approvals. Sign up for an API key at [hub.uniswap.org](https://hub.uniswap.org).
+
+## On-Chain V4 Quoter
+
+Simulate swaps directly against V4 pools without an API key. Includes Clawnch-native pool discovery via the LP locker contract.
+
+```typescript
+import { UniswapQuoter } from '@clawnch/clawncher-sdk';
+
+const quoter = new UniswapQuoter({
+  publicClient,
+  chainId: 8453,
+});
+
+// One-call quote for any Clawnch token (auto-discovers pool key from LP locker)
+const quote = await quoter.quoteClawnchToken(
+  '0xTokenAddress...',
+  parseEther('0.01'),
+  'buy', // 'buy' = ETH→Token, 'sell' = Token→ETH
+);
+console.log('Output:', quote.quotedAmount);
+console.log('Impact:', quote.priceImpact);
+console.log('Hook:', quote.poolKey.hooks); // correct MEV hook, not zero address
+
+// Build pool key from LP locker (includes hook address, fee, tick spacing)
+const poolKey = await quoter.buildPoolKeyFromToken('0xTokenAddress...');
+
+// Read pool state (sqrtPriceX96, tick, liquidity)
+const state = await quoter.getPoolState(poolKey);
+
+// Manual quote with explicit pool key
+const manualQuote = await quoter.quoteExactInput({
+  poolKey,
+  zeroForOne: true,
+  amount: parseEther('0.01'),
+});
+
+// Estimate price impact without a full quote
+const impact = await quoter.estimatePriceImpact(poolKey, parseEther('1'));
+```
+
+`buildPoolKeyFromToken()` reads the LP locker via `ClawnchReader.getTokenRewards()` to auto-discover the correct pool key — including the MEV hook address. This is critical because defaulting the hook to the zero address targets the wrong pool for Clawnch tokens.
+
+## Permit2 Client
+
+Manage token approvals for Uniswap V4 via the Permit2 contract. Supports both AllowanceTransfer (PositionManager) and SignatureTransfer (UniversalRouter).
+
+```typescript
+import { Permit2Client, PERMIT2_ADDRESS } from '@clawnch/clawncher-sdk';
+
+const permit2 = new Permit2Client({
+  wallet,
+  publicClient,
+  chainId: 8453,
+});
+
+// Full approval flow: ERC20→Permit2 + Permit2→spender
+const { approvalTxHash, permitTxHash } = await permit2.ensurePermit2Allowance(
+  tokenAddress,
+  spenderAddress, // e.g. UniversalRouter
+  amount,
+);
+
+// Two-token approval for LP operations
+await permit2.ensurePermit2AllowancePair(
+  token0, token1, positionManagerAddress, amount0, amount1,
+);
+
+// Check allowance state
+const allowance = await permit2.getAllowance(tokenAddress, spenderAddress);
+console.log('Amount:', allowance.amount, 'Expires:', allowance.expiration);
+
+// Emergency lockdown — revoke all access
+await permit2.lockdown([
+  { token: tokenA, spender: routerAddress },
+  { token: tokenB, spender: routerAddress },
+]);
+
+// Sign off-chain permits (AllowanceTransfer)
+const signed = await permit2.signPermitSingle({
+  token: tokenAddress,
+  spender: routerAddress,
+});
+
+// Sign off-chain permits (SignatureTransfer — bitmap nonces)
+const nonce = await permit2.findUnusedNonce(0n);
+const transfer = await permit2.signPermitTransferFrom({
+  token: tokenAddress,
+  amount: parseEther('1'),
+  spender: routerAddress,
+  nonce,
+});
+```
+
+Permit2 is deployed at `0x000000000022D473030F116dDEE9F6B43aC78BA3` on all chains.
+
+## Multi-Chain Uniswap Registry
+
+Address registry for all 15 Uniswap-supported chains.
+
+```typescript
+import {
+  getUniswapChain,
+  getAllUniswapChains,
+  getTradingApiChains,
+  getV4Chains,
+  chainIdFromSlug,
+  FEE_TIERS,
+} from '@clawnch/clawncher-sdk';
+
+// Get config for a specific chain
+const base = getUniswapChain(8453);
+console.log(base.v4UniversalRouter, base.weth, base.permit2);
+
+// All chains with Trading API support
+const tradingChains = getTradingApiChains(); // 15 chains
+
+// All chains with V4 deployed
+const v4Chains = getV4Chains();
+
+// Resolve slug to chain ID
+const chainId = chainIdFromSlug('arbitrum'); // 42161
+
+// Fee tiers with tick spacing
+FEE_TIERS.forEach(t => console.log(t.label, t.fee, t.tickSpacing));
+```
+
+Supported chains: Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain, Unichain, Avalanche, Celo, Blast, Zora, World Chain, Soneium, zkSync, Monad.
+
 ## Liquidity Management
 
 Manage Uniswap V3 and V4 liquidity positions on Base.
@@ -514,6 +682,28 @@ import type {
   UniswapV4Addresses,
   UniswapV3Addresses,
   CommonAddresses,
+  // Uniswap Trading API types
+  UniswapTradingConfig,
+  TradingSwapParams,
+  TradingQuote,
+  TradingSwapResult,
+  ApprovalCheckResult,
+  // Uniswap Quoter types
+  QuoterConfig,
+  PoolKey,
+  QuoteParams,
+  QuoteResult,
+  PoolState,
+  // Permit2 types
+  Permit2Config,
+  Permit2Allowance,
+  PermitSingleParams,
+  PermitBatchParams,
+  SignedPermitSingle,
+  SignedPermitBatch,
+  // Multi-chain registry types
+  UniswapChainConfig,
+  FeeTier,
   // Verified agent launch types
   ClawnchApiDeployer,
   ApiDeployerConfig,

package/dist/analytics.d.ts

@@ -0,0 +1,157 @@
+/**
+ * ClawnchAnalytics — Price history aggregation and technical indicators.
+ *
+ * Builds OHLCV candles from on-chain swap events and computes basic
+ * technical indicators the agent can use for trading decisions.
+ *
+ * Indicators:
+ *   - SMA (Simple Moving Average) — trend direction
+ *   - EMA (Exponential Moving Average) — responsive trend
+ *   - RSI (Relative Strength Index) — overbought/oversold
+ *   - Bollinger Bands — volatility + mean reversion
+ *   - VWAP (Volume-Weighted Average Price) — fair price
+ *   - Volatility (annualized, from returns)
+ *
+ * @example
+ * ```typescript
+ * const analytics = new ClawnchAnalytics();
+ *
+ * // Build candles from swap events
+ * const swaps = await watcher.getRecentSwaps(poolId, { fromBlock: 1000n });
+ * const candles = analytics.buildCandles(swaps, wethSide, '1h');
+ *
+ * // Compute indicators
+ * const sma20 = analytics.sma(candles, 20);
+ * const rsi14 = analytics.rsi(candles, 14);
+ * const bb = analytics.bollingerBands(candles, 20, 2);
+ *
+ * // Get a full analysis
+ * const analysis = analytics.analyze(candles);
+ * console.log(analysis.signal); // 'bullish' | 'bearish' | 'neutral'
+ * ```
+ */
+import type { PoolSwapEvent } from './watcher.js';
+export interface Candle {
+    /** Period start timestamp (ms) */
+    timestamp: number;
+    /** Opening price in ETH */
+    open: number;
+    /** Highest price in period */
+    high: number;
+    /** Lowest price in period */
+    low: number;
+    /** Closing price in ETH */
+    close: number;
+    /** Volume in ETH (absolute value of WETH side) */
+    volume: number;
+    /** Number of swaps in this candle */
+    swapCount: number;
+}
+export type CandleInterval = '5m' | '15m' | '1h' | '4h' | '1d';
+export interface BollingerBand {
+    upper: number;
+    middle: number;
+    lower: number;
+    bandwidth: number;
+}
+export type Signal = 'strong_buy' | 'buy' | 'neutral' | 'sell' | 'strong_sell';
+export interface MarketAnalysis {
+    /** Overall signal */
+    signal: Signal;
+    /** Signal strength 0-100 */
+    strength: number;
+    /** Individual indicator signals */
+    indicators: {
+        sma20: {
+            value: number;
+            signal: Signal;
+        };
+        sma50: {
+            value: number;
+            signal: Signal;
+        };
+        rsi14: {
+            value: number;
+            signal: Signal;
+        };
+        bollinger: {
+            band: BollingerBand;
+            signal: Signal;
+        };
+        vwap: {
+            value: number;
+            signal: Signal;
+        };
+        volatility: {
+            annualized: number;
+            signal: Signal;
+        };
+    };
+    /** Current price */
+    currentPrice: number;
+    /** Volume trend */
+    volumeTrend: 'increasing' | 'decreasing' | 'stable';
+    /** Human-readable summary for agent prompt */
+    summary: string;
+}
+export declare class ClawnchAnalytics {
+    /**
+     * Build OHLCV candles from raw swap events.
+     *
+     * @param swaps - Pool swap events (from ClawnchWatcher.getRecentSwaps)
+     * @param wethSide - Which side WETH is on in the pool (0 or 1)
+     * @param interval - Candle interval
+     * @param tokenDecimals - Token decimals (default 18)
+     * @returns Sorted candles (oldest first)
+     */
+    buildCandles(swaps: PoolSwapEvent[], wethSide: 0 | 1, interval?: CandleInterval, tokenDecimals?: number): Candle[];
+    /**
+     * Build candles from pre-priced data (e.g. from a price feed or manual entries).
+     * Useful when you already have timestamp + price data rather than raw swap events.
+     */
+    buildCandlesFromPrices(data: Array<{
+        timestamp: number;
+        price: number;
+        volume?: number;
+    }>, interval?: CandleInterval): Candle[];
+    /**
+     * Simple Moving Average over closing prices.
+     */
+    sma(candles: Candle[], period: number): number[];
+    /**
+     * Exponential Moving Average over closing prices.
+     */
+    ema(candles: Candle[], period: number): number[];
+    /**
+     * Relative Strength Index.
+     * RSI < 30 → oversold, RSI > 70 → overbought.
+     */
+    rsi(candles: Candle[], period?: number): number[];
+    /**
+     * Bollinger Bands (SMA ± k standard deviations).
+     */
+    bollingerBands(candles: Candle[], period?: number, k?: number): BollingerBand[];
+    /**
+     * Volume-Weighted Average Price.
+     */
+    vwap(candles: Candle[]): number;
+    /**
+     * Annualized volatility from closing prices.
+     * Uses log returns and scales to annual (assuming 24h candles for daily vol,
+     * or scaled by intervals per year).
+     */
+    volatility(candles: Candle[], interval?: CandleInterval): number;
+    /**
+     * Run all indicators and produce a combined signal + human summary.
+     */
+    analyze(candles: Candle[], interval?: CandleInterval): MarketAnalysis | null;
+    private smaFromValues;
+    private emaFromValues;
+    private signalFromSMA;
+    private signalFromRSI;
+    private signalFromBB;
+    private signalFromVWAP;
+    private signalFromVolatility;
+    private compositeSignal;
+}
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

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