Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector
git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900

npm/packages/agentic-synth/examples/crypto/README.md

@@ -0,0 +1,673 @@
+# Cryptocurrency and Blockchain Data Generation Examples
+
+Comprehensive examples for generating realistic cryptocurrency trading, DeFi protocol, and blockchain data using agentic-synth.
+
+## Overview
+
+This directory contains production-ready examples for simulating:
+
+- **Exchange Data**: OHLCV, order books, trades, liquidity pools, arbitrage
+- **DeFi Scenarios**: Yield farming, liquidity provision, impermanent loss, gas prices
+- **Blockchain Data**: Transactions, wallets, tokens, NFTs, MEV patterns
+
+All examples include **24/7 market patterns** and **cross-exchange scenarios** for realistic crypto market simulation.
+
+## Files
+
+### 1. exchange-data.ts
+
+Cryptocurrency exchange data generation covering both CEX and DEX markets.
+
+**Examples:**
+- OHLCV data for multiple cryptocurrencies (BTC, ETH, SOL, AVAX, MATIC)
+- Real-time order book snapshots with bid/ask spreads
+- Trade execution data with maker/taker fees
+- AMM liquidity pool metrics
+- Cross-exchange arbitrage opportunities
+- 24/7 market data with timezone effects
+- Perpetual futures funding rates
+- Streaming market data feeds
+
+**Key Features:**
+```typescript
+// Generate realistic OHLCV with seasonality
+await generateOHLCV();
+
+// Order book with realistic spreads and depth
+await generateOrderBook();
+
+// 10k trades with realistic patterns
+await generateTrades();
+
+// DEX liquidity pool data
+await generateLiquidityPools();
+
+// Cross-exchange arbitrage
+await generateArbitrageOpportunities();
+```
+
+### 2. defi-scenarios.ts
+
+DeFi protocol simulations for yield farming, lending, and advanced strategies.
+
+**Examples:**
+- Yield farming across Aave, Compound, Curve, Convex, Yearn
+- Liquidity provision scenarios with LP token calculations
+- Impermanent loss simulations under various market conditions
+- Gas price data with network congestion patterns
+- Smart contract interaction sequences
+- Lending/borrowing position management
+- Staking rewards (liquid staking protocols)
+- MEV extraction scenarios
+
+**Key Features:**
+```typescript
+// Yield farming data
+await generateYieldFarmingData();
+
+// LP scenarios with IL analysis
+await generateLiquidityProvisionScenarios();
+
+// Impermanent loss under different conditions
+await generateImpermanentLossScenarios();
+
+// Gas price optimization
+await generateGasPriceData();
+
+// Smart contract interactions
+await generateSmartContractInteractions();
+```
+
+### 3. blockchain-data.ts
+
+On-chain data generation for transactions, wallets, and blockchain activity.
+
+**Examples:**
+- Transaction patterns across multiple networks (Ethereum, Polygon, Arbitrum, Optimism, Base)
+- Wallet behavior simulation (HODLers, traders, bots, whales)
+- Token transfer events (ERC-20, ERC-721, ERC-1155)
+- NFT marketplace activity and trading
+- MEV bundle construction and extraction
+- Block production and validator performance
+- Smart contract deployment tracking
+- Cross-chain bridge activity
+
+**Key Features:**
+```typescript
+// Generate realistic transactions
+await generateTransactionPatterns();
+
+// Wallet behavior patterns
+await generateWalletBehavior();
+
+// Token transfers
+await generateTokenTransfers();
+
+// NFT trading activity
+await generateNFTActivity();
+
+// MEV scenarios
+await generateMEVPatterns();
+```
+
+## Installation
+
+```bash
+# Install dependencies
+cd packages/agentic-synth
+npm install
+
+# Set up API keys
+cp .env.example .env
+# Add your GEMINI_API_KEY or OPENROUTER_API_KEY
+```
+
+## Usage
+
+### Running Individual Examples
+
+```typescript
+// Import specific examples
+import { generateOHLCV, generateArbitrageOpportunities } from './crypto/exchange-data.js';
+import { generateYieldFarmingData } from './crypto/defi-scenarios.js';
+import { generateWalletBehavior } from './crypto/blockchain-data.js';
+
+// Run examples
+const ohlcvData = await generateOHLCV();
+const arbOps = await generateArbitrageOpportunities();
+const yieldData = await generateYieldFarmingData();
+const wallets = await generateWalletBehavior();
+```
+
+### Running All Examples
+
+```typescript
+// Exchange data examples
+import { runExchangeDataExamples } from './crypto/exchange-data.js';
+await runExchangeDataExamples();
+
+// DeFi scenario examples
+import { runDeFiScenarioExamples } from './crypto/defi-scenarios.js';
+await runDeFiScenarioExamples();
+
+// Blockchain data examples
+import { runBlockchainDataExamples } from './crypto/blockchain-data.js';
+await runBlockchainDataExamples();
+```
+
+### Command Line Usage
+
+```bash
+# Run via Node.js
+node --experimental-modules examples/crypto/exchange-data.js
+node --experimental-modules examples/crypto/defi-scenarios.js
+node --experimental-modules examples/crypto/blockchain-data.js
+
+# Run via ts-node
+ts-node examples/crypto/exchange-data.ts
+```
+
+## Configuration
+
+### Basic Configuration
+
+```typescript
+import { createSynth } from '@ruvector/agentic-synth';
+
+const synth = createSynth({
+  provider: 'gemini',           // or 'openrouter'
+  apiKey: process.env.GEMINI_API_KEY,
+  model: 'gemini-2.0-flash-exp', // or 'anthropic/claude-3.5-sonnet'
+  cacheStrategy: 'memory',       // Enable caching
+  cacheTTL: 3600                 // Cache for 1 hour
+});
+```
+
+### Provider Options
+
+**Gemini (Recommended for crypto data):**
+```typescript
+{
+  provider: 'gemini',
+  apiKey: process.env.GEMINI_API_KEY,
+  model: 'gemini-2.0-flash-exp'
+}
+```
+
+**OpenRouter (For Claude/GPT models):**
+```typescript
+{
+  provider: 'openrouter',
+  apiKey: process.env.OPENROUTER_API_KEY,
+  model: 'anthropic/claude-3.5-sonnet'
+}
+```
+
+## Key Features
+
+### 24/7 Market Patterns
+
+All examples include realistic 24/7 cryptocurrency market patterns:
+
+- **Asian Session**: Increased volatility, lower volume
+- **European Session**: Medium volatility, building volume
+- **US Session**: Highest volume, major moves
+- **Weekend Effect**: 30% lower volume typically
+- **Holiday Impact**: Reduced activity during major holidays
+
+```typescript
+const result = await synth.generateTimeSeries({
+  count: 168 * 12, // 1 week of 5-minute data
+  interval: '5m',
+  seasonality: true, // Enable session patterns
+  // ...
+});
+```
+
+### Cross-Exchange Arbitrage
+
+Realistic price differences and arbitrage opportunities:
+
+```typescript
+const arbOps = await generateArbitrageOpportunities();
+// Returns opportunities across Binance, Coinbase, Kraken, OKX
+// Includes:
+// - Price spreads
+// - Execution times
+// - Fee calculations
+// - Feasibility analysis
+```
+
+### Gas Price Optimization
+
+Network congestion modeling for transaction cost analysis:
+
+```typescript
+const gasData = await generateGasPriceData();
+// Includes:
+// - Base fee dynamics (EIP-1559)
+// - Priority fees
+// - Network congestion levels
+// - Cost estimates for different transaction types
+```
+
+### Impermanent Loss Calculations
+
+Accurate IL simulation for liquidity providers:
+
+```typescript
+const ilData = await generateImpermanentLossScenarios();
+// Formula: 2 * sqrt(priceRatio) / (1 + priceRatio) - 1
+// Includes:
+// - Price divergence analysis
+// - Fee compensation
+// - Break-even calculations
+// - Recommendations
+```
+
+## Data Schemas
+
+### OHLCV Schema
+
+```typescript
+{
+  timestamp: string,      // ISO 8601
+  symbol: string,         // e.g., "BTC/USDT"
+  open: number,
+  high: number,           // >= max(open, close, low)
+  low: number,            // <= min(open, close, high)
+  close: number,
+  volume: number,
+  vwap: number,          // Volume-weighted average price
+  trades: number         // Number of trades
+}
+```
+
+### Order Book Schema
+
+```typescript
+{
+  timestamp: string,
+  exchange: string,
+  symbol: string,
+  bids: [
+    { price: number, quantity: number, total: number }
+  ],
+  asks: [
+    { price: number, quantity: number, total: number }
+  ],
+  spread: number,        // asks[0].price - bids[0].price
+  midPrice: number,      // (bids[0].price + asks[0].price) / 2
+  liquidity: {
+    bidDepth: number,
+    askDepth: number,
+    totalDepth: number
+  }
+}
+```
+
+### Trade Schema
+
+```typescript
+{
+  tradeId: string,
+  timestamp: string,
+  exchange: string,
+  symbol: string,
+  side: 'buy' | 'sell',
+  orderType: 'market' | 'limit' | 'stop' | 'stop_limit',
+  price: number,
+  quantity: number,
+  total: number,
+  fee: number,
+  feeAsset: string,
+  makerTaker: 'maker' | 'taker',
+  latency: number        // milliseconds
+}
+```
+
+### Liquidity Pool Schema
+
+```typescript
+{
+  timestamp: string,
+  dex: string,
+  poolAddress: string,
+  tokenA: string,
+  tokenB: string,
+  reserveA: number,
+  reserveB: number,
+  totalLiquidity: number,
+  price: number,         // reserveB / reserveA
+  volume24h: number,
+  fees24h: number,
+  apy: number,
+  impermanentLoss: number
+}
+```
+
+## Use Cases
+
+### 1. Trading Algorithm Development
+
+Generate realistic market data for backtesting trading strategies:
+
+```typescript
+const historicalData = await generateOHLCV();
+const orderBook = await generateOrderBook();
+const trades = await generateTrades();
+
+// Use for:
+// - Strategy backtesting
+// - Order execution simulation
+// - Market impact analysis
+```
+
+### 2. DeFi Protocol Testing
+
+Test DeFi applications with realistic scenarios:
+
+```typescript
+const yieldData = await generateYieldFarmingData();
+const lpScenarios = await generateLiquidityProvisionScenarios();
+const gasData = await generateGasPriceData();
+
+// Use for:
+// - APY calculation testing
+// - IL mitigation strategies
+// - Gas optimization
+```
+
+### 3. Risk Analysis
+
+Simulate various market conditions for risk assessment:
+
+```typescript
+const ilScenarios = await generateImpermanentLossScenarios();
+const lendingScenarios = await generateLendingScenarios();
+
+// Use for:
+// - Portfolio risk assessment
+// - Liquidation analysis
+// - Stress testing
+```
+
+### 4. Blockchain Analytics
+
+Generate on-chain data for analytics platforms:
+
+```typescript
+const txPatterns = await generateTransactionPatterns();
+const wallets = await generateWalletBehavior();
+const nftActivity = await generateNFTActivity();
+
+// Use for:
+// - Wallet profiling
+// - Transaction pattern analysis
+// - Network activity monitoring
+```
+
+### 5. MEV Research
+
+Study MEV extraction patterns and strategies:
+
+```typescript
+const mevPatterns = await generateMEVPatterns();
+const arbOps = await generateArbitrageOpportunities();
+
+// Use for:
+// - MEV strategy development
+// - Sandwich attack analysis
+// - Flashbot simulation
+```
+
+## Performance Optimization
+
+### Caching
+
+Enable caching for repeated queries:
+
+```typescript
+const synth = createSynth({
+  cacheStrategy: 'memory',
+  cacheTTL: 3600  // 1 hour
+});
+
+// First call: generates data
+const data1 = await synth.generateTimeSeries({...});
+
+// Second call: returns cached data
+const data2 = await synth.generateTimeSeries({...}); // Fast!
+```
+
+### Batch Generation
+
+Generate multiple datasets in parallel:
+
+```typescript
+const batches = [
+  { count: 100, interval: '1h' },
+  { count: 200, interval: '5m' },
+  { count: 50, interval: '1d' }
+];
+
+const results = await synth.generateBatch('timeseries', batches, 3);
+// Processes 3 batches concurrently
+```
+
+### Streaming
+
+Use streaming for real-time data generation:
+
+```typescript
+for await (const tick of synth.generateStream('timeseries', {
+  count: 100,
+  interval: '1s',
+  metrics: ['price', 'volume']
+})) {
+  console.log('New tick:', tick);
+  // Process data in real-time
+}
+```
+
+## Best Practices
+
+1. **Use Appropriate Intervals**
+   - 1s-1m: High-frequency trading, tick data
+   - 5m-1h: Intraday trading, short-term analysis
+   - 4h-1d: Swing trading, daily analysis
+   - 1d-1w: Long-term analysis, backtesting
+
+2. **Set Realistic Constraints**
+   - Use market-appropriate price ranges
+   - Set sensible volatility levels (0.1-0.3 for crypto)
+   - Include seasonality for realistic patterns
+
+3. **Validate Generated Data**
+   - Check for price consistency (high >= max(open, close, low))
+   - Verify volume patterns
+   - Ensure timestamp ordering
+
+4. **Optimize for Scale**
+   - Use caching for repeated queries
+   - Batch generation for multiple datasets
+   - Stream data for real-time applications
+
+5. **Security Considerations**
+   - Never hardcode API keys
+   - Use environment variables
+   - Implement rate limiting
+   - Validate all inputs
+
+## Examples Output
+
+### OHLCV Data Sample
+
+```json
+{
+  "timestamp": "2025-01-22T10:00:00.000Z",
+  "symbol": "BTC/USDT",
+  "open": 42150.50,
+  "high": 42380.25,
+  "low": 42080.00,
+  "close": 42295.75,
+  "volume": 125.48,
+  "vwap": 42225.33,
+  "trades": 342
+}
+```
+
+### Arbitrage Opportunity Sample
+
+```json
+{
+  "timestamp": "2025-01-22T10:15:32.000Z",
+  "symbol": "ETH/USDT",
+  "buyExchange": "binance",
+  "sellExchange": "coinbase",
+  "buyPrice": 2245.50,
+  "sellPrice": 2258.25,
+  "spread": 12.75,
+  "spreadPercent": 0.568,
+  "profitUSD": 127.50,
+  "feasible": true
+}
+```
+
+### Impermanent Loss Sample
+
+```json
+{
+  "timestamp": "2025-01-22T10:00:00.000Z",
+  "scenario": "high_volatility",
+  "priceRatio": 1.5,
+  "impermanentLoss": -2.02,
+  "impermanentLossPercent": -2.02,
+  "hodlValue": 10000,
+  "lpValue": 9798,
+  "feesEarned": 150,
+  "netProfit": -52,
+  "recommendation": "rebalance"
+}
+```
+
+## Troubleshooting
+
+### API Rate Limits
+
+If you hit rate limits:
+
+```typescript
+const synth = createSynth({
+  maxRetries: 5,
+  timeout: 60000  // Increase timeout
+});
+```
+
+### Memory Issues
+
+For large datasets:
+
+```typescript
+// Use streaming instead of batch generation
+for await (const data of synth.generateStream(...)) {
+  processData(data);
+  // Process one at a time
+}
+```
+
+### Data Quality Issues
+
+If generated data doesn't meet requirements:
+
+```typescript
+// Add more specific constraints
+const result = await synth.generateTimeSeries({
+  // ...
+  constraints: {
+    custom: [
+      'high >= Math.max(open, close, low)',
+      'low <= Math.min(open, close, high)',
+      'volume > 1000',
+      'realistic market microstructure'
+    ]
+  }
+});
+```
+
+## Integration Examples
+
+### With Trading Bots
+
+```typescript
+import { generateOHLCV, generateOrderBook } from './crypto/exchange-data.js';
+
+async function backtestStrategy() {
+  const historicalData = await generateOHLCV();
+  const orderBook = await generateOrderBook();
+
+  // Run your trading strategy
+  const results = runBacktest(historicalData, orderBook);
+
+  return results;
+}
+```
+
+### With DeFi Protocols
+
+```typescript
+import { generateYieldFarmingData, generateGasPriceData } from './crypto/defi-scenarios.js';
+
+async function optimizeYield() {
+  const yieldData = await generateYieldFarmingData();
+  const gasData = await generateGasPriceData();
+
+  // Calculate optimal farming strategy
+  const strategy = calculateOptimal(yieldData, gasData);
+
+  return strategy;
+}
+```
+
+### With Analytics Platforms
+
+```typescript
+import { generateWalletBehavior, generateTransactionPatterns } from './crypto/blockchain-data.js';
+
+async function analyzeUserBehavior() {
+  const wallets = await generateWalletBehavior();
+  const transactions = await generateTransactionPatterns();
+
+  // Perform analytics
+  const insights = analyzePatterns(wallets, transactions);
+
+  return insights;
+}
+```
+
+## Contributing
+
+To add new crypto data examples:
+
+1. Follow existing patterns in the example files
+2. Include realistic constraints and validations
+3. Add comprehensive documentation
+4. Include sample outputs
+5. Test with multiple data sizes
+
+## Resources
+
+- [agentic-synth Documentation](../../README.md)
+- [Crypto Market Data Standards](https://www.ccxt.pro/)
+- [DeFi Protocol Documentation](https://defillama.com/)
+- [Blockchain Data APIs](https://www.alchemy.com/)
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/ruvnet/ruvector/issues
+- Documentation: https://github.com/ruvnet/ruvector/tree/main/packages/agentic-synth
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) for details

npm/packages/agentic-synth/examples/crypto/blockchain-data.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Blockchain and On-Chain Data Generation
+ *
+ * Examples for generating realistic blockchain data including:
+ * - Transaction patterns and behaviors
+ * - Wallet activity simulation
+ * - Token transfer events
+ * - NFT trading activity
+ * - MEV (Maximal Extractable Value) scenarios
+ */
+/**
+ * Example 1: Generate realistic transaction patterns
+ * Simulates various transaction types across different networks
+ */
+declare function generateTransactionPatterns(): Promise<{
+    network: string;
+    data: unknown[];
+}[]>;
+/**
+ * Example 2: Simulate wallet behavior patterns
+ * Includes HODLers, traders, bots, and contract wallets
+ */
+declare function generateWalletBehavior(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 3: Generate token transfer events
+ * Simulates ERC-20, ERC-721, and ERC-1155 transfers
+ */
+declare function generateTokenTransfers(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 4: Generate NFT trading activity
+ * Includes mints, sales, and marketplace activity
+ */
+declare function generateNFTActivity(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 5: Generate MEV transaction patterns
+ * Advanced MEV extraction and sandwich attack simulations
+ */
+declare function generateMEVPatterns(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 6: Generate block production data
+ * Includes validator performance and block building
+ */
+declare function generateBlockData(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 7: Generate smart contract deployment patterns
+ * Tracks contract creation and verification
+ */
+declare function generateContractDeployments(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 8: Generate cross-chain bridge activity
+ * Simulates asset transfers between blockchains
+ */
+declare function generateBridgeActivity(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Run all blockchain data examples
+ */
+export declare function runBlockchainDataExamples(): Promise<void>;
+export { generateTransactionPatterns, generateWalletBehavior, generateTokenTransfers, generateNFTActivity, generateMEVPatterns, generateBlockData, generateContractDeployments, generateBridgeActivity };
+//# sourceMappingURL=blockchain-data.d.ts.map

npm/packages/agentic-synth/examples/crypto/blockchain-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blockchain-data.d.ts","sourceRoot":"","sources":["blockchain-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;GAGG;AACH,iBAAe,2BAA2B;;;KAsDzC;AAED;;;GAGG;AACH,iBAAe,sBAAsB,oEAwFpC;AAED;;;GAGG;AACH,iBAAe,sBAAsB,oEAoDpC;AAED;;;GAGG;AACH,iBAAe,mBAAmB,oEAwFjC;AAED;;;GAGG;AACH,iBAAe,mBAAmB,oEAmFjC;AAED;;;GAGG;AACH,iBAAe,iBAAiB,oEA2E/B;AAED;;;GAGG;AACH,iBAAe,2BAA2B,oEAwEzC;AAED;;;GAGG;AACH,iBAAe,sBAAsB,oEAmEpC;AAED;;GAEG;AACH,wBAAsB,yBAAyB,kBAiC9C;AAGD,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,2BAA2B,EAC3B,sBAAsB,EACvB,CAAC"}

npm/packages/agentic-synth/examples/crypto/blockchain-data.js

@@ -0,0 +1,632 @@
+"use strict";
+/**
+ * Blockchain and On-Chain Data Generation
+ *
+ * Examples for generating realistic blockchain data including:
+ * - Transaction patterns and behaviors
+ * - Wallet activity simulation
+ * - Token transfer events
+ * - NFT trading activity
+ * - MEV (Maximal Extractable Value) scenarios
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBlockchainDataExamples = runBlockchainDataExamples;
+exports.generateTransactionPatterns = generateTransactionPatterns;
+exports.generateWalletBehavior = generateWalletBehavior;
+exports.generateTokenTransfers = generateTokenTransfers;
+exports.generateNFTActivity = generateNFTActivity;
+exports.generateMEVPatterns = generateMEVPatterns;
+exports.generateBlockData = generateBlockData;
+exports.generateContractDeployments = generateContractDeployments;
+exports.generateBridgeActivity = generateBridgeActivity;
+const index_js_1 = require("../../src/index.js");
+/**
+ * Example 1: Generate realistic transaction patterns
+ * Simulates various transaction types across different networks
+ */
+async function generateTransactionPatterns() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini',
+        apiKey: process.env.GEMINI_API_KEY
+    });
+    const networks = ['ethereum', 'polygon', 'arbitrum', 'optimism', 'base'];
+    const results = [];
+    for (const network of networks) {
+        const result = await synth.generateEvents({
+            count: 10000,
+            eventTypes: [
+                'transfer',
+                'contract_call',
+                'contract_creation',
+                'erc20_transfer',
+                'erc721_transfer',
+                'erc1155_transfer'
+            ],
+            distribution: 'poisson',
+            timeRange: {
+                start: new Date(Date.now() - 24 * 60 * 60 * 1000),
+                end: new Date()
+            },
+            userCount: 5000,
+            schema: {
+                txHash: { type: 'string', format: 'transaction_hash' },
+                blockNumber: { type: 'integer', min: 1000000 },
+                blockTimestamp: { type: 'datetime', format: 'iso8601' },
+                network: { type: 'string', default: network },
+                from: { type: 'string', format: 'ethereum_address' },
+                to: { type: 'string', format: 'ethereum_address' },
+                value: { type: 'number', min: 0 },
+                gasLimit: { type: 'integer', min: 21000, max: 30000000 },
+                gasUsed: { type: 'integer', min: 21000 },
+                gasPrice: { type: 'number', min: 1 },
+                maxFeePerGas: { type: 'number' },
+                maxPriorityFeePerGas: { type: 'number' },
+                nonce: { type: 'integer', min: 0 },
+                transactionIndex: { type: 'integer', min: 0, max: 300 },
+                status: { type: 'string', enum: ['success', 'failed'] },
+                type: { type: 'integer', enum: [0, 1, 2] }, // Legacy, EIP-2930, EIP-1559
+                input: { type: 'string' },
+                methodId: { type: 'string' },
+                internalTransactions: { type: 'integer', min: 0, max: 100 }
+            }
+        });
+        results.push({ network, data: result.data });
+        console.log(`Generated ${network} transactions: ${result.data.length}`);
+    }
+    return results;
+}
+/**
+ * Example 2: Simulate wallet behavior patterns
+ * Includes HODLers, traders, bots, and contract wallets
+ */
+async function generateWalletBehavior() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const walletTypes = ['hodler', 'trader', 'bot', 'whale', 'retail', 'contract'];
+    const result = await synth.generateStructured({
+        count: 5000,
+        schema: {
+            walletAddress: { type: 'string', format: 'ethereum_address', required: true },
+            walletType: { type: 'string', enum: walletTypes },
+            createdAt: { type: 'datetime', required: true },
+            lastActive: { type: 'datetime' },
+            balance: {
+                type: 'object',
+                properties: {
+                    ETH: { type: 'number', min: 0 },
+                    USDC: { type: 'number', min: 0 },
+                    USDT: { type: 'number', min: 0 },
+                    totalValueUSD: { type: 'number', min: 0 }
+                }
+            },
+            activity: {
+                type: 'object',
+                properties: {
+                    totalTxs: { type: 'integer', min: 0 },
+                    txsLast24h: { type: 'integer', min: 0 },
+                    txsLast7d: { type: 'integer', min: 0 },
+                    txsLast30d: { type: 'integer', min: 0 },
+                    avgTxValue: { type: 'number', min: 0 },
+                    avgTxFrequency: { type: 'number', min: 0 } // per day
+                }
+            },
+            holdings: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        token: { type: 'string' },
+                        symbol: { type: 'string' },
+                        balance: { type: 'number' },
+                        valueUSD: { type: 'number' },
+                        allocation: { type: 'number', min: 0, max: 100 }
+                    }
+                }
+            },
+            defi: {
+                type: 'object',
+                properties: {
+                    totalValueLocked: { type: 'number', min: 0 },
+                    activePools: { type: 'integer', min: 0 },
+                    lendingPositions: { type: 'integer', min: 0 },
+                    borrowingPositions: { type: 'integer', min: 0 },
+                    nftCount: { type: 'integer', min: 0 }
+                }
+            },
+            behaviorMetrics: {
+                type: 'object',
+                properties: {
+                    riskProfile: { type: 'string', enum: ['conservative', 'moderate', 'aggressive', 'degen'] },
+                    avgHoldingPeriod: { type: 'number', min: 0 }, // days
+                    tradingFrequency: { type: 'string', enum: ['daily', 'weekly', 'monthly', 'rarely'] },
+                    gasTotalSpent: { type: 'number', min: 0 },
+                    profitLoss: { type: 'number' },
+                    winRate: { type: 'number', min: 0, max: 100 }
+                }
+            },
+            labels: {
+                type: 'array',
+                items: {
+                    type: 'string',
+                    enum: ['whale', 'early_adopter', 'nft_collector', 'yield_farmer', 'mev_bot', 'exchange', 'bridge']
+                }
+            }
+        }
+    });
+    console.log('Generated wallet behavior data:', result.data.length);
+    // Analyze by wallet type
+    const typeDistribution = {};
+    result.data.forEach((wallet) => {
+        typeDistribution[wallet.walletType] = (typeDistribution[wallet.walletType] || 0) + 1;
+    });
+    console.log('Wallet type distribution:', typeDistribution);
+    return result;
+}
+/**
+ * Example 3: Generate token transfer events
+ * Simulates ERC-20, ERC-721, and ERC-1155 transfers
+ */
+async function generateTokenTransfers() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateEvents({
+        count: 50000,
+        eventTypes: ['erc20', 'erc721', 'erc1155'],
+        distribution: 'poisson',
+        timeRange: {
+            start: new Date(Date.now() - 24 * 60 * 60 * 1000),
+            end: new Date()
+        },
+        userCount: 10000,
+        schema: {
+            txHash: { type: 'string', format: 'transaction_hash' },
+            blockNumber: { type: 'integer', min: 18000000 },
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            tokenStandard: { type: 'string', enum: ['erc20', 'erc721', 'erc1155'] },
+            contractAddress: { type: 'string', format: 'ethereum_address' },
+            tokenName: { type: 'string', required: true },
+            tokenSymbol: { type: 'string', required: true },
+            from: { type: 'string', format: 'ethereum_address' },
+            to: { type: 'string', format: 'ethereum_address' },
+            value: { type: 'string' }, // Large numbers as string
+            valueDecimal: { type: 'number' },
+            valueUSD: { type: 'number', min: 0 },
+            tokenId: { type: 'string' }, // For NFTs
+            amount: { type: 'integer' }, // For ERC-1155
+            logIndex: { type: 'integer', min: 0 },
+            metadata: {
+                type: 'object',
+                properties: {
+                    decimals: { type: 'integer', default: 18 },
+                    totalSupply: { type: 'string' },
+                    holderCount: { type: 'integer' },
+                    marketCap: { type: 'number' }
+                }
+            }
+        }
+    });
+    console.log('Generated token transfers:', result.data.length);
+    // Analyze by token standard
+    const standards = {};
+    result.data.forEach((transfer) => {
+        standards[transfer.tokenStandard] = (standards[transfer.tokenStandard] || 0) + 1;
+    });
+    console.log('Transfers by standard:', standards);
+    return result;
+}
+/**
+ * Example 4: Generate NFT trading activity
+ * Includes mints, sales, and marketplace activity
+ */
+async function generateNFTActivity() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateEvents({
+        count: 5000,
+        eventTypes: ['mint', 'sale', 'transfer', 'listing', 'bid', 'offer_accepted'],
+        distribution: 'poisson',
+        timeRange: {
+            start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+            end: new Date()
+        },
+        userCount: 3000,
+        schema: {
+            txHash: { type: 'string', format: 'transaction_hash' },
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            eventType: {
+                type: 'string',
+                enum: ['mint', 'sale', 'transfer', 'listing', 'bid', 'offer_accepted']
+            },
+            marketplace: {
+                type: 'string',
+                enum: ['opensea', 'blur', 'looksrare', 'x2y2', 'rarible', 'foundation']
+            },
+            collection: {
+                type: 'object',
+                properties: {
+                    address: { type: 'string', format: 'ethereum_address' },
+                    name: { type: 'string' },
+                    symbol: { type: 'string' },
+                    floorPrice: { type: 'number', min: 0 },
+                    totalVolume: { type: 'number', min: 0 },
+                    itemCount: { type: 'integer', min: 1 }
+                }
+            },
+            nft: {
+                type: 'object',
+                properties: {
+                    tokenId: { type: 'string' },
+                    name: { type: 'string' },
+                    rarity: { type: 'string', enum: ['common', 'uncommon', 'rare', 'epic', 'legendary'] },
+                    rarityRank: { type: 'integer', min: 1 },
+                    traits: { type: 'array' }
+                }
+            },
+            price: {
+                type: 'object',
+                properties: {
+                    amount: { type: 'number', min: 0 },
+                    currency: { type: 'string', enum: ['ETH', 'WETH', 'USDC', 'APE'] },
+                    usdValue: { type: 'number', min: 0 }
+                }
+            },
+            from: { type: 'string', format: 'ethereum_address' },
+            to: { type: 'string', format: 'ethereum_address' },
+            royalty: {
+                type: 'object',
+                properties: {
+                    recipient: { type: 'string', format: 'ethereum_address' },
+                    amount: { type: 'number', min: 0 },
+                    percentage: { type: 'number', min: 0, max: 10 }
+                }
+            },
+            marketplaceFee: { type: 'number', min: 0 }
+        }
+    });
+    console.log('Generated NFT activity:', result.data.length);
+    // Analyze by event type
+    const events = {};
+    result.data.forEach((activity) => {
+        events[activity.eventType] = (events[activity.eventType] || 0) + 1;
+    });
+    console.log('Activity by type:', events);
+    // Top marketplaces by volume
+    const marketplaces = {};
+    result.data.forEach((activity) => {
+        if (activity.price) {
+            marketplaces[activity.marketplace] =
+                (marketplaces[activity.marketplace] || 0) + activity.price.usdValue;
+        }
+    });
+    console.log('Volume by marketplace:', marketplaces);
+    return result;
+}
+/**
+ * Example 5: Generate MEV transaction patterns
+ * Advanced MEV extraction and sandwich attack simulations
+ */
+async function generateMEVPatterns() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateStructured({
+        count: 1000,
+        schema: {
+            bundleId: { type: 'string', format: 'uuid' },
+            blockNumber: { type: 'integer', min: 18000000 },
+            timestamp: { type: 'datetime', required: true },
+            mevType: {
+                type: 'string',
+                enum: ['sandwich', 'arbitrage', 'liquidation', 'jit', 'backrun', 'frontrun']
+            },
+            bundleTransactions: {
+                type: 'array',
+                minItems: 1,
+                maxItems: 10,
+                items: {
+                    type: 'object',
+                    properties: {
+                        txHash: { type: 'string' },
+                        position: { type: 'integer' },
+                        type: { type: 'string', enum: ['frontrun', 'victim', 'backrun'] },
+                        from: { type: 'string' },
+                        to: { type: 'string' },
+                        value: { type: 'number' },
+                        gasPrice: { type: 'number' }
+                    }
+                }
+            },
+            targetProtocol: {
+                type: 'string',
+                enum: ['uniswap_v2', 'uniswap_v3', 'sushiswap', 'curve', 'balancer', 'aave', 'compound']
+            },
+            profit: {
+                type: 'object',
+                properties: {
+                    gross: { type: 'number' },
+                    gasCost: { type: 'number' },
+                    net: { type: 'number' },
+                    roi: { type: 'number' }
+                }
+            },
+            victimTx: {
+                type: 'object',
+                properties: {
+                    hash: { type: 'string' },
+                    expectedSlippage: { type: 'number' },
+                    actualSlippage: { type: 'number' },
+                    lossUSD: { type: 'number' }
+                }
+            },
+            mevBot: {
+                type: 'object',
+                properties: {
+                    address: { type: 'string', format: 'ethereum_address' },
+                    operator: { type: 'string' },
+                    flashbotRelay: { type: 'boolean' },
+                    privateTx: { type: 'boolean' }
+                }
+            },
+            complexity: { type: 'integer', min: 1, max: 10 },
+            executionTimeMs: { type: 'number', min: 10, max: 5000 }
+        }
+    });
+    console.log('Generated MEV patterns:', result.data.length);
+    // Analyze MEV types
+    const types = {};
+    result.data.forEach((mev) => {
+        types[mev.mevType] = (types[mev.mevType] || 0) + 1;
+    });
+    console.log('MEV by type:', types);
+    // Total profit extracted
+    const totalProfit = result.data.reduce((sum, mev) => sum + mev.profit.net, 0);
+    console.log(`Total MEV extracted: $${totalProfit.toFixed(2)}`);
+    return result;
+}
+/**
+ * Example 6: Generate block production data
+ * Includes validator performance and block building
+ */
+async function generateBlockData() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateTimeSeries({
+        count: 7200, // ~24 hours of blocks (12s block time)
+        interval: '12s',
+        startDate: new Date(Date.now() - 24 * 60 * 60 * 1000),
+        metrics: ['gasUsed', 'baseFee', 'mevReward', 'transactionCount'],
+        trend: 'stable',
+        seasonality: true,
+        noise: 0.15,
+        schema: {
+            blockNumber: { type: 'integer', min: 18000000, required: true },
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            hash: { type: 'string', format: 'block_hash' },
+            parentHash: { type: 'string', format: 'block_hash' },
+            proposer: { type: 'string', format: 'ethereum_address' },
+            validator: {
+                type: 'object',
+                properties: {
+                    index: { type: 'integer' },
+                    balance: { type: 'number' },
+                    effectiveBalance: { type: 'number', default: 32 },
+                    slashed: { type: 'boolean', default: false }
+                }
+            },
+            transactions: {
+                type: 'object',
+                properties: {
+                    count: { type: 'integer', min: 0, max: 300 },
+                    totalValue: { type: 'number' },
+                    totalFees: { type: 'number' },
+                    internalTxs: { type: 'integer' }
+                }
+            },
+            gas: {
+                type: 'object',
+                properties: {
+                    used: { type: 'integer', min: 0, max: 30000000 },
+                    limit: { type: 'integer', default: 30000000 },
+                    utilization: { type: 'number', min: 0, max: 100 },
+                    baseFee: { type: 'number', min: 1 },
+                    avgPriorityFee: { type: 'number' }
+                }
+            },
+            mev: {
+                type: 'object',
+                properties: {
+                    bundles: { type: 'integer', min: 0 },
+                    reward: { type: 'number', min: 0 },
+                    flashbotsTx: { type: 'integer', min: 0 }
+                }
+            },
+            size: { type: 'integer', min: 1000 },
+            difficulty: { type: 'string' },
+            extraData: { type: 'string' },
+            blockReward: { type: 'number', min: 0 }
+        }
+    });
+    console.log('Generated block data:', result.data.length);
+    // Calculate average block stats
+    const avgGasUsed = result.data.reduce((sum, block) => sum + block.gas.used, 0) / result.data.length;
+    const avgTxCount = result.data.reduce((sum, block) => sum + block.transactions.count, 0) / result.data.length;
+    console.log('Average block statistics:');
+    console.log(`  Gas used: ${avgGasUsed.toFixed(0)}`);
+    console.log(`  Transactions: ${avgTxCount.toFixed(0)}`);
+    return result;
+}
+/**
+ * Example 7: Generate smart contract deployment patterns
+ * Tracks contract creation and verification
+ */
+async function generateContractDeployments() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateEvents({
+        count: 1000,
+        eventTypes: ['erc20', 'erc721', 'erc1155', 'proxy', 'defi', 'custom'],
+        distribution: 'uniform',
+        timeRange: {
+            start: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+            end: new Date()
+        },
+        userCount: 500,
+        schema: {
+            txHash: { type: 'string', format: 'transaction_hash' },
+            blockNumber: { type: 'integer', min: 18000000 },
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            deployer: { type: 'string', format: 'ethereum_address' },
+            contractAddress: { type: 'string', format: 'ethereum_address' },
+            contractType: {
+                type: 'string',
+                enum: ['token', 'nft', 'defi', 'dao', 'bridge', 'oracle', 'gaming', 'other']
+            },
+            standard: { type: 'string', enum: ['erc20', 'erc721', 'erc1155', 'erc4626', 'custom'] },
+            bytecode: { type: 'string' },
+            bytecodeSize: { type: 'integer', min: 100, max: 24576 },
+            constructorArgs: { type: 'array' },
+            verified: { type: 'boolean' },
+            verificationDate: { type: 'datetime' },
+            compiler: {
+                type: 'object',
+                properties: {
+                    version: { type: 'string' },
+                    optimization: { type: 'boolean' },
+                    runs: { type: 'integer', default: 200 }
+                }
+            },
+            proxy: {
+                type: 'object',
+                properties: {
+                    isProxy: { type: 'boolean' },
+                    implementation: { type: 'string' },
+                    proxyType: { type: 'string', enum: ['transparent', 'uups', 'beacon', 'none'] }
+                }
+            },
+            gasUsed: { type: 'integer', min: 100000 },
+            deploymentCost: { type: 'number', min: 0 },
+            activity: {
+                type: 'object',
+                properties: {
+                    uniqueUsers: { type: 'integer', min: 0 },
+                    totalTxs: { type: 'integer', min: 0 },
+                    totalVolume: { type: 'number', min: 0 }
+                }
+            }
+        }
+    });
+    console.log('Generated contract deployments:', result.data.length);
+    // Analyze by type
+    const types = {};
+    result.data.forEach((contract) => {
+        types[contract.contractType] = (types[contract.contractType] || 0) + 1;
+    });
+    console.log('Deployments by type:', types);
+    const verified = result.data.filter((c) => c.verified).length;
+    console.log(`Verification rate: ${(verified / result.data.length * 100).toFixed(1)}%`);
+    return result;
+}
+/**
+ * Example 8: Generate cross-chain bridge activity
+ * Simulates asset transfers between blockchains
+ */
+async function generateBridgeActivity() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateEvents({
+        count: 2000,
+        eventTypes: ['deposit', 'withdraw', 'relay'],
+        distribution: 'poisson',
+        timeRange: {
+            start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+            end: new Date()
+        },
+        userCount: 1000,
+        schema: {
+            bridgeTxId: { type: 'string', format: 'uuid' },
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            bridge: {
+                type: 'string',
+                enum: ['stargate', 'hop', 'across', 'synapse', 'multichain', 'wormhole', 'layerzero']
+            },
+            sourceChain: {
+                type: 'string',
+                enum: ['ethereum', 'polygon', 'arbitrum', 'optimism', 'avalanche', 'bsc']
+            },
+            destinationChain: {
+                type: 'string',
+                enum: ['ethereum', 'polygon', 'arbitrum', 'optimism', 'avalanche', 'bsc']
+            },
+            user: { type: 'string', format: 'ethereum_address' },
+            asset: { type: 'string', enum: ['ETH', 'USDC', 'USDT', 'DAI', 'WBTC'] },
+            amount: { type: 'number', min: 1 },
+            amountUSD: { type: 'number', min: 1 },
+            fees: {
+                type: 'object',
+                properties: {
+                    sourceGas: { type: 'number' },
+                    bridgeFee: { type: 'number' },
+                    destinationGas: { type: 'number' },
+                    totalFee: { type: 'number' }
+                }
+            },
+            status: {
+                type: 'string',
+                enum: ['pending', 'relaying', 'completed', 'failed', 'refunded']
+            },
+            sourceTxHash: { type: 'string', format: 'transaction_hash' },
+            destinationTxHash: { type: 'string', format: 'transaction_hash' },
+            completionTime: { type: 'number', min: 60, max: 3600 }, // seconds
+            securityDelay: { type: 'number', min: 0, max: 86400 }
+        }
+    });
+    console.log('Generated bridge activity:', result.data.length);
+    // Analyze bridge usage
+    const bridges = {};
+    result.data.forEach((tx) => {
+        bridges[tx.bridge] = (bridges[tx.bridge] || 0) + 1;
+    });
+    console.log('Usage by bridge:', bridges);
+    // Calculate success rate
+    const completed = result.data.filter((tx) => tx.status === 'completed').length;
+    console.log(`Success rate: ${(completed / result.data.length * 100).toFixed(1)}%`);
+    return result;
+}
+/**
+ * Run all blockchain data examples
+ */
+async function runBlockchainDataExamples() {
+    console.log('=== Blockchain and On-Chain Data Generation Examples ===\n');
+    console.log('Example 1: Transaction Patterns');
+    await generateTransactionPatterns();
+    console.log('\n---\n');
+    console.log('Example 2: Wallet Behavior');
+    await generateWalletBehavior();
+    console.log('\n---\n');
+    console.log('Example 3: Token Transfers');
+    await generateTokenTransfers();
+    console.log('\n---\n');
+    console.log('Example 4: NFT Activity');
+    await generateNFTActivity();
+    console.log('\n---\n');
+    console.log('Example 5: MEV Patterns');
+    await generateMEVPatterns();
+    console.log('\n---\n');
+    console.log('Example 6: Block Production Data');
+    await generateBlockData();
+    console.log('\n---\n');
+    console.log('Example 7: Contract Deployments');
+    await generateContractDeployments();
+    console.log('\n---\n');
+    console.log('Example 8: Bridge Activity');
+    await generateBridgeActivity();
+}
+// Uncomment to run
+// runBlockchainDataExamples().catch(console.error);
+//# sourceMappingURL=blockchain-data.js.map

npm/packages/agentic-synth/examples/crypto/blockchain-data.ts

@@ -0,0 +1,692 @@
+/**
+ * Blockchain and On-Chain Data Generation
+ *
+ * Examples for generating realistic blockchain data including:
+ * - Transaction patterns and behaviors
+ * - Wallet activity simulation
+ * - Token transfer events
+ * - NFT trading activity
+ * - MEV (Maximal Extractable Value) scenarios
+ */
+
+import { createSynth } from '../../src/index.js';
+
+/**
+ * Example 1: Generate realistic transaction patterns
+ * Simulates various transaction types across different networks
+ */
+async function generateTransactionPatterns() {
+  const synth = createSynth({
+    provider: 'gemini',
+    apiKey: process.env.GEMINI_API_KEY
+  });
+
+  const networks = ['ethereum', 'polygon', 'arbitrum', 'optimism', 'base'];
+  const results = [];
+
+  for (const network of networks) {
+    const result = await synth.generateEvents({
+      count: 10000,
+      eventTypes: [
+        'transfer',
+        'contract_call',
+        'contract_creation',
+        'erc20_transfer',
+        'erc721_transfer',
+        'erc1155_transfer'
+      ],
+      distribution: 'poisson',
+      timeRange: {
+        start: new Date(Date.now() - 24 * 60 * 60 * 1000),
+        end: new Date()
+      },
+      userCount: 5000,
+      schema: {
+        txHash: { type: 'string', format: 'transaction_hash' },
+        blockNumber: { type: 'integer', min: 1000000 },
+        blockTimestamp: { type: 'datetime', format: 'iso8601' },
+        network: { type: 'string', default: network },
+        from: { type: 'string', format: 'ethereum_address' },
+        to: { type: 'string', format: 'ethereum_address' },
+        value: { type: 'number', min: 0 },
+        gasLimit: { type: 'integer', min: 21000, max: 30000000 },
+        gasUsed: { type: 'integer', min: 21000 },
+        gasPrice: { type: 'number', min: 1 },
+        maxFeePerGas: { type: 'number' },
+        maxPriorityFeePerGas: { type: 'number' },
+        nonce: { type: 'integer', min: 0 },
+        transactionIndex: { type: 'integer', min: 0, max: 300 },
+        status: { type: 'string', enum: ['success', 'failed'] },
+        type: { type: 'integer', enum: [0, 1, 2] }, // Legacy, EIP-2930, EIP-1559
+        input: { type: 'string' },
+        methodId: { type: 'string' },
+        internalTransactions: { type: 'integer', min: 0, max: 100 }
+      }
+    });
+
+    results.push({ network, data: result.data });
+    console.log(`Generated ${network} transactions: ${result.data.length}`);
+  }
+
+  return results;
+}
+
+/**
+ * Example 2: Simulate wallet behavior patterns
+ * Includes HODLers, traders, bots, and contract wallets
+ */
+async function generateWalletBehavior() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const walletTypes = ['hodler', 'trader', 'bot', 'whale', 'retail', 'contract'];
+
+  const result = await synth.generateStructured({
+    count: 5000,
+    schema: {
+      walletAddress: { type: 'string', format: 'ethereum_address', required: true },
+      walletType: { type: 'string', enum: walletTypes },
+      createdAt: { type: 'datetime', required: true },
+      lastActive: { type: 'datetime' },
+      balance: {
+        type: 'object',
+        properties: {
+          ETH: { type: 'number', min: 0 },
+          USDC: { type: 'number', min: 0 },
+          USDT: { type: 'number', min: 0 },
+          totalValueUSD: { type: 'number', min: 0 }
+        }
+      },
+      activity: {
+        type: 'object',
+        properties: {
+          totalTxs: { type: 'integer', min: 0 },
+          txsLast24h: { type: 'integer', min: 0 },
+          txsLast7d: { type: 'integer', min: 0 },
+          txsLast30d: { type: 'integer', min: 0 },
+          avgTxValue: { type: 'number', min: 0 },
+          avgTxFrequency: { type: 'number', min: 0 } // per day
+        }
+      },
+      holdings: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            token: { type: 'string' },
+            symbol: { type: 'string' },
+            balance: { type: 'number' },
+            valueUSD: { type: 'number' },
+            allocation: { type: 'number', min: 0, max: 100 }
+          }
+        }
+      },
+      defi: {
+        type: 'object',
+        properties: {
+          totalValueLocked: { type: 'number', min: 0 },
+          activePools: { type: 'integer', min: 0 },
+          lendingPositions: { type: 'integer', min: 0 },
+          borrowingPositions: { type: 'integer', min: 0 },
+          nftCount: { type: 'integer', min: 0 }
+        }
+      },
+      behaviorMetrics: {
+        type: 'object',
+        properties: {
+          riskProfile: { type: 'string', enum: ['conservative', 'moderate', 'aggressive', 'degen'] },
+          avgHoldingPeriod: { type: 'number', min: 0 }, // days
+          tradingFrequency: { type: 'string', enum: ['daily', 'weekly', 'monthly', 'rarely'] },
+          gasTotalSpent: { type: 'number', min: 0 },
+          profitLoss: { type: 'number' },
+          winRate: { type: 'number', min: 0, max: 100 }
+        }
+      },
+      labels: {
+        type: 'array',
+        items: {
+          type: 'string',
+          enum: ['whale', 'early_adopter', 'nft_collector', 'yield_farmer', 'mev_bot', 'exchange', 'bridge']
+        }
+      }
+    }
+  });
+
+  console.log('Generated wallet behavior data:', result.data.length);
+
+  // Analyze by wallet type
+  const typeDistribution: any = {};
+  result.data.forEach((wallet: any) => {
+    typeDistribution[wallet.walletType] = (typeDistribution[wallet.walletType] || 0) + 1;
+  });
+  console.log('Wallet type distribution:', typeDistribution);
+
+  return result;
+}
+
+/**
+ * Example 3: Generate token transfer events
+ * Simulates ERC-20, ERC-721, and ERC-1155 transfers
+ */
+async function generateTokenTransfers() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateEvents({
+    count: 50000,
+    eventTypes: ['erc20', 'erc721', 'erc1155'],
+    distribution: 'poisson',
+    timeRange: {
+      start: new Date(Date.now() - 24 * 60 * 60 * 1000),
+      end: new Date()
+    },
+    userCount: 10000,
+    schema: {
+      txHash: { type: 'string', format: 'transaction_hash' },
+      blockNumber: { type: 'integer', min: 18000000 },
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      tokenStandard: { type: 'string', enum: ['erc20', 'erc721', 'erc1155'] },
+      contractAddress: { type: 'string', format: 'ethereum_address' },
+      tokenName: { type: 'string', required: true },
+      tokenSymbol: { type: 'string', required: true },
+      from: { type: 'string', format: 'ethereum_address' },
+      to: { type: 'string', format: 'ethereum_address' },
+      value: { type: 'string' }, // Large numbers as string
+      valueDecimal: { type: 'number' },
+      valueUSD: { type: 'number', min: 0 },
+      tokenId: { type: 'string' }, // For NFTs
+      amount: { type: 'integer' }, // For ERC-1155
+      logIndex: { type: 'integer', min: 0 },
+      metadata: {
+        type: 'object',
+        properties: {
+          decimals: { type: 'integer', default: 18 },
+          totalSupply: { type: 'string' },
+          holderCount: { type: 'integer' },
+          marketCap: { type: 'number' }
+        }
+      }
+    }
+  });
+
+  console.log('Generated token transfers:', result.data.length);
+
+  // Analyze by token standard
+  const standards: any = {};
+  result.data.forEach((transfer: any) => {
+    standards[transfer.tokenStandard] = (standards[transfer.tokenStandard] || 0) + 1;
+  });
+  console.log('Transfers by standard:', standards);
+
+  return result;
+}
+
+/**
+ * Example 4: Generate NFT trading activity
+ * Includes mints, sales, and marketplace activity
+ */
+async function generateNFTActivity() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateEvents({
+    count: 5000,
+    eventTypes: ['mint', 'sale', 'transfer', 'listing', 'bid', 'offer_accepted'],
+    distribution: 'poisson',
+    timeRange: {
+      start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+      end: new Date()
+    },
+    userCount: 3000,
+    schema: {
+      txHash: { type: 'string', format: 'transaction_hash' },
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      eventType: {
+        type: 'string',
+        enum: ['mint', 'sale', 'transfer', 'listing', 'bid', 'offer_accepted']
+      },
+      marketplace: {
+        type: 'string',
+        enum: ['opensea', 'blur', 'looksrare', 'x2y2', 'rarible', 'foundation']
+      },
+      collection: {
+        type: 'object',
+        properties: {
+          address: { type: 'string', format: 'ethereum_address' },
+          name: { type: 'string' },
+          symbol: { type: 'string' },
+          floorPrice: { type: 'number', min: 0 },
+          totalVolume: { type: 'number', min: 0 },
+          itemCount: { type: 'integer', min: 1 }
+        }
+      },
+      nft: {
+        type: 'object',
+        properties: {
+          tokenId: { type: 'string' },
+          name: { type: 'string' },
+          rarity: { type: 'string', enum: ['common', 'uncommon', 'rare', 'epic', 'legendary'] },
+          rarityRank: { type: 'integer', min: 1 },
+          traits: { type: 'array' }
+        }
+      },
+      price: {
+        type: 'object',
+        properties: {
+          amount: { type: 'number', min: 0 },
+          currency: { type: 'string', enum: ['ETH', 'WETH', 'USDC', 'APE'] },
+          usdValue: { type: 'number', min: 0 }
+        }
+      },
+      from: { type: 'string', format: 'ethereum_address' },
+      to: { type: 'string', format: 'ethereum_address' },
+      royalty: {
+        type: 'object',
+        properties: {
+          recipient: { type: 'string', format: 'ethereum_address' },
+          amount: { type: 'number', min: 0 },
+          percentage: { type: 'number', min: 0, max: 10 }
+        }
+      },
+      marketplaceFee: { type: 'number', min: 0 }
+    }
+  });
+
+  console.log('Generated NFT activity:', result.data.length);
+
+  // Analyze by event type
+  const events: any = {};
+  result.data.forEach((activity: any) => {
+    events[activity.eventType] = (events[activity.eventType] || 0) + 1;
+  });
+  console.log('Activity by type:', events);
+
+  // Top marketplaces by volume
+  const marketplaces: any = {};
+  result.data.forEach((activity: any) => {
+    if (activity.price) {
+      marketplaces[activity.marketplace] =
+        (marketplaces[activity.marketplace] || 0) + activity.price.usdValue;
+    }
+  });
+  console.log('Volume by marketplace:', marketplaces);
+
+  return result;
+}
+
+/**
+ * Example 5: Generate MEV transaction patterns
+ * Advanced MEV extraction and sandwich attack simulations
+ */
+async function generateMEVPatterns() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateStructured({
+    count: 1000,
+    schema: {
+      bundleId: { type: 'string', format: 'uuid' },
+      blockNumber: { type: 'integer', min: 18000000 },
+      timestamp: { type: 'datetime', required: true },
+      mevType: {
+        type: 'string',
+        enum: ['sandwich', 'arbitrage', 'liquidation', 'jit', 'backrun', 'frontrun']
+      },
+      bundleTransactions: {
+        type: 'array',
+        minItems: 1,
+        maxItems: 10,
+        items: {
+          type: 'object',
+          properties: {
+            txHash: { type: 'string' },
+            position: { type: 'integer' },
+            type: { type: 'string', enum: ['frontrun', 'victim', 'backrun'] },
+            from: { type: 'string' },
+            to: { type: 'string' },
+            value: { type: 'number' },
+            gasPrice: { type: 'number' }
+          }
+        }
+      },
+      targetProtocol: {
+        type: 'string',
+        enum: ['uniswap_v2', 'uniswap_v3', 'sushiswap', 'curve', 'balancer', 'aave', 'compound']
+      },
+      profit: {
+        type: 'object',
+        properties: {
+          gross: { type: 'number' },
+          gasCost: { type: 'number' },
+          net: { type: 'number' },
+          roi: { type: 'number' }
+        }
+      },
+      victimTx: {
+        type: 'object',
+        properties: {
+          hash: { type: 'string' },
+          expectedSlippage: { type: 'number' },
+          actualSlippage: { type: 'number' },
+          lossUSD: { type: 'number' }
+        }
+      },
+      mevBot: {
+        type: 'object',
+        properties: {
+          address: { type: 'string', format: 'ethereum_address' },
+          operator: { type: 'string' },
+          flashbotRelay: { type: 'boolean' },
+          privateTx: { type: 'boolean' }
+        }
+      },
+      complexity: { type: 'integer', min: 1, max: 10 },
+      executionTimeMs: { type: 'number', min: 10, max: 5000 }
+    }
+  });
+
+  console.log('Generated MEV patterns:', result.data.length);
+
+  // Analyze MEV types
+  const types: any = {};
+  result.data.forEach((mev: any) => {
+    types[mev.mevType] = (types[mev.mevType] || 0) + 1;
+  });
+  console.log('MEV by type:', types);
+
+  // Total profit extracted
+  const totalProfit = result.data.reduce((sum: number, mev: any) =>
+    sum + mev.profit.net, 0);
+  console.log(`Total MEV extracted: $${totalProfit.toFixed(2)}`);
+
+  return result;
+}
+
+/**
+ * Example 6: Generate block production data
+ * Includes validator performance and block building
+ */
+async function generateBlockData() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateTimeSeries({
+    count: 7200, // ~24 hours of blocks (12s block time)
+    interval: '12s',
+    startDate: new Date(Date.now() - 24 * 60 * 60 * 1000),
+    metrics: ['gasUsed', 'baseFee', 'mevReward', 'transactionCount'],
+    trend: 'stable',
+    seasonality: true,
+    noise: 0.15,
+    schema: {
+      blockNumber: { type: 'integer', min: 18000000, required: true },
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      hash: { type: 'string', format: 'block_hash' },
+      parentHash: { type: 'string', format: 'block_hash' },
+      proposer: { type: 'string', format: 'ethereum_address' },
+      validator: {
+        type: 'object',
+        properties: {
+          index: { type: 'integer' },
+          balance: { type: 'number' },
+          effectiveBalance: { type: 'number', default: 32 },
+          slashed: { type: 'boolean', default: false }
+        }
+      },
+      transactions: {
+        type: 'object',
+        properties: {
+          count: { type: 'integer', min: 0, max: 300 },
+          totalValue: { type: 'number' },
+          totalFees: { type: 'number' },
+          internalTxs: { type: 'integer' }
+        }
+      },
+      gas: {
+        type: 'object',
+        properties: {
+          used: { type: 'integer', min: 0, max: 30000000 },
+          limit: { type: 'integer', default: 30000000 },
+          utilization: { type: 'number', min: 0, max: 100 },
+          baseFee: { type: 'number', min: 1 },
+          avgPriorityFee: { type: 'number' }
+        }
+      },
+      mev: {
+        type: 'object',
+        properties: {
+          bundles: { type: 'integer', min: 0 },
+          reward: { type: 'number', min: 0 },
+          flashbotsTx: { type: 'integer', min: 0 }
+        }
+      },
+      size: { type: 'integer', min: 1000 },
+      difficulty: { type: 'string' },
+      extraData: { type: 'string' },
+      blockReward: { type: 'number', min: 0 }
+    }
+  });
+
+  console.log('Generated block data:', result.data.length);
+
+  // Calculate average block stats
+  const avgGasUsed = result.data.reduce((sum: number, block: any) =>
+    sum + block.gas.used, 0) / result.data.length;
+  const avgTxCount = result.data.reduce((sum: number, block: any) =>
+    sum + block.transactions.count, 0) / result.data.length;
+
+  console.log('Average block statistics:');
+  console.log(`  Gas used: ${avgGasUsed.toFixed(0)}`);
+  console.log(`  Transactions: ${avgTxCount.toFixed(0)}`);
+
+  return result;
+}
+
+/**
+ * Example 7: Generate smart contract deployment patterns
+ * Tracks contract creation and verification
+ */
+async function generateContractDeployments() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateEvents({
+    count: 1000,
+    eventTypes: ['erc20', 'erc721', 'erc1155', 'proxy', 'defi', 'custom'],
+    distribution: 'uniform',
+    timeRange: {
+      start: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+      end: new Date()
+    },
+    userCount: 500,
+    schema: {
+      txHash: { type: 'string', format: 'transaction_hash' },
+      blockNumber: { type: 'integer', min: 18000000 },
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      deployer: { type: 'string', format: 'ethereum_address' },
+      contractAddress: { type: 'string', format: 'ethereum_address' },
+      contractType: {
+        type: 'string',
+        enum: ['token', 'nft', 'defi', 'dao', 'bridge', 'oracle', 'gaming', 'other']
+      },
+      standard: { type: 'string', enum: ['erc20', 'erc721', 'erc1155', 'erc4626', 'custom'] },
+      bytecode: { type: 'string' },
+      bytecodeSize: { type: 'integer', min: 100, max: 24576 },
+      constructorArgs: { type: 'array' },
+      verified: { type: 'boolean' },
+      verificationDate: { type: 'datetime' },
+      compiler: {
+        type: 'object',
+        properties: {
+          version: { type: 'string' },
+          optimization: { type: 'boolean' },
+          runs: { type: 'integer', default: 200 }
+        }
+      },
+      proxy: {
+        type: 'object',
+        properties: {
+          isProxy: { type: 'boolean' },
+          implementation: { type: 'string' },
+          proxyType: { type: 'string', enum: ['transparent', 'uups', 'beacon', 'none'] }
+        }
+      },
+      gasUsed: { type: 'integer', min: 100000 },
+      deploymentCost: { type: 'number', min: 0 },
+      activity: {
+        type: 'object',
+        properties: {
+          uniqueUsers: { type: 'integer', min: 0 },
+          totalTxs: { type: 'integer', min: 0 },
+          totalVolume: { type: 'number', min: 0 }
+        }
+      }
+    }
+  });
+
+  console.log('Generated contract deployments:', result.data.length);
+
+  // Analyze by type
+  const types: any = {};
+  result.data.forEach((contract: any) => {
+    types[contract.contractType] = (types[contract.contractType] || 0) + 1;
+  });
+  console.log('Deployments by type:', types);
+
+  const verified = result.data.filter((c: any) => c.verified).length;
+  console.log(`Verification rate: ${(verified / result.data.length * 100).toFixed(1)}%`);
+
+  return result;
+}
+
+/**
+ * Example 8: Generate cross-chain bridge activity
+ * Simulates asset transfers between blockchains
+ */
+async function generateBridgeActivity() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateEvents({
+    count: 2000,
+    eventTypes: ['deposit', 'withdraw', 'relay'],
+    distribution: 'poisson',
+    timeRange: {
+      start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+      end: new Date()
+    },
+    userCount: 1000,
+    schema: {
+      bridgeTxId: { type: 'string', format: 'uuid' },
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      bridge: {
+        type: 'string',
+        enum: ['stargate', 'hop', 'across', 'synapse', 'multichain', 'wormhole', 'layerzero']
+      },
+      sourceChain: {
+        type: 'string',
+        enum: ['ethereum', 'polygon', 'arbitrum', 'optimism', 'avalanche', 'bsc']
+      },
+      destinationChain: {
+        type: 'string',
+        enum: ['ethereum', 'polygon', 'arbitrum', 'optimism', 'avalanche', 'bsc']
+      },
+      user: { type: 'string', format: 'ethereum_address' },
+      asset: { type: 'string', enum: ['ETH', 'USDC', 'USDT', 'DAI', 'WBTC'] },
+      amount: { type: 'number', min: 1 },
+      amountUSD: { type: 'number', min: 1 },
+      fees: {
+        type: 'object',
+        properties: {
+          sourceGas: { type: 'number' },
+          bridgeFee: { type: 'number' },
+          destinationGas: { type: 'number' },
+          totalFee: { type: 'number' }
+        }
+      },
+      status: {
+        type: 'string',
+        enum: ['pending', 'relaying', 'completed', 'failed', 'refunded']
+      },
+      sourceTxHash: { type: 'string', format: 'transaction_hash' },
+      destinationTxHash: { type: 'string', format: 'transaction_hash' },
+      completionTime: { type: 'number', min: 60, max: 3600 }, // seconds
+      securityDelay: { type: 'number', min: 0, max: 86400 }
+    }
+  });
+
+  console.log('Generated bridge activity:', result.data.length);
+
+  // Analyze bridge usage
+  const bridges: any = {};
+  result.data.forEach((tx: any) => {
+    bridges[tx.bridge] = (bridges[tx.bridge] || 0) + 1;
+  });
+  console.log('Usage by bridge:', bridges);
+
+  // Calculate success rate
+  const completed = result.data.filter((tx: any) => tx.status === 'completed').length;
+  console.log(`Success rate: ${(completed / result.data.length * 100).toFixed(1)}%`);
+
+  return result;
+}
+
+/**
+ * Run all blockchain data examples
+ */
+export async function runBlockchainDataExamples() {
+  console.log('=== Blockchain and On-Chain Data Generation Examples ===\n');
+
+  console.log('Example 1: Transaction Patterns');
+  await generateTransactionPatterns();
+  console.log('\n---\n');
+
+  console.log('Example 2: Wallet Behavior');
+  await generateWalletBehavior();
+  console.log('\n---\n');
+
+  console.log('Example 3: Token Transfers');
+  await generateTokenTransfers();
+  console.log('\n---\n');
+
+  console.log('Example 4: NFT Activity');
+  await generateNFTActivity();
+  console.log('\n---\n');
+
+  console.log('Example 5: MEV Patterns');
+  await generateMEVPatterns();
+  console.log('\n---\n');
+
+  console.log('Example 6: Block Production Data');
+  await generateBlockData();
+  console.log('\n---\n');
+
+  console.log('Example 7: Contract Deployments');
+  await generateContractDeployments();
+  console.log('\n---\n');
+
+  console.log('Example 8: Bridge Activity');
+  await generateBridgeActivity();
+}
+
+// Export individual examples
+export {
+  generateTransactionPatterns,
+  generateWalletBehavior,
+  generateTokenTransfers,
+  generateNFTActivity,
+  generateMEVPatterns,
+  generateBlockData,
+  generateContractDeployments,
+  generateBridgeActivity
+};
+
+// Uncomment to run
+// runBlockchainDataExamples().catch(console.error);

npm/packages/agentic-synth/examples/crypto/defi-scenarios.d.ts

@@ -0,0 +1,59 @@
+/**
+ * DeFi Protocol Simulation and Scenario Generation
+ *
+ * Examples for generating realistic DeFi data including:
+ * - Yield farming returns and APY calculations
+ * - Liquidity provision scenarios
+ * - Impermanent loss simulations
+ * - Gas price variations and optimization
+ * - Smart contract interaction patterns
+ */
+/**
+ * Example 1: Generate yield farming scenarios
+ * Simulates various DeFi protocols and farming strategies
+ */
+declare function generateYieldFarmingData(): Promise<{
+    protocol: string;
+    data: unknown[];
+}[]>;
+/**
+ * Example 2: Simulate liquidity provision scenarios
+ * Includes LP token calculations and position management
+ */
+declare function generateLiquidityProvisionScenarios(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 3: Generate impermanent loss scenarios
+ * Detailed analysis of IL under different market conditions
+ */
+declare function generateImpermanentLossScenarios(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 4: Generate gas price data and optimization scenarios
+ * Critical for DeFi transaction cost analysis
+ */
+declare function generateGasPriceData(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 5: Generate smart contract interaction patterns
+ * Simulates complex DeFi transaction sequences
+ */
+declare function generateSmartContractInteractions(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 6: Generate lending/borrowing scenarios
+ * Simulates DeFi lending protocols like Aave and Compound
+ */
+declare function generateLendingScenarios(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 7: Generate staking rewards data
+ * Covers liquid staking and validator rewards
+ */
+declare function generateStakingRewards(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 8: Generate MEV (Maximal Extractable Value) scenarios
+ * Advanced DeFi strategy simulations
+ */
+declare function generateMEVScenarios(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Run all DeFi scenario examples
+ */
+export declare function runDeFiScenarioExamples(): Promise<void>;
+export { generateYieldFarmingData, generateLiquidityProvisionScenarios, generateImpermanentLossScenarios, generateGasPriceData, generateSmartContractInteractions, generateLendingScenarios, generateStakingRewards, generateMEVScenarios };
+//# sourceMappingURL=defi-scenarios.d.ts.map

npm/packages/agentic-synth/examples/crypto/defi-scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defi-scenarios.d.ts","sourceRoot":"","sources":["defi-scenarios.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;GAGG;AACH,iBAAe,wBAAwB;;;KA+CtC;AAED;;;GAGG;AACH,iBAAe,mCAAmC,oEAqFjD;AAED;;;GAGG;AACH,iBAAe,gCAAgC,oEAuD9C;AAED;;;GAGG;AACH,iBAAe,oBAAoB,oEA+DlC;AAED;;;GAGG;AACH,iBAAe,iCAAiC,oEAkF/C;AAED;;;GAGG;AACH,iBAAe,wBAAwB,oEAwEtC;AAED;;;GAGG;AACH,iBAAe,sBAAsB,oEA6CpC;AAED;;;GAGG;AACH,iBAAe,oBAAoB,oEAiDlC;AAED;;GAEG;AACH,wBAAsB,uBAAuB,kBAiC5C;AAGD,OAAO,EACL,wBAAwB,EACxB,mCAAmC,EACnC,gCAAgC,EAChC,oBAAoB,EACpB,iCAAiC,EACjC,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACrB,CAAC"}

npm/packages/agentic-synth/examples/crypto/defi-scenarios.js

@@ -0,0 +1,549 @@
+"use strict";
+/**
+ * DeFi Protocol Simulation and Scenario Generation
+ *
+ * Examples for generating realistic DeFi data including:
+ * - Yield farming returns and APY calculations
+ * - Liquidity provision scenarios
+ * - Impermanent loss simulations
+ * - Gas price variations and optimization
+ * - Smart contract interaction patterns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeFiScenarioExamples = runDeFiScenarioExamples;
+exports.generateYieldFarmingData = generateYieldFarmingData;
+exports.generateLiquidityProvisionScenarios = generateLiquidityProvisionScenarios;
+exports.generateImpermanentLossScenarios = generateImpermanentLossScenarios;
+exports.generateGasPriceData = generateGasPriceData;
+exports.generateSmartContractInteractions = generateSmartContractInteractions;
+exports.generateLendingScenarios = generateLendingScenarios;
+exports.generateStakingRewards = generateStakingRewards;
+exports.generateMEVScenarios = generateMEVScenarios;
+const index_js_1 = require("../../src/index.js");
+/**
+ * Example 1: Generate yield farming scenarios
+ * Simulates various DeFi protocols and farming strategies
+ */
+async function generateYieldFarmingData() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini',
+        apiKey: process.env.GEMINI_API_KEY
+    });
+    const protocols = ['aave', 'compound', 'curve', 'convex', 'yearn'];
+    const results = [];
+    for (const protocol of protocols) {
+        const result = await synth.generateTimeSeries({
+            count: 720, // 30 days, hourly data
+            interval: '1h',
+            startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+            metrics: ['apy', 'tvl', 'dailyRewards', 'userCount'],
+            trend: protocol === 'aave' ? 'up' : 'stable',
+            seasonality: true,
+            noise: 0.1,
+            schema: {
+                timestamp: { type: 'datetime', format: 'iso8601' },
+                protocol: { type: 'string', default: protocol },
+                pool: { type: 'string', enum: ['USDC-USDT', 'ETH-USDC', 'WBTC-ETH', 'DAI-USDC'] },
+                apy: { type: 'number', min: 0.1, max: 500 }, // 0.1% to 500%
+                baseAPY: { type: 'number', min: 0.1, max: 50 },
+                rewardAPY: { type: 'number', min: 0, max: 450 },
+                tvl: { type: 'number', min: 1000000 },
+                dailyRewards: { type: 'number', min: 0 },
+                userCount: { type: 'integer', min: 100 },
+                depositFee: { type: 'number', min: 0, max: 1 },
+                withdrawalFee: { type: 'number', min: 0, max: 1 },
+                performanceFee: { type: 'number', min: 0, max: 20 }
+            },
+            constraints: {
+                custom: [
+                    'apy = baseAPY + rewardAPY',
+                    'dailyRewards proportional to tvl',
+                    'APY inversely related to TVL (dilution)',
+                    'Weekend APY typically lower due to reduced activity'
+                ]
+            }
+        });
+        results.push({ protocol, data: result.data });
+        console.log(`Generated ${protocol} yield farming data: ${result.data.length} records`);
+    }
+    return results;
+}
+/**
+ * Example 2: Simulate liquidity provision scenarios
+ * Includes LP token calculations and position management
+ */
+async function generateLiquidityProvisionScenarios() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateStructured({
+        count: 1000, // 1000 LP positions
+        schema: {
+            positionId: { type: 'string', format: 'uuid' },
+            provider: { type: 'string', required: true },
+            walletAddress: { type: 'string', format: 'ethereum_address' },
+            dex: { type: 'string', enum: ['uniswap_v2', 'uniswap_v3', 'sushiswap', 'curve', 'balancer'] },
+            pool: { type: 'string', enum: ['ETH-USDC', 'WBTC-ETH', 'DAI-USDC', 'stETH-ETH'] },
+            entryDate: { type: 'datetime', required: true },
+            exitDate: { type: 'datetime' },
+            position: {
+                type: 'object',
+                required: true,
+                properties: {
+                    tokenA: { type: 'string' },
+                    tokenB: { type: 'string' },
+                    amountA: { type: 'number', min: 0 },
+                    amountB: { type: 'number', min: 0 },
+                    shareOfPool: { type: 'number', min: 0, max: 100 },
+                    lpTokens: { type: 'number', min: 0 }
+                }
+            },
+            entryPrice: {
+                type: 'object',
+                properties: {
+                    tokenA_USD: { type: 'number' },
+                    tokenB_USD: { type: 'number' },
+                    ratio: { type: 'number' }
+                }
+            },
+            currentPrice: {
+                type: 'object',
+                properties: {
+                    tokenA_USD: { type: 'number' },
+                    tokenB_USD: { type: 'number' },
+                    ratio: { type: 'number' }
+                }
+            },
+            returns: {
+                type: 'object',
+                properties: {
+                    feesEarned: { type: 'number', min: 0 },
+                    impermanentLoss: { type: 'number', min: -100, max: 0 },
+                    totalReturn: { type: 'number' },
+                    returnPercent: { type: 'number' },
+                    annualizedReturn: { type: 'number' }
+                }
+            },
+            riskMetrics: {
+                type: 'object',
+                properties: {
+                    volatility: { type: 'number', min: 0, max: 200 },
+                    maxDrawdown: { type: 'number', min: 0, max: 100 },
+                    sharpeRatio: { type: 'number' }
+                }
+            }
+        },
+        constraints: {
+            custom: [
+                'exitDate >= entryDate or null',
+                'impermanentLoss calculated based on price divergence',
+                'totalReturn = feesEarned + impermanentLoss',
+                'feesEarned based on volume and pool share',
+                'Uniswap V3 positions can have concentrated liquidity ranges'
+            ]
+        }
+    });
+    console.log('Generated LP scenarios:', result.data.length);
+    // Analyze returns
+    const avgIL = result.data.reduce((sum, pos) => sum + pos.returns.impermanentLoss, 0) / result.data.length;
+    const avgFees = result.data.reduce((sum, pos) => sum + pos.returns.feesEarned, 0) / result.data.length;
+    console.log(`Average Impermanent Loss: ${avgIL.toFixed(2)}%`);
+    console.log(`Average Fees Earned: $${avgFees.toFixed(2)}`);
+    return result;
+}
+/**
+ * Example 3: Generate impermanent loss scenarios
+ * Detailed analysis of IL under different market conditions
+ */
+async function generateImpermanentLossScenarios() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateTimeSeries({
+        count: 1000,
+        interval: '1h',
+        startDate: new Date(Date.now() - 42 * 24 * 60 * 60 * 1000), // 42 days
+        metrics: ['priceRatio', 'impermanentLoss', 'hodlValue', 'lpValue', 'feesEarned'],
+        trend: 'volatile',
+        seasonality: false,
+        noise: 0.2,
+        schema: {
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            scenario: { type: 'string', enum: ['bull_market', 'bear_market', 'sideways', 'high_volatility'] },
+            initialRatio: { type: 'number', default: 1 },
+            priceRatio: { type: 'number', min: 0.1, max: 10 },
+            priceChange: { type: 'number' },
+            impermanentLoss: { type: 'number', min: -100, max: 0 },
+            impermanentLossPercent: { type: 'number' },
+            hodlValue: { type: 'number', min: 0 },
+            lpValue: { type: 'number', min: 0 },
+            feesEarned: { type: 'number', min: 0 },
+            netProfit: { type: 'number' },
+            breakEvenFeeRate: { type: 'number' },
+            recommendation: {
+                type: 'string',
+                enum: ['stay', 'exit', 'rebalance', 'wait']
+            }
+        },
+        constraints: {
+            custom: [
+                'IL formula: 2 * sqrt(priceRatio) / (1 + priceRatio) - 1',
+                'lpValue = hodlValue + impermanentLoss + feesEarned',
+                'netProfit = lpValue - hodlValue',
+                'Higher price divergence = higher IL',
+                'Fees can compensate for IL in high-volume pools'
+            ]
+        }
+    });
+    console.log('Generated impermanent loss scenarios:', result.data.length);
+    // Find worst IL scenario
+    const worstIL = result.data.reduce((worst, current) => current.impermanentLoss < worst.impermanentLoss ? current : worst);
+    console.log('Worst IL scenario:', {
+        timestamp: worstIL.timestamp,
+        priceRatio: worstIL.priceRatio,
+        IL: `${worstIL.impermanentLossPercent}%`
+    });
+    return result;
+}
+/**
+ * Example 4: Generate gas price data and optimization scenarios
+ * Critical for DeFi transaction cost analysis
+ */
+async function generateGasPriceData() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateTimeSeries({
+        count: 10080, // 1 week, minute-by-minute
+        interval: '1m',
+        startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+        metrics: ['baseFee', 'priorityFee', 'maxFee', 'gasUsed'],
+        trend: 'stable',
+        seasonality: true, // Network congestion patterns
+        noise: 0.25, // High volatility in gas prices
+        schema: {
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            network: { type: 'string', enum: ['ethereum', 'polygon', 'arbitrum', 'optimism', 'base'] },
+            block: { type: 'integer', min: 18000000 },
+            baseFee: { type: 'number', min: 1, max: 500 }, // Gwei
+            priorityFee: { type: 'number', min: 0.1, max: 100 },
+            maxFee: { type: 'number', min: 1, max: 600 },
+            gasUsed: { type: 'integer', min: 21000, max: 30000000 },
+            blockUtilization: { type: 'number', min: 0, max: 100 },
+            pendingTxCount: { type: 'integer', min: 0 },
+            congestionLevel: {
+                type: 'string',
+                enum: ['low', 'medium', 'high', 'extreme']
+            },
+            estimatedCost: {
+                type: 'object',
+                properties: {
+                    transfer: { type: 'number' }, // Simple ETH transfer
+                    swap: { type: 'number' }, // DEX swap
+                    addLiquidity: { type: 'number' },
+                    removeLiquidity: { type: 'number' },
+                    complexDeFi: { type: 'number' } // Multi-protocol interaction
+                }
+            }
+        },
+        constraints: {
+            custom: [
+                'maxFee >= baseFee + priorityFee',
+                'Higher baseFee during peak hours (EST afternoon)',
+                'Weekend gas typically 20-30% lower',
+                'NFT mint events cause temporary spikes',
+                'L2 gas prices 10-100x cheaper than mainnet'
+            ]
+        }
+    });
+    console.log('Generated gas price data:', result.data.length);
+    // Analyze gas patterns
+    const avgGas = result.data.reduce((sum, d) => sum + d.baseFee, 0) / result.data.length;
+    const maxGas = Math.max(...result.data.map((d) => d.baseFee));
+    const minGas = Math.min(...result.data.map((d) => d.baseFee));
+    console.log('Gas statistics (Gwei):');
+    console.log(`  Average: ${avgGas.toFixed(2)}`);
+    console.log(`  Max: ${maxGas.toFixed(2)}`);
+    console.log(`  Min: ${minGas.toFixed(2)}`);
+    return result;
+}
+/**
+ * Example 5: Generate smart contract interaction patterns
+ * Simulates complex DeFi transaction sequences
+ */
+async function generateSmartContractInteractions() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateEvents({
+        count: 5000,
+        eventTypes: [
+            'approve',
+            'swap',
+            'addLiquidity',
+            'removeLiquidity',
+            'stake',
+            'unstake',
+            'claim',
+            'compound',
+            'flashloan',
+            'arbitrage'
+        ],
+        distribution: 'poisson',
+        timeRange: {
+            start: new Date(Date.now() - 24 * 60 * 60 * 1000),
+            end: new Date()
+        },
+        userCount: 2000,
+        schema: {
+            txHash: { type: 'string', format: 'transaction_hash' },
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            walletAddress: { type: 'string', format: 'ethereum_address' },
+            contractAddress: { type: 'string', format: 'ethereum_address' },
+            protocol: {
+                type: 'string',
+                enum: ['uniswap', 'aave', 'compound', 'curve', 'yearn', 'maker', 'lido']
+            },
+            function: { type: 'string', required: true },
+            gasUsed: { type: 'integer', min: 21000 },
+            gasPrice: { type: 'number', min: 1 },
+            txCost: { type: 'number', min: 0 },
+            value: { type: 'number', min: 0 },
+            status: { type: 'string', enum: ['success', 'failed', 'pending'] },
+            failureReason: { type: 'string' },
+            interactionSequence: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        step: { type: 'integer' },
+                        action: { type: 'string' },
+                        contract: { type: 'string' }
+                    }
+                }
+            },
+            internalTxs: { type: 'integer', min: 0, max: 50 },
+            tokensTransferred: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        token: { type: 'string' },
+                        amount: { type: 'number' },
+                        from: { type: 'string' },
+                        to: { type: 'string' }
+                    }
+                }
+            }
+        }
+    });
+    console.log('Generated smart contract interactions:', result.data.length);
+    // Analyze by protocol
+    const protocols = {};
+    result.data.forEach((tx) => {
+        protocols[tx.protocol] = (protocols[tx.protocol] || 0) + 1;
+    });
+    console.log('Interactions by protocol:', protocols);
+    // Failure rate
+    const failures = result.data.filter((tx) => tx.status === 'failed').length;
+    console.log(`Failure rate: ${(failures / result.data.length * 100).toFixed(2)}%`);
+    return result;
+}
+/**
+ * Example 6: Generate lending/borrowing scenarios
+ * Simulates DeFi lending protocols like Aave and Compound
+ */
+async function generateLendingScenarios() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateStructured({
+        count: 500,
+        schema: {
+            positionId: { type: 'string', format: 'uuid' },
+            walletAddress: { type: 'string', format: 'ethereum_address' },
+            protocol: { type: 'string', enum: ['aave_v3', 'compound', 'maker', 'euler'] },
+            positionType: { type: 'string', enum: ['lender', 'borrower', 'both'] },
+            openedAt: { type: 'datetime', required: true },
+            collateral: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        asset: { type: 'string', enum: ['ETH', 'WBTC', 'USDC', 'DAI', 'stETH'] },
+                        amount: { type: 'number', min: 0 },
+                        valueUSD: { type: 'number', min: 0 },
+                        collateralFactor: { type: 'number', min: 0, max: 0.95 }
+                    }
+                }
+            },
+            borrowed: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        asset: { type: 'string' },
+                        amount: { type: 'number', min: 0 },
+                        valueUSD: { type: 'number', min: 0 },
+                        interestRate: { type: 'number', min: 0, max: 50 },
+                        rateMode: { type: 'string', enum: ['stable', 'variable'] }
+                    }
+                }
+            },
+            healthFactor: { type: 'number', min: 0, max: 5 },
+            ltv: { type: 'number', min: 0, max: 100 }, // Loan-to-Value
+            liquidationThreshold: { type: 'number', min: 0, max: 100 },
+            liquidationPrice: { type: 'number' },
+            netAPY: { type: 'number' },
+            totalInterestPaid: { type: 'number', min: 0 },
+            totalInterestEarned: { type: 'number', min: 0 },
+            riskLevel: { type: 'string', enum: ['safe', 'moderate', 'risky', 'critical'] },
+            autoLiquidate: { type: 'boolean' }
+        },
+        constraints: {
+            custom: [
+                'healthFactor = totalCollateral / totalBorrowed',
+                'healthFactor < 1.0 = liquidation risk',
+                'LTV = totalBorrowed / totalCollateral * 100',
+                'liquidationPrice based on collateral type',
+                'Higher LTV = higher risk = higher potential liquidation'
+            ]
+        }
+    });
+    console.log('Generated lending scenarios:', result.data.length);
+    // Risk analysis
+    const riskLevels = {};
+    result.data.forEach((pos) => {
+        riskLevels[pos.riskLevel] = (riskLevels[pos.riskLevel] || 0) + 1;
+    });
+    console.log('Positions by risk level:', riskLevels);
+    const atRisk = result.data.filter((pos) => pos.healthFactor < 1.2).length;
+    console.log(`Positions at liquidation risk (HF < 1.2): ${atRisk}`);
+    return result;
+}
+/**
+ * Example 7: Generate staking rewards data
+ * Covers liquid staking and validator rewards
+ */
+async function generateStakingRewards() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateTimeSeries({
+        count: 365, // 1 year, daily
+        interval: '1d',
+        startDate: new Date(Date.now() - 365 * 24 * 60 * 60 * 1000),
+        metrics: ['stakingAPR', 'totalStaked', 'dailyRewards', 'validatorCount'],
+        trend: 'stable',
+        seasonality: false,
+        noise: 0.05,
+        schema: {
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            protocol: {
+                type: 'string',
+                enum: ['lido', 'rocket_pool', 'frax', 'stakewise', 'native_eth']
+            },
+            stakingAPR: { type: 'number', min: 2, max: 20 },
+            baseAPR: { type: 'number', min: 2, max: 8 },
+            bonusAPR: { type: 'number', min: 0, max: 12 },
+            totalStaked: { type: 'number', min: 1000000 },
+            totalStakedETH: { type: 'number', min: 10000 },
+            dailyRewards: { type: 'number', min: 0 },
+            validatorCount: { type: 'integer', min: 100 },
+            averageValidatorBalance: { type: 'number', default: 32 },
+            networkParticipation: { type: 'number', min: 0, max: 100 },
+            slashingEvents: { type: 'integer', min: 0, max: 5 },
+            fees: {
+                type: 'object',
+                properties: {
+                    protocolFee: { type: 'number', min: 0, max: 10 },
+                    nodeOperatorFee: { type: 'number', min: 0, max: 15 }
+                }
+            }
+        }
+    });
+    console.log('Generated staking rewards data:', result.data.length);
+    console.log('Average APR:', (result.data.reduce((sum, d) => sum + d.stakingAPR, 0) / result.data.length).toFixed(2) + '%');
+    return result;
+}
+/**
+ * Example 8: Generate MEV (Maximal Extractable Value) scenarios
+ * Advanced DeFi strategy simulations
+ */
+async function generateMEVScenarios() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateEvents({
+        count: 1000,
+        eventTypes: ['sandwich', 'arbitrage', 'liquidation', 'jit_liquidity', 'nft_snipe'],
+        distribution: 'poisson',
+        timeRange: {
+            start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+            end: new Date()
+        },
+        userCount: 200, // MEV bots
+        schema: {
+            txHash: { type: 'string', format: 'transaction_hash' },
+            blockNumber: { type: 'integer', min: 18000000 },
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            mevType: {
+                type: 'string',
+                enum: ['sandwich', 'arbitrage', 'liquidation', 'jit_liquidity', 'backrun']
+            },
+            botAddress: { type: 'string', format: 'ethereum_address' },
+            targetTx: { type: 'string', format: 'transaction_hash' },
+            profit: { type: 'number', min: -1000, max: 100000 },
+            profitUSD: { type: 'number' },
+            gasCost: { type: 'number', min: 0 },
+            netProfit: { type: 'number' },
+            roi: { type: 'number' },
+            complexity: { type: 'integer', min: 1, max: 10 },
+            involvedProtocols: {
+                type: 'array',
+                items: { type: 'string' }
+            },
+            flashloanUsed: { type: 'boolean' },
+            flashloanAmount: { type: 'number' },
+            executionTime: { type: 'number', min: 1, max: 1000 } // ms
+        }
+    });
+    console.log('Generated MEV scenarios:', result.data.length);
+    const totalProfit = result.data.reduce((sum, mev) => sum + mev.netProfit, 0);
+    const profitableOps = result.data.filter((mev) => mev.netProfit > 0).length;
+    console.log(`Total MEV extracted: $${totalProfit.toFixed(2)}`);
+    console.log(`Profitable operations: ${profitableOps}/${result.data.length} (${(profitableOps / result.data.length * 100).toFixed(1)}%)`);
+    return result;
+}
+/**
+ * Run all DeFi scenario examples
+ */
+async function runDeFiScenarioExamples() {
+    console.log('=== DeFi Protocol Simulation Examples ===\n');
+    console.log('Example 1: Yield Farming Data');
+    await generateYieldFarmingData();
+    console.log('\n---\n');
+    console.log('Example 2: Liquidity Provision Scenarios');
+    await generateLiquidityProvisionScenarios();
+    console.log('\n---\n');
+    console.log('Example 3: Impermanent Loss Scenarios');
+    await generateImpermanentLossScenarios();
+    console.log('\n---\n');
+    console.log('Example 4: Gas Price Data');
+    await generateGasPriceData();
+    console.log('\n---\n');
+    console.log('Example 5: Smart Contract Interactions');
+    await generateSmartContractInteractions();
+    console.log('\n---\n');
+    console.log('Example 6: Lending/Borrowing Scenarios');
+    await generateLendingScenarios();
+    console.log('\n---\n');
+    console.log('Example 7: Staking Rewards');
+    await generateStakingRewards();
+    console.log('\n---\n');
+    console.log('Example 8: MEV Scenarios');
+    await generateMEVScenarios();
+}
+// Uncomment to run
+// runDeFiScenarioExamples().catch(console.error);
+//# sourceMappingURL=defi-scenarios.js.map

npm/packages/agentic-synth/examples/crypto/defi-scenarios.ts

@@ -0,0 +1,611 @@
+/**
+ * DeFi Protocol Simulation and Scenario Generation
+ *
+ * Examples for generating realistic DeFi data including:
+ * - Yield farming returns and APY calculations
+ * - Liquidity provision scenarios
+ * - Impermanent loss simulations
+ * - Gas price variations and optimization
+ * - Smart contract interaction patterns
+ */
+
+import { createSynth } from '../../src/index.js';
+
+/**
+ * Example 1: Generate yield farming scenarios
+ * Simulates various DeFi protocols and farming strategies
+ */
+async function generateYieldFarmingData() {
+  const synth = createSynth({
+    provider: 'gemini',
+    apiKey: process.env.GEMINI_API_KEY
+  });
+
+  const protocols = ['aave', 'compound', 'curve', 'convex', 'yearn'];
+  const results = [];
+
+  for (const protocol of protocols) {
+    const result = await synth.generateTimeSeries({
+      count: 720, // 30 days, hourly data
+      interval: '1h',
+      startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+      metrics: ['apy', 'tvl', 'dailyRewards', 'userCount'],
+      trend: protocol === 'aave' ? 'up' : 'stable',
+      seasonality: true,
+      noise: 0.1,
+      schema: {
+        timestamp: { type: 'datetime', format: 'iso8601' },
+        protocol: { type: 'string', default: protocol },
+        pool: { type: 'string', enum: ['USDC-USDT', 'ETH-USDC', 'WBTC-ETH', 'DAI-USDC'] },
+        apy: { type: 'number', min: 0.1, max: 500 }, // 0.1% to 500%
+        baseAPY: { type: 'number', min: 0.1, max: 50 },
+        rewardAPY: { type: 'number', min: 0, max: 450 },
+        tvl: { type: 'number', min: 1000000 },
+        dailyRewards: { type: 'number', min: 0 },
+        userCount: { type: 'integer', min: 100 },
+        depositFee: { type: 'number', min: 0, max: 1 },
+        withdrawalFee: { type: 'number', min: 0, max: 1 },
+        performanceFee: { type: 'number', min: 0, max: 20 }
+      },
+      constraints: {
+        custom: [
+          'apy = baseAPY + rewardAPY',
+          'dailyRewards proportional to tvl',
+          'APY inversely related to TVL (dilution)',
+          'Weekend APY typically lower due to reduced activity'
+        ]
+      }
+    });
+
+    results.push({ protocol, data: result.data });
+    console.log(`Generated ${protocol} yield farming data: ${result.data.length} records`);
+  }
+
+  return results;
+}
+
+/**
+ * Example 2: Simulate liquidity provision scenarios
+ * Includes LP token calculations and position management
+ */
+async function generateLiquidityProvisionScenarios() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateStructured({
+    count: 1000, // 1000 LP positions
+    schema: {
+      positionId: { type: 'string', format: 'uuid' },
+      provider: { type: 'string', required: true },
+      walletAddress: { type: 'string', format: 'ethereum_address' },
+      dex: { type: 'string', enum: ['uniswap_v2', 'uniswap_v3', 'sushiswap', 'curve', 'balancer'] },
+      pool: { type: 'string', enum: ['ETH-USDC', 'WBTC-ETH', 'DAI-USDC', 'stETH-ETH'] },
+      entryDate: { type: 'datetime', required: true },
+      exitDate: { type: 'datetime' },
+      position: {
+        type: 'object',
+        required: true,
+        properties: {
+          tokenA: { type: 'string' },
+          tokenB: { type: 'string' },
+          amountA: { type: 'number', min: 0 },
+          amountB: { type: 'number', min: 0 },
+          shareOfPool: { type: 'number', min: 0, max: 100 },
+          lpTokens: { type: 'number', min: 0 }
+        }
+      },
+      entryPrice: {
+        type: 'object',
+        properties: {
+          tokenA_USD: { type: 'number' },
+          tokenB_USD: { type: 'number' },
+          ratio: { type: 'number' }
+        }
+      },
+      currentPrice: {
+        type: 'object',
+        properties: {
+          tokenA_USD: { type: 'number' },
+          tokenB_USD: { type: 'number' },
+          ratio: { type: 'number' }
+        }
+      },
+      returns: {
+        type: 'object',
+        properties: {
+          feesEarned: { type: 'number', min: 0 },
+          impermanentLoss: { type: 'number', min: -100, max: 0 },
+          totalReturn: { type: 'number' },
+          returnPercent: { type: 'number' },
+          annualizedReturn: { type: 'number' }
+        }
+      },
+      riskMetrics: {
+        type: 'object',
+        properties: {
+          volatility: { type: 'number', min: 0, max: 200 },
+          maxDrawdown: { type: 'number', min: 0, max: 100 },
+          sharpeRatio: { type: 'number' }
+        }
+      }
+    },
+    constraints: {
+      custom: [
+        'exitDate >= entryDate or null',
+        'impermanentLoss calculated based on price divergence',
+        'totalReturn = feesEarned + impermanentLoss',
+        'feesEarned based on volume and pool share',
+        'Uniswap V3 positions can have concentrated liquidity ranges'
+      ]
+    }
+  });
+
+  console.log('Generated LP scenarios:', result.data.length);
+
+  // Analyze returns
+  const avgIL = result.data.reduce((sum: number, pos: any) =>
+    sum + pos.returns.impermanentLoss, 0) / result.data.length;
+  const avgFees = result.data.reduce((sum: number, pos: any) =>
+    sum + pos.returns.feesEarned, 0) / result.data.length;
+
+  console.log(`Average Impermanent Loss: ${avgIL.toFixed(2)}%`);
+  console.log(`Average Fees Earned: $${avgFees.toFixed(2)}`);
+
+  return result;
+}
+
+/**
+ * Example 3: Generate impermanent loss scenarios
+ * Detailed analysis of IL under different market conditions
+ */
+async function generateImpermanentLossScenarios() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateTimeSeries({
+    count: 1000,
+    interval: '1h',
+    startDate: new Date(Date.now() - 42 * 24 * 60 * 60 * 1000), // 42 days
+    metrics: ['priceRatio', 'impermanentLoss', 'hodlValue', 'lpValue', 'feesEarned'],
+    trend: 'volatile',
+    seasonality: false,
+    noise: 0.2,
+    schema: {
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      scenario: { type: 'string', enum: ['bull_market', 'bear_market', 'sideways', 'high_volatility'] },
+      initialRatio: { type: 'number', default: 1 },
+      priceRatio: { type: 'number', min: 0.1, max: 10 },
+      priceChange: { type: 'number' },
+      impermanentLoss: { type: 'number', min: -100, max: 0 },
+      impermanentLossPercent: { type: 'number' },
+      hodlValue: { type: 'number', min: 0 },
+      lpValue: { type: 'number', min: 0 },
+      feesEarned: { type: 'number', min: 0 },
+      netProfit: { type: 'number' },
+      breakEvenFeeRate: { type: 'number' },
+      recommendation: {
+        type: 'string',
+        enum: ['stay', 'exit', 'rebalance', 'wait']
+      }
+    },
+    constraints: {
+      custom: [
+        'IL formula: 2 * sqrt(priceRatio) / (1 + priceRatio) - 1',
+        'lpValue = hodlValue + impermanentLoss + feesEarned',
+        'netProfit = lpValue - hodlValue',
+        'Higher price divergence = higher IL',
+        'Fees can compensate for IL in high-volume pools'
+      ]
+    }
+  });
+
+  console.log('Generated impermanent loss scenarios:', result.data.length);
+
+  // Find worst IL scenario
+  const worstIL = result.data.reduce((worst: any, current: any) =>
+    current.impermanentLoss < worst.impermanentLoss ? current : worst
+  );
+  console.log('Worst IL scenario:', {
+    timestamp: worstIL.timestamp,
+    priceRatio: worstIL.priceRatio,
+    IL: `${worstIL.impermanentLossPercent}%`
+  });
+
+  return result;
+}
+
+/**
+ * Example 4: Generate gas price data and optimization scenarios
+ * Critical for DeFi transaction cost analysis
+ */
+async function generateGasPriceData() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateTimeSeries({
+    count: 10080, // 1 week, minute-by-minute
+    interval: '1m',
+    startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+    metrics: ['baseFee', 'priorityFee', 'maxFee', 'gasUsed'],
+    trend: 'stable',
+    seasonality: true, // Network congestion patterns
+    noise: 0.25, // High volatility in gas prices
+    schema: {
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      network: { type: 'string', enum: ['ethereum', 'polygon', 'arbitrum', 'optimism', 'base'] },
+      block: { type: 'integer', min: 18000000 },
+      baseFee: { type: 'number', min: 1, max: 500 }, // Gwei
+      priorityFee: { type: 'number', min: 0.1, max: 100 },
+      maxFee: { type: 'number', min: 1, max: 600 },
+      gasUsed: { type: 'integer', min: 21000, max: 30000000 },
+      blockUtilization: { type: 'number', min: 0, max: 100 },
+      pendingTxCount: { type: 'integer', min: 0 },
+      congestionLevel: {
+        type: 'string',
+        enum: ['low', 'medium', 'high', 'extreme']
+      },
+      estimatedCost: {
+        type: 'object',
+        properties: {
+          transfer: { type: 'number' }, // Simple ETH transfer
+          swap: { type: 'number' },     // DEX swap
+          addLiquidity: { type: 'number' },
+          removeLiquidity: { type: 'number' },
+          complexDeFi: { type: 'number' } // Multi-protocol interaction
+        }
+      }
+    },
+    constraints: {
+      custom: [
+        'maxFee >= baseFee + priorityFee',
+        'Higher baseFee during peak hours (EST afternoon)',
+        'Weekend gas typically 20-30% lower',
+        'NFT mint events cause temporary spikes',
+        'L2 gas prices 10-100x cheaper than mainnet'
+      ]
+    }
+  });
+
+  console.log('Generated gas price data:', result.data.length);
+
+  // Analyze gas patterns
+  const avgGas = result.data.reduce((sum: number, d: any) =>
+    sum + d.baseFee, 0) / result.data.length;
+  const maxGas = Math.max(...result.data.map((d: any) => d.baseFee));
+  const minGas = Math.min(...result.data.map((d: any) => d.baseFee));
+
+  console.log('Gas statistics (Gwei):');
+  console.log(`  Average: ${avgGas.toFixed(2)}`);
+  console.log(`  Max: ${maxGas.toFixed(2)}`);
+  console.log(`  Min: ${minGas.toFixed(2)}`);
+
+  return result;
+}
+
+/**
+ * Example 5: Generate smart contract interaction patterns
+ * Simulates complex DeFi transaction sequences
+ */
+async function generateSmartContractInteractions() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateEvents({
+    count: 5000,
+    eventTypes: [
+      'approve',
+      'swap',
+      'addLiquidity',
+      'removeLiquidity',
+      'stake',
+      'unstake',
+      'claim',
+      'compound',
+      'flashloan',
+      'arbitrage'
+    ],
+    distribution: 'poisson',
+    timeRange: {
+      start: new Date(Date.now() - 24 * 60 * 60 * 1000),
+      end: new Date()
+    },
+    userCount: 2000,
+    schema: {
+      txHash: { type: 'string', format: 'transaction_hash' },
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      walletAddress: { type: 'string', format: 'ethereum_address' },
+      contractAddress: { type: 'string', format: 'ethereum_address' },
+      protocol: {
+        type: 'string',
+        enum: ['uniswap', 'aave', 'compound', 'curve', 'yearn', 'maker', 'lido']
+      },
+      function: { type: 'string', required: true },
+      gasUsed: { type: 'integer', min: 21000 },
+      gasPrice: { type: 'number', min: 1 },
+      txCost: { type: 'number', min: 0 },
+      value: { type: 'number', min: 0 },
+      status: { type: 'string', enum: ['success', 'failed', 'pending'] },
+      failureReason: { type: 'string' },
+      interactionSequence: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            step: { type: 'integer' },
+            action: { type: 'string' },
+            contract: { type: 'string' }
+          }
+        }
+      },
+      internalTxs: { type: 'integer', min: 0, max: 50 },
+      tokensTransferred: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            token: { type: 'string' },
+            amount: { type: 'number' },
+            from: { type: 'string' },
+            to: { type: 'string' }
+          }
+        }
+      }
+    }
+  });
+
+  console.log('Generated smart contract interactions:', result.data.length);
+
+  // Analyze by protocol
+  const protocols: any = {};
+  result.data.forEach((tx: any) => {
+    protocols[tx.protocol] = (protocols[tx.protocol] || 0) + 1;
+  });
+  console.log('Interactions by protocol:', protocols);
+
+  // Failure rate
+  const failures = result.data.filter((tx: any) => tx.status === 'failed').length;
+  console.log(`Failure rate: ${(failures / result.data.length * 100).toFixed(2)}%`);
+
+  return result;
+}
+
+/**
+ * Example 6: Generate lending/borrowing scenarios
+ * Simulates DeFi lending protocols like Aave and Compound
+ */
+async function generateLendingScenarios() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateStructured({
+    count: 500,
+    schema: {
+      positionId: { type: 'string', format: 'uuid' },
+      walletAddress: { type: 'string', format: 'ethereum_address' },
+      protocol: { type: 'string', enum: ['aave_v3', 'compound', 'maker', 'euler'] },
+      positionType: { type: 'string', enum: ['lender', 'borrower', 'both'] },
+      openedAt: { type: 'datetime', required: true },
+      collateral: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            asset: { type: 'string', enum: ['ETH', 'WBTC', 'USDC', 'DAI', 'stETH'] },
+            amount: { type: 'number', min: 0 },
+            valueUSD: { type: 'number', min: 0 },
+            collateralFactor: { type: 'number', min: 0, max: 0.95 }
+          }
+        }
+      },
+      borrowed: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            asset: { type: 'string' },
+            amount: { type: 'number', min: 0 },
+            valueUSD: { type: 'number', min: 0 },
+            interestRate: { type: 'number', min: 0, max: 50 },
+            rateMode: { type: 'string', enum: ['stable', 'variable'] }
+          }
+        }
+      },
+      healthFactor: { type: 'number', min: 0, max: 5 },
+      ltv: { type: 'number', min: 0, max: 100 }, // Loan-to-Value
+      liquidationThreshold: { type: 'number', min: 0, max: 100 },
+      liquidationPrice: { type: 'number' },
+      netAPY: { type: 'number' },
+      totalInterestPaid: { type: 'number', min: 0 },
+      totalInterestEarned: { type: 'number', min: 0 },
+      riskLevel: { type: 'string', enum: ['safe', 'moderate', 'risky', 'critical'] },
+      autoLiquidate: { type: 'boolean' }
+    },
+    constraints: {
+      custom: [
+        'healthFactor = totalCollateral / totalBorrowed',
+        'healthFactor < 1.0 = liquidation risk',
+        'LTV = totalBorrowed / totalCollateral * 100',
+        'liquidationPrice based on collateral type',
+        'Higher LTV = higher risk = higher potential liquidation'
+      ]
+    }
+  });
+
+  console.log('Generated lending scenarios:', result.data.length);
+
+  // Risk analysis
+  const riskLevels: any = {};
+  result.data.forEach((pos: any) => {
+    riskLevels[pos.riskLevel] = (riskLevels[pos.riskLevel] || 0) + 1;
+  });
+  console.log('Positions by risk level:', riskLevels);
+
+  const atRisk = result.data.filter((pos: any) => pos.healthFactor < 1.2).length;
+  console.log(`Positions at liquidation risk (HF < 1.2): ${atRisk}`);
+
+  return result;
+}
+
+/**
+ * Example 7: Generate staking rewards data
+ * Covers liquid staking and validator rewards
+ */
+async function generateStakingRewards() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateTimeSeries({
+    count: 365, // 1 year, daily
+    interval: '1d',
+    startDate: new Date(Date.now() - 365 * 24 * 60 * 60 * 1000),
+    metrics: ['stakingAPR', 'totalStaked', 'dailyRewards', 'validatorCount'],
+    trend: 'stable',
+    seasonality: false,
+    noise: 0.05,
+    schema: {
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      protocol: {
+        type: 'string',
+        enum: ['lido', 'rocket_pool', 'frax', 'stakewise', 'native_eth']
+      },
+      stakingAPR: { type: 'number', min: 2, max: 20 },
+      baseAPR: { type: 'number', min: 2, max: 8 },
+      bonusAPR: { type: 'number', min: 0, max: 12 },
+      totalStaked: { type: 'number', min: 1000000 },
+      totalStakedETH: { type: 'number', min: 10000 },
+      dailyRewards: { type: 'number', min: 0 },
+      validatorCount: { type: 'integer', min: 100 },
+      averageValidatorBalance: { type: 'number', default: 32 },
+      networkParticipation: { type: 'number', min: 0, max: 100 },
+      slashingEvents: { type: 'integer', min: 0, max: 5 },
+      fees: {
+        type: 'object',
+        properties: {
+          protocolFee: { type: 'number', min: 0, max: 10 },
+          nodeOperatorFee: { type: 'number', min: 0, max: 15 }
+        }
+      }
+    }
+  });
+
+  console.log('Generated staking rewards data:', result.data.length);
+  console.log('Average APR:',
+    (result.data.reduce((sum: number, d: any) => sum + d.stakingAPR, 0) / result.data.length).toFixed(2) + '%'
+  );
+
+  return result;
+}
+
+/**
+ * Example 8: Generate MEV (Maximal Extractable Value) scenarios
+ * Advanced DeFi strategy simulations
+ */
+async function generateMEVScenarios() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateEvents({
+    count: 1000,
+    eventTypes: ['sandwich', 'arbitrage', 'liquidation', 'jit_liquidity', 'nft_snipe'],
+    distribution: 'poisson',
+    timeRange: {
+      start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+      end: new Date()
+    },
+    userCount: 200, // MEV bots
+    schema: {
+      txHash: { type: 'string', format: 'transaction_hash' },
+      blockNumber: { type: 'integer', min: 18000000 },
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      mevType: {
+        type: 'string',
+        enum: ['sandwich', 'arbitrage', 'liquidation', 'jit_liquidity', 'backrun']
+      },
+      botAddress: { type: 'string', format: 'ethereum_address' },
+      targetTx: { type: 'string', format: 'transaction_hash' },
+      profit: { type: 'number', min: -1000, max: 100000 },
+      profitUSD: { type: 'number' },
+      gasCost: { type: 'number', min: 0 },
+      netProfit: { type: 'number' },
+      roi: { type: 'number' },
+      complexity: { type: 'integer', min: 1, max: 10 },
+      involvedProtocols: {
+        type: 'array',
+        items: { type: 'string' }
+      },
+      flashloanUsed: { type: 'boolean' },
+      flashloanAmount: { type: 'number' },
+      executionTime: { type: 'number', min: 1, max: 1000 } // ms
+    }
+  });
+
+  console.log('Generated MEV scenarios:', result.data.length);
+
+  const totalProfit = result.data.reduce((sum: number, mev: any) => sum + mev.netProfit, 0);
+  const profitableOps = result.data.filter((mev: any) => mev.netProfit > 0).length;
+
+  console.log(`Total MEV extracted: $${totalProfit.toFixed(2)}`);
+  console.log(`Profitable operations: ${profitableOps}/${result.data.length} (${(profitableOps/result.data.length*100).toFixed(1)}%)`);
+
+  return result;
+}
+
+/**
+ * Run all DeFi scenario examples
+ */
+export async function runDeFiScenarioExamples() {
+  console.log('=== DeFi Protocol Simulation Examples ===\n');
+
+  console.log('Example 1: Yield Farming Data');
+  await generateYieldFarmingData();
+  console.log('\n---\n');
+
+  console.log('Example 2: Liquidity Provision Scenarios');
+  await generateLiquidityProvisionScenarios();
+  console.log('\n---\n');
+
+  console.log('Example 3: Impermanent Loss Scenarios');
+  await generateImpermanentLossScenarios();
+  console.log('\n---\n');
+
+  console.log('Example 4: Gas Price Data');
+  await generateGasPriceData();
+  console.log('\n---\n');
+
+  console.log('Example 5: Smart Contract Interactions');
+  await generateSmartContractInteractions();
+  console.log('\n---\n');
+
+  console.log('Example 6: Lending/Borrowing Scenarios');
+  await generateLendingScenarios();
+  console.log('\n---\n');
+
+  console.log('Example 7: Staking Rewards');
+  await generateStakingRewards();
+  console.log('\n---\n');
+
+  console.log('Example 8: MEV Scenarios');
+  await generateMEVScenarios();
+}
+
+// Export individual examples
+export {
+  generateYieldFarmingData,
+  generateLiquidityProvisionScenarios,
+  generateImpermanentLossScenarios,
+  generateGasPriceData,
+  generateSmartContractInteractions,
+  generateLendingScenarios,
+  generateStakingRewards,
+  generateMEVScenarios
+};
+
+// Uncomment to run
+// runDeFiScenarioExamples().catch(console.error);

npm/packages/agentic-synth/examples/crypto/exchange-data.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Cryptocurrency Exchange Data Generation
+ *
+ * Examples for generating realistic crypto exchange data including:
+ * - OHLCV (Open, High, Low, Close, Volume) data
+ * - Order book snapshots and updates
+ * - Trade execution data
+ * - Liquidity pool metrics
+ * - CEX (Centralized Exchange) and DEX (Decentralized Exchange) patterns
+ */
+/**
+ * Example 1: Generate OHLCV data for multiple cryptocurrencies
+ * Simulates 24/7 crypto market with realistic price movements
+ */
+declare function generateOHLCV(): Promise<{
+    symbol: string;
+    data: unknown[];
+}[]>;
+/**
+ * Example 2: Generate realistic order book data
+ * Includes bid/ask spreads, market depth, and price levels
+ */
+declare function generateOrderBook(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 3: Generate trade execution data
+ * Simulates actual trades with realistic patterns
+ */
+declare function generateTrades(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 4: Generate liquidity pool data (DEX)
+ * Simulates AMM (Automated Market Maker) pools
+ */
+declare function generateLiquidityPools(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 5: Generate cross-exchange arbitrage opportunities
+ * Simulates price differences across exchanges
+ */
+declare function generateArbitrageOpportunities(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 6: Generate 24/7 market data with realistic patterns
+ * Includes timezone effects and global trading sessions
+ */
+declare function generate24x7MarketData(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 7: Generate funding rate data (perpetual futures)
+ * Important for derivatives trading
+ */
+declare function generateFundingRates(): Promise<import("../../src/types.js").GenerationResult<unknown>>;
+/**
+ * Example 8: Generate streaming real-time market data
+ * Simulates WebSocket-like continuous data feed
+ */
+declare function streamMarketData(): Promise<void>;
+/**
+ * Run all examples
+ */
+export declare function runExchangeDataExamples(): Promise<void>;
+export { generateOHLCV, generateOrderBook, generateTrades, generateLiquidityPools, generateArbitrageOpportunities, generate24x7MarketData, generateFundingRates, streamMarketData };
+//# sourceMappingURL=exchange-data.d.ts.map

npm/packages/agentic-synth/examples/crypto/exchange-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-data.d.ts","sourceRoot":"","sources":["exchange-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;GAGG;AACH,iBAAe,aAAa;;;KA8C3B;AAED;;;GAGG;AACH,iBAAe,iBAAiB,oEAkE/B;AAED;;;GAGG;AACH,iBAAe,cAAc,oEAyC5B;AAED;;;GAGG;AACH,iBAAe,sBAAsB,oEA6CpC;AAED;;;GAGG;AACH,iBAAe,8BAA8B,oEAwD5C;AAED;;;GAGG;AACH,iBAAe,sBAAsB,oEA8CpC;AAED;;;GAGG;AACH,iBAAe,oBAAoB,oEA0ClC;AAED;;;GAGG;AACH,iBAAe,gBAAgB,kBAuB9B;AAED;;GAEG;AACH,wBAAsB,uBAAuB,kBAiC5C;AAGD,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,8BAA8B,EAC9B,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EACjB,CAAC"}

npm/packages/agentic-synth/examples/crypto/exchange-data.js

@@ -0,0 +1,428 @@
+"use strict";
+/**
+ * Cryptocurrency Exchange Data Generation
+ *
+ * Examples for generating realistic crypto exchange data including:
+ * - OHLCV (Open, High, Low, Close, Volume) data
+ * - Order book snapshots and updates
+ * - Trade execution data
+ * - Liquidity pool metrics
+ * - CEX (Centralized Exchange) and DEX (Decentralized Exchange) patterns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runExchangeDataExamples = runExchangeDataExamples;
+exports.generateOHLCV = generateOHLCV;
+exports.generateOrderBook = generateOrderBook;
+exports.generateTrades = generateTrades;
+exports.generateLiquidityPools = generateLiquidityPools;
+exports.generateArbitrageOpportunities = generateArbitrageOpportunities;
+exports.generate24x7MarketData = generate24x7MarketData;
+exports.generateFundingRates = generateFundingRates;
+exports.streamMarketData = streamMarketData;
+const index_js_1 = require("../../src/index.js");
+/**
+ * Example 1: Generate OHLCV data for multiple cryptocurrencies
+ * Simulates 24/7 crypto market with realistic price movements
+ */
+async function generateOHLCV() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini',
+        apiKey: process.env.GEMINI_API_KEY
+    });
+    const cryptocurrencies = ['BTC', 'ETH', 'SOL', 'AVAX', 'MATIC'];
+    const results = [];
+    for (const symbol of cryptocurrencies) {
+        const result = await synth.generateTimeSeries({
+            count: 288, // 24 hours of 5-minute candles
+            interval: '5m',
+            startDate: new Date(Date.now() - 24 * 60 * 60 * 1000),
+            metrics: ['open', 'high', 'low', 'close', 'volume', 'vwap'],
+            trend: symbol === 'BTC' ? 'up' : symbol === 'SOL' ? 'volatile' : 'stable',
+            seasonality: true, // Include daily trading patterns
+            noise: 0.15, // 15% volatility
+            schema: {
+                timestamp: { type: 'datetime', format: 'iso8601' },
+                symbol: { type: 'string', enum: [symbol] },
+                open: { type: 'number', min: 0 },
+                high: { type: 'number', min: 0 },
+                low: { type: 'number', min: 0 },
+                close: { type: 'number', min: 0 },
+                volume: { type: 'number', min: 1000 },
+                vwap: { type: 'number', min: 0 },
+                trades: { type: 'integer', min: 1 }
+            },
+            constraints: {
+                // Ensure high >= open, close, low
+                // Ensure low <= open, close, high
+                custom: [
+                    'high >= Math.max(open, close, low)',
+                    'low <= Math.min(open, close, high)',
+                    'vwap >= low && vwap <= high',
+                    'volume > 0'
+                ]
+            }
+        });
+        results.push({ symbol, data: result.data });
+        console.log(`Generated ${symbol} OHLCV data: ${result.data.length} candles`);
+    }
+    return results;
+}
+/**
+ * Example 2: Generate realistic order book data
+ * Includes bid/ask spreads, market depth, and price levels
+ */
+async function generateOrderBook() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateStructured({
+        count: 100, // 100 order book snapshots
+        schema: {
+            timestamp: { type: 'datetime', required: true },
+            exchange: { type: 'string', enum: ['binance', 'coinbase', 'kraken', 'okx'] },
+            symbol: { type: 'string', enum: ['BTC/USDT', 'ETH/USDT', 'SOL/USDT'] },
+            bids: {
+                type: 'array',
+                required: true,
+                minItems: 20,
+                maxItems: 50,
+                items: {
+                    type: 'object',
+                    properties: {
+                        price: { type: 'number', min: 0 },
+                        quantity: { type: 'number', min: 0.001 },
+                        total: { type: 'number' }
+                    }
+                }
+            },
+            asks: {
+                type: 'array',
+                required: true,
+                minItems: 20,
+                maxItems: 50,
+                items: {
+                    type: 'object',
+                    properties: {
+                        price: { type: 'number', min: 0 },
+                        quantity: { type: 'number', min: 0.001 },
+                        total: { type: 'number' }
+                    }
+                }
+            },
+            spread: { type: 'number', min: 0 },
+            spreadPercent: { type: 'number', min: 0, max: 5 },
+            midPrice: { type: 'number', min: 0 },
+            liquidity: {
+                type: 'object',
+                properties: {
+                    bidDepth: { type: 'number' },
+                    askDepth: { type: 'number' },
+                    totalDepth: { type: 'number' }
+                }
+            }
+        },
+        constraints: {
+            custom: [
+                'bids sorted by price descending',
+                'asks sorted by price ascending',
+                'spread = asks[0].price - bids[0].price',
+                'midPrice = (bids[0].price + asks[0].price) / 2',
+                'realistic market microstructure'
+            ]
+        }
+    });
+    console.log('Generated order book snapshots:', result.data.length);
+    console.log('Sample order book:', JSON.stringify(result.data[0], null, 2));
+    return result;
+}
+/**
+ * Example 3: Generate trade execution data
+ * Simulates actual trades with realistic patterns
+ */
+async function generateTrades() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateEvents({
+        count: 10000, // 10k trades
+        eventTypes: ['market_buy', 'market_sell', 'limit_buy', 'limit_sell'],
+        distribution: 'poisson', // Realistic trade arrival times
+        timeRange: {
+            start: new Date(Date.now() - 24 * 60 * 60 * 1000),
+            end: new Date()
+        },
+        userCount: 5000, // 5k unique traders
+        schema: {
+            tradeId: { type: 'string', format: 'uuid' },
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            exchange: { type: 'string', enum: ['binance', 'coinbase', 'kraken'] },
+            symbol: { type: 'string', enum: ['BTC/USDT', 'ETH/USDT', 'SOL/USDT', 'AVAX/USDT'] },
+            side: { type: 'string', enum: ['buy', 'sell'] },
+            orderType: { type: 'string', enum: ['market', 'limit', 'stop', 'stop_limit'] },
+            price: { type: 'number', min: 0 },
+            quantity: { type: 'number', min: 0.001 },
+            total: { type: 'number' },
+            fee: { type: 'number', min: 0 },
+            feeAsset: { type: 'string', enum: ['USDT', 'BTC', 'ETH', 'BNB'] },
+            userId: { type: 'string' },
+            makerTaker: { type: 'string', enum: ['maker', 'taker'] },
+            latency: { type: 'number', min: 1, max: 500 } // ms
+        }
+    });
+    console.log('Generated trades:', result.data.length);
+    console.log('Metadata:', result.metadata);
+    // Analyze trade patterns
+    const buyTrades = result.data.filter((t) => t.side === 'buy').length;
+    const sellTrades = result.data.filter((t) => t.side === 'sell').length;
+    console.log(`Buy/Sell ratio: ${buyTrades}/${sellTrades}`);
+    return result;
+}
+/**
+ * Example 4: Generate liquidity pool data (DEX)
+ * Simulates AMM (Automated Market Maker) pools
+ */
+async function generateLiquidityPools() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateTimeSeries({
+        count: 1440, // 24 hours, 1-minute intervals
+        interval: '1m',
+        startDate: new Date(Date.now() - 24 * 60 * 60 * 1000),
+        metrics: ['reserveA', 'reserveB', 'totalLiquidity', 'volume24h', 'fees24h', 'apy'],
+        trend: 'stable',
+        seasonality: true,
+        noise: 0.08,
+        schema: {
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            dex: { type: 'string', enum: ['uniswap', 'sushiswap', 'pancakeswap', 'curve'] },
+            poolAddress: { type: 'string', format: 'ethereum_address' },
+            tokenA: { type: 'string', enum: ['WETH', 'USDC', 'DAI', 'WBTC'] },
+            tokenB: { type: 'string', enum: ['USDC', 'USDT', 'DAI'] },
+            reserveA: { type: 'number', min: 100000 },
+            reserveB: { type: 'number', min: 100000 },
+            totalLiquidity: { type: 'number', min: 200000 },
+            price: { type: 'number', min: 0 },
+            volume24h: { type: 'number', min: 0 },
+            fees24h: { type: 'number', min: 0 },
+            txCount: { type: 'integer', min: 0 },
+            uniqueWallets: { type: 'integer', min: 0 },
+            apy: { type: 'number', min: 0, max: 500 },
+            impermanentLoss: { type: 'number', min: -50, max: 0 }
+        },
+        constraints: {
+            custom: [
+                'price = reserveB / reserveA',
+                'totalLiquidity = reserveA + reserveB (in USD)',
+                'fees24h = volume24h * 0.003', // 0.3% fee
+                'apy based on fees and liquidity',
+                'maintain constant product formula (k = reserveA * reserveB)'
+            ]
+        }
+    });
+    console.log('Generated liquidity pool data:', result.data.length);
+    console.log('Sample pool state:', result.data[0]);
+    return result;
+}
+/**
+ * Example 5: Generate cross-exchange arbitrage opportunities
+ * Simulates price differences across exchanges
+ */
+async function generateArbitrageOpportunities() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const exchanges = ['binance', 'coinbase', 'kraken', 'okx'];
+    const symbols = ['BTC/USDT', 'ETH/USDT', 'SOL/USDT'];
+    const result = await synth.generateStructured({
+        count: 500, // 500 arbitrage opportunities over 24 hours
+        schema: {
+            timestamp: { type: 'datetime', required: true },
+            symbol: { type: 'string', enum: symbols },
+            buyExchange: { type: 'string', enum: exchanges },
+            sellExchange: { type: 'string', enum: exchanges },
+            buyPrice: { type: 'number', min: 0 },
+            sellPrice: { type: 'number', min: 0 },
+            spread: { type: 'number', min: 0.001, max: 5 }, // 0.1% to 5%
+            spreadPercent: { type: 'number' },
+            volume: { type: 'number', min: 0 },
+            profitUSD: { type: 'number', min: 0 },
+            profitPercent: { type: 'number', min: 0 },
+            executionTime: { type: 'number', min: 100, max: 5000 }, // ms
+            feasible: { type: 'boolean' },
+            fees: {
+                type: 'object',
+                properties: {
+                    buyFee: { type: 'number' },
+                    sellFee: { type: 'number' },
+                    networkFee: { type: 'number' },
+                    totalFee: { type: 'number' }
+                }
+            },
+            netProfit: { type: 'number' }
+        },
+        constraints: {
+            custom: [
+                'buyExchange !== sellExchange',
+                'sellPrice > buyPrice',
+                'spreadPercent = (sellPrice - buyPrice) / buyPrice * 100',
+                'profitUSD = volume * spread - fees.totalFee',
+                'netProfit = profitUSD - fees.totalFee',
+                'feasible = netProfit > 0 && executionTime < 3000'
+            ]
+        }
+    });
+    console.log('Generated arbitrage opportunities:', result.data.length);
+    const feasibleOpps = result.data.filter((opp) => opp.feasible);
+    console.log('Feasible opportunities:', feasibleOpps.length);
+    console.log('Average profit:', feasibleOpps.reduce((sum, opp) => sum + opp.netProfit, 0) / feasibleOpps.length);
+    return result;
+}
+/**
+ * Example 6: Generate 24/7 market data with realistic patterns
+ * Includes timezone effects and global trading sessions
+ */
+async function generate24x7MarketData() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateTimeSeries({
+        count: 168 * 12, // 1 week, 5-minute intervals
+        interval: '5m',
+        startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+        metrics: ['price', 'volume', 'volatility', 'momentum'],
+        trend: 'up',
+        seasonality: true,
+        noise: 0.12,
+        schema: {
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            symbol: { type: 'string', default: 'BTC/USDT' },
+            price: { type: 'number', min: 0 },
+            volume: { type: 'number', min: 0 },
+            volatility: { type: 'number', min: 0, max: 100 },
+            momentum: { type: 'number', min: -100, max: 100 },
+            tradingSession: {
+                type: 'string',
+                enum: ['asian', 'european', 'american', 'overlap']
+            },
+            marketCap: { type: 'number' },
+            dominance: { type: 'number', min: 0, max: 100 },
+            fearGreedIndex: { type: 'integer', min: 0, max: 100 }
+        },
+        constraints: {
+            custom: [
+                'Higher volume during US and European hours',
+                'Increased volatility during Asian session opens',
+                'Weekend volumes typically 30% lower',
+                'Fear & Greed index correlates with momentum',
+                'Price movements respect support/resistance levels'
+            ]
+        }
+    });
+    console.log('Generated 24/7 market data:', result.data.length);
+    console.log('Time range:', {
+        start: result.data[0].timestamp,
+        end: result.data[result.data.length - 1].timestamp
+    });
+    return result;
+}
+/**
+ * Example 7: Generate funding rate data (perpetual futures)
+ * Important for derivatives trading
+ */
+async function generateFundingRates() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini'
+    });
+    const result = await synth.generateTimeSeries({
+        count: 720, // 30 days, 8-hour funding periods
+        interval: '8h',
+        startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+        metrics: ['fundingRate', 'predictedRate', 'openInterest', 'markPrice', 'indexPrice'],
+        trend: 'stable',
+        seasonality: false,
+        noise: 0.05,
+        schema: {
+            timestamp: { type: 'datetime', format: 'iso8601' },
+            exchange: { type: 'string', enum: ['binance', 'bybit', 'okx', 'deribit'] },
+            symbol: { type: 'string', enum: ['BTC-PERP', 'ETH-PERP', 'SOL-PERP'] },
+            fundingRate: { type: 'number', min: -0.05, max: 0.05 }, // -5% to 5%
+            predictedRate: { type: 'number', min: -0.05, max: 0.05 },
+            openInterest: { type: 'number', min: 1000000 },
+            markPrice: { type: 'number', min: 0 },
+            indexPrice: { type: 'number', min: 0 },
+            premium: { type: 'number' },
+            longShortRatio: { type: 'number', min: 0.5, max: 2 }
+        },
+        constraints: {
+            custom: [
+                'premium = markPrice - indexPrice',
+                'fundingRate based on premium and time',
+                'positive rate means longs pay shorts',
+                'negative rate means shorts pay longs',
+                'extreme rates indicate strong directional bias'
+            ]
+        }
+    });
+    console.log('Generated funding rate data:', result.data.length);
+    console.log('Average funding rate:', result.data.reduce((sum, d) => sum + d.fundingRate, 0) / result.data.length);
+    return result;
+}
+/**
+ * Example 8: Generate streaming real-time market data
+ * Simulates WebSocket-like continuous data feed
+ */
+async function streamMarketData() {
+    const synth = (0, index_js_1.createSynth)({
+        provider: 'gemini',
+        streaming: true
+    });
+    console.log('Streaming real-time market data (30 updates)...');
+    let count = 0;
+    for await (const tick of synth.generateStream('timeseries', {
+        count: 30,
+        interval: '1s',
+        metrics: ['price', 'volume'],
+        schema: {
+            timestamp: { type: 'datetime' },
+            symbol: { type: 'string', default: 'BTC/USDT' },
+            price: { type: 'number' },
+            volume: { type: 'number' },
+            lastUpdate: { type: 'number' }
+        }
+    })) {
+        console.log(`[${++count}] ${tick.timestamp} - ${tick.symbol}: $${tick.price} (Vol: ${tick.volume})`);
+    }
+}
+/**
+ * Run all examples
+ */
+async function runExchangeDataExamples() {
+    console.log('=== Cryptocurrency Exchange Data Generation Examples ===\n');
+    console.log('Example 1: OHLCV Data Generation');
+    await generateOHLCV();
+    console.log('\n---\n');
+    console.log('Example 2: Order Book Generation');
+    await generateOrderBook();
+    console.log('\n---\n');
+    console.log('Example 3: Trade Execution Data');
+    await generateTrades();
+    console.log('\n---\n');
+    console.log('Example 4: Liquidity Pool Data (DEX)');
+    await generateLiquidityPools();
+    console.log('\n---\n');
+    console.log('Example 5: Arbitrage Opportunities');
+    await generateArbitrageOpportunities();
+    console.log('\n---\n');
+    console.log('Example 6: 24/7 Market Data');
+    await generate24x7MarketData();
+    console.log('\n---\n');
+    console.log('Example 7: Funding Rate Data');
+    await generateFundingRates();
+    console.log('\n---\n');
+    console.log('Example 8: Streaming Market Data');
+    await streamMarketData();
+}
+// Uncomment to run
+// runExchangeDataExamples().catch(console.error);
+//# sourceMappingURL=exchange-data.js.map

npm/packages/agentic-synth/examples/crypto/exchange-data.ts

@@ -0,0 +1,478 @@
+/**
+ * Cryptocurrency Exchange Data Generation
+ *
+ * Examples for generating realistic crypto exchange data including:
+ * - OHLCV (Open, High, Low, Close, Volume) data
+ * - Order book snapshots and updates
+ * - Trade execution data
+ * - Liquidity pool metrics
+ * - CEX (Centralized Exchange) and DEX (Decentralized Exchange) patterns
+ */
+
+import { createSynth } from '../../src/index.js';
+
+/**
+ * Example 1: Generate OHLCV data for multiple cryptocurrencies
+ * Simulates 24/7 crypto market with realistic price movements
+ */
+async function generateOHLCV() {
+  const synth = createSynth({
+    provider: 'gemini',
+    apiKey: process.env.GEMINI_API_KEY
+  });
+
+  const cryptocurrencies = ['BTC', 'ETH', 'SOL', 'AVAX', 'MATIC'];
+  const results = [];
+
+  for (const symbol of cryptocurrencies) {
+    const result = await synth.generateTimeSeries({
+      count: 288, // 24 hours of 5-minute candles
+      interval: '5m',
+      startDate: new Date(Date.now() - 24 * 60 * 60 * 1000),
+      metrics: ['open', 'high', 'low', 'close', 'volume', 'vwap'],
+      trend: symbol === 'BTC' ? 'up' : symbol === 'SOL' ? 'volatile' : 'stable',
+      seasonality: true, // Include daily trading patterns
+      noise: 0.15, // 15% volatility
+      schema: {
+        timestamp: { type: 'datetime', format: 'iso8601' },
+        symbol: { type: 'string', enum: [symbol] },
+        open: { type: 'number', min: 0 },
+        high: { type: 'number', min: 0 },
+        low: { type: 'number', min: 0 },
+        close: { type: 'number', min: 0 },
+        volume: { type: 'number', min: 1000 },
+        vwap: { type: 'number', min: 0 },
+        trades: { type: 'integer', min: 1 }
+      },
+      constraints: {
+        // Ensure high >= open, close, low
+        // Ensure low <= open, close, high
+        custom: [
+          'high >= Math.max(open, close, low)',
+          'low <= Math.min(open, close, high)',
+          'vwap >= low && vwap <= high',
+          'volume > 0'
+        ]
+      }
+    });
+
+    results.push({ symbol, data: result.data });
+    console.log(`Generated ${symbol} OHLCV data: ${result.data.length} candles`);
+  }
+
+  return results;
+}
+
+/**
+ * Example 2: Generate realistic order book data
+ * Includes bid/ask spreads, market depth, and price levels
+ */
+async function generateOrderBook() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateStructured({
+    count: 100, // 100 order book snapshots
+    schema: {
+      timestamp: { type: 'datetime', required: true },
+      exchange: { type: 'string', enum: ['binance', 'coinbase', 'kraken', 'okx'] },
+      symbol: { type: 'string', enum: ['BTC/USDT', 'ETH/USDT', 'SOL/USDT'] },
+      bids: {
+        type: 'array',
+        required: true,
+        minItems: 20,
+        maxItems: 50,
+        items: {
+          type: 'object',
+          properties: {
+            price: { type: 'number', min: 0 },
+            quantity: { type: 'number', min: 0.001 },
+            total: { type: 'number' }
+          }
+        }
+      },
+      asks: {
+        type: 'array',
+        required: true,
+        minItems: 20,
+        maxItems: 50,
+        items: {
+          type: 'object',
+          properties: {
+            price: { type: 'number', min: 0 },
+            quantity: { type: 'number', min: 0.001 },
+            total: { type: 'number' }
+          }
+        }
+      },
+      spread: { type: 'number', min: 0 },
+      spreadPercent: { type: 'number', min: 0, max: 5 },
+      midPrice: { type: 'number', min: 0 },
+      liquidity: {
+        type: 'object',
+        properties: {
+          bidDepth: { type: 'number' },
+          askDepth: { type: 'number' },
+          totalDepth: { type: 'number' }
+        }
+      }
+    },
+    constraints: {
+      custom: [
+        'bids sorted by price descending',
+        'asks sorted by price ascending',
+        'spread = asks[0].price - bids[0].price',
+        'midPrice = (bids[0].price + asks[0].price) / 2',
+        'realistic market microstructure'
+      ]
+    }
+  });
+
+  console.log('Generated order book snapshots:', result.data.length);
+  console.log('Sample order book:', JSON.stringify(result.data[0], null, 2));
+
+  return result;
+}
+
+/**
+ * Example 3: Generate trade execution data
+ * Simulates actual trades with realistic patterns
+ */
+async function generateTrades() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateEvents({
+    count: 10000, // 10k trades
+    eventTypes: ['market_buy', 'market_sell', 'limit_buy', 'limit_sell'],
+    distribution: 'poisson', // Realistic trade arrival times
+    timeRange: {
+      start: new Date(Date.now() - 24 * 60 * 60 * 1000),
+      end: new Date()
+    },
+    userCount: 5000, // 5k unique traders
+    schema: {
+      tradeId: { type: 'string', format: 'uuid' },
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      exchange: { type: 'string', enum: ['binance', 'coinbase', 'kraken'] },
+      symbol: { type: 'string', enum: ['BTC/USDT', 'ETH/USDT', 'SOL/USDT', 'AVAX/USDT'] },
+      side: { type: 'string', enum: ['buy', 'sell'] },
+      orderType: { type: 'string', enum: ['market', 'limit', 'stop', 'stop_limit'] },
+      price: { type: 'number', min: 0 },
+      quantity: { type: 'number', min: 0.001 },
+      total: { type: 'number' },
+      fee: { type: 'number', min: 0 },
+      feeAsset: { type: 'string', enum: ['USDT', 'BTC', 'ETH', 'BNB'] },
+      userId: { type: 'string' },
+      makerTaker: { type: 'string', enum: ['maker', 'taker'] },
+      latency: { type: 'number', min: 1, max: 500 } // ms
+    }
+  });
+
+  console.log('Generated trades:', result.data.length);
+  console.log('Metadata:', result.metadata);
+
+  // Analyze trade patterns
+  const buyTrades = result.data.filter((t: any) => t.side === 'buy').length;
+  const sellTrades = result.data.filter((t: any) => t.side === 'sell').length;
+  console.log(`Buy/Sell ratio: ${buyTrades}/${sellTrades}`);
+
+  return result;
+}
+
+/**
+ * Example 4: Generate liquidity pool data (DEX)
+ * Simulates AMM (Automated Market Maker) pools
+ */
+async function generateLiquidityPools() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateTimeSeries({
+    count: 1440, // 24 hours, 1-minute intervals
+    interval: '1m',
+    startDate: new Date(Date.now() - 24 * 60 * 60 * 1000),
+    metrics: ['reserveA', 'reserveB', 'totalLiquidity', 'volume24h', 'fees24h', 'apy'],
+    trend: 'stable',
+    seasonality: true,
+    noise: 0.08,
+    schema: {
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      dex: { type: 'string', enum: ['uniswap', 'sushiswap', 'pancakeswap', 'curve'] },
+      poolAddress: { type: 'string', format: 'ethereum_address' },
+      tokenA: { type: 'string', enum: ['WETH', 'USDC', 'DAI', 'WBTC'] },
+      tokenB: { type: 'string', enum: ['USDC', 'USDT', 'DAI'] },
+      reserveA: { type: 'number', min: 100000 },
+      reserveB: { type: 'number', min: 100000 },
+      totalLiquidity: { type: 'number', min: 200000 },
+      price: { type: 'number', min: 0 },
+      volume24h: { type: 'number', min: 0 },
+      fees24h: { type: 'number', min: 0 },
+      txCount: { type: 'integer', min: 0 },
+      uniqueWallets: { type: 'integer', min: 0 },
+      apy: { type: 'number', min: 0, max: 500 },
+      impermanentLoss: { type: 'number', min: -50, max: 0 }
+    },
+    constraints: {
+      custom: [
+        'price = reserveB / reserveA',
+        'totalLiquidity = reserveA + reserveB (in USD)',
+        'fees24h = volume24h * 0.003', // 0.3% fee
+        'apy based on fees and liquidity',
+        'maintain constant product formula (k = reserveA * reserveB)'
+      ]
+    }
+  });
+
+  console.log('Generated liquidity pool data:', result.data.length);
+  console.log('Sample pool state:', result.data[0]);
+
+  return result;
+}
+
+/**
+ * Example 5: Generate cross-exchange arbitrage opportunities
+ * Simulates price differences across exchanges
+ */
+async function generateArbitrageOpportunities() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const exchanges = ['binance', 'coinbase', 'kraken', 'okx'];
+  const symbols = ['BTC/USDT', 'ETH/USDT', 'SOL/USDT'];
+
+  const result = await synth.generateStructured({
+    count: 500, // 500 arbitrage opportunities over 24 hours
+    schema: {
+      timestamp: { type: 'datetime', required: true },
+      symbol: { type: 'string', enum: symbols },
+      buyExchange: { type: 'string', enum: exchanges },
+      sellExchange: { type: 'string', enum: exchanges },
+      buyPrice: { type: 'number', min: 0 },
+      sellPrice: { type: 'number', min: 0 },
+      spread: { type: 'number', min: 0.001, max: 5 }, // 0.1% to 5%
+      spreadPercent: { type: 'number' },
+      volume: { type: 'number', min: 0 },
+      profitUSD: { type: 'number', min: 0 },
+      profitPercent: { type: 'number', min: 0 },
+      executionTime: { type: 'number', min: 100, max: 5000 }, // ms
+      feasible: { type: 'boolean' },
+      fees: {
+        type: 'object',
+        properties: {
+          buyFee: { type: 'number' },
+          sellFee: { type: 'number' },
+          networkFee: { type: 'number' },
+          totalFee: { type: 'number' }
+        }
+      },
+      netProfit: { type: 'number' }
+    },
+    constraints: {
+      custom: [
+        'buyExchange !== sellExchange',
+        'sellPrice > buyPrice',
+        'spreadPercent = (sellPrice - buyPrice) / buyPrice * 100',
+        'profitUSD = volume * spread - fees.totalFee',
+        'netProfit = profitUSD - fees.totalFee',
+        'feasible = netProfit > 0 && executionTime < 3000'
+      ]
+    }
+  });
+
+  console.log('Generated arbitrage opportunities:', result.data.length);
+
+  const feasibleOpps = result.data.filter((opp: any) => opp.feasible);
+  console.log('Feasible opportunities:', feasibleOpps.length);
+  console.log('Average profit:',
+    feasibleOpps.reduce((sum: number, opp: any) => sum + opp.netProfit, 0) / feasibleOpps.length
+  );
+
+  return result;
+}
+
+/**
+ * Example 6: Generate 24/7 market data with realistic patterns
+ * Includes timezone effects and global trading sessions
+ */
+async function generate24x7MarketData() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateTimeSeries({
+    count: 168 * 12, // 1 week, 5-minute intervals
+    interval: '5m',
+    startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+    metrics: ['price', 'volume', 'volatility', 'momentum'],
+    trend: 'up',
+    seasonality: true,
+    noise: 0.12,
+    schema: {
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      symbol: { type: 'string', default: 'BTC/USDT' },
+      price: { type: 'number', min: 0 },
+      volume: { type: 'number', min: 0 },
+      volatility: { type: 'number', min: 0, max: 100 },
+      momentum: { type: 'number', min: -100, max: 100 },
+      tradingSession: {
+        type: 'string',
+        enum: ['asian', 'european', 'american', 'overlap']
+      },
+      marketCap: { type: 'number' },
+      dominance: { type: 'number', min: 0, max: 100 },
+      fearGreedIndex: { type: 'integer', min: 0, max: 100 }
+    },
+    constraints: {
+      custom: [
+        'Higher volume during US and European hours',
+        'Increased volatility during Asian session opens',
+        'Weekend volumes typically 30% lower',
+        'Fear & Greed index correlates with momentum',
+        'Price movements respect support/resistance levels'
+      ]
+    }
+  });
+
+  console.log('Generated 24/7 market data:', result.data.length);
+  console.log('Time range:', {
+    start: result.data[0].timestamp,
+    end: result.data[result.data.length - 1].timestamp
+  });
+
+  return result;
+}
+
+/**
+ * Example 7: Generate funding rate data (perpetual futures)
+ * Important for derivatives trading
+ */
+async function generateFundingRates() {
+  const synth = createSynth({
+    provider: 'gemini'
+  });
+
+  const result = await synth.generateTimeSeries({
+    count: 720, // 30 days, 8-hour funding periods
+    interval: '8h',
+    startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+    metrics: ['fundingRate', 'predictedRate', 'openInterest', 'markPrice', 'indexPrice'],
+    trend: 'stable',
+    seasonality: false,
+    noise: 0.05,
+    schema: {
+      timestamp: { type: 'datetime', format: 'iso8601' },
+      exchange: { type: 'string', enum: ['binance', 'bybit', 'okx', 'deribit'] },
+      symbol: { type: 'string', enum: ['BTC-PERP', 'ETH-PERP', 'SOL-PERP'] },
+      fundingRate: { type: 'number', min: -0.05, max: 0.05 }, // -5% to 5%
+      predictedRate: { type: 'number', min: -0.05, max: 0.05 },
+      openInterest: { type: 'number', min: 1000000 },
+      markPrice: { type: 'number', min: 0 },
+      indexPrice: { type: 'number', min: 0 },
+      premium: { type: 'number' },
+      longShortRatio: { type: 'number', min: 0.5, max: 2 }
+    },
+    constraints: {
+      custom: [
+        'premium = markPrice - indexPrice',
+        'fundingRate based on premium and time',
+        'positive rate means longs pay shorts',
+        'negative rate means shorts pay longs',
+        'extreme rates indicate strong directional bias'
+      ]
+    }
+  });
+
+  console.log('Generated funding rate data:', result.data.length);
+  console.log('Average funding rate:',
+    result.data.reduce((sum: any, d: any) => sum + d.fundingRate, 0) / result.data.length
+  );
+
+  return result;
+}
+
+/**
+ * Example 8: Generate streaming real-time market data
+ * Simulates WebSocket-like continuous data feed
+ */
+async function streamMarketData() {
+  const synth = createSynth({
+    provider: 'gemini',
+    streaming: true
+  });
+
+  console.log('Streaming real-time market data (30 updates)...');
+  let count = 0;
+
+  for await (const tick of synth.generateStream('timeseries', {
+    count: 30,
+    interval: '1s',
+    metrics: ['price', 'volume'],
+    schema: {
+      timestamp: { type: 'datetime' },
+      symbol: { type: 'string', default: 'BTC/USDT' },
+      price: { type: 'number' },
+      volume: { type: 'number' },
+      lastUpdate: { type: 'number' }
+    }
+  })) {
+    console.log(`[${++count}] ${tick.timestamp} - ${tick.symbol}: $${tick.price} (Vol: ${tick.volume})`);
+  }
+}
+
+/**
+ * Run all examples
+ */
+export async function runExchangeDataExamples() {
+  console.log('=== Cryptocurrency Exchange Data Generation Examples ===\n');
+
+  console.log('Example 1: OHLCV Data Generation');
+  await generateOHLCV();
+  console.log('\n---\n');
+
+  console.log('Example 2: Order Book Generation');
+  await generateOrderBook();
+  console.log('\n---\n');
+
+  console.log('Example 3: Trade Execution Data');
+  await generateTrades();
+  console.log('\n---\n');
+
+  console.log('Example 4: Liquidity Pool Data (DEX)');
+  await generateLiquidityPools();
+  console.log('\n---\n');
+
+  console.log('Example 5: Arbitrage Opportunities');
+  await generateArbitrageOpportunities();
+  console.log('\n---\n');
+
+  console.log('Example 6: 24/7 Market Data');
+  await generate24x7MarketData();
+  console.log('\n---\n');
+
+  console.log('Example 7: Funding Rate Data');
+  await generateFundingRates();
+  console.log('\n---\n');
+
+  console.log('Example 8: Streaming Market Data');
+  await streamMarketData();
+}
+
+// Export individual examples
+export {
+  generateOHLCV,
+  generateOrderBook,
+  generateTrades,
+  generateLiquidityPools,
+  generateArbitrageOpportunities,
+  generate24x7MarketData,
+  generateFundingRates,
+  streamMarketData
+};
+
+// Uncomment to run
+// runExchangeDataExamples().catch(console.error);