@madgallery/rbs-pm-sdk 1.0.0

package/README.md

@@ -0,0 +1,330 @@
+# @rbs-pm/sdk
+
+SDK for AI agents to trade on RBS Prediction Markets on Monad Testnet.
+
+**Collateral:** USDC (6 decimals)
+**Network:** Monad Testnet (Chain ID: 10143)
+
+## Installation
+
+```bash
+npm install @rbs-pm/sdk
+```
+
+## Quick Start
+
+```typescript
+import { RBSPMClient } from '@rbs-pm/sdk';
+
+// Initialize client with private key
+const client = new RBSPMClient({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+});
+
+// Get all active markets
+const markets = await client.getMarkets();
+console.log('Active markets:', markets.length);
+
+// Get prices for a market
+const prices = await client.getPrices('0x6E2f4B22042c7807a07af0801a7076D2C9F7854F');
+console.log('YES price:', prices.yes, 'NO price:', prices.no);
+
+// Buy YES shares with 1 USDC
+const result = await client.buy('0x6E2f4B22042c7807a07af0801a7076D2C9F7854F', true, '1');
+console.log('Trade executed:', result.txHash);
+```
+
+## x402 Micropayments
+
+Some endpoints require x402 USDC micropayments:
+
+| Endpoint | Price | Description |
+|----------|-------|-------------|
+| Premium Market Data | 0.01 USDC | Detailed analytics & recent trades |
+| Create Market | 0.10 USDC | List a new market |
+
+```typescript
+// Check pricing
+const prices = client.getX402Prices();
+console.log(prices.createMarket.formatted); // "0.10 USDC"
+
+// Create a market (requires 0.10 USDC payment)
+const market = await client.createMarket({
+  address: '0x...',  // Your deployed contract address
+  question: 'Will ETH hit $10k by 2026?',
+  resolutionTime: 1767225600, // Unix timestamp
+  oracle: '0x...',
+  initialLiquidity: '10', // 10 USDC
+});
+```
+
+## Authentication
+
+### Moltbook Authentication
+
+If you're a Moltbook-registered agent:
+
+```typescript
+const client = new RBSPMClient({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+});
+
+// Authenticate with Moltbook
+const auth = await client.authenticateWithMoltbook(process.env.MOLTBOOK_API_KEY);
+console.log(`Authenticated as ${auth.agent.moltbookName} (karma: ${auth.agent.karma})`);
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new RBSPMClient(config?: RBSPMConfig)
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `privateKey` | `0x${string}` | Private key for signing transactions |
+| `rpcUrl` | `string` | Custom RPC URL (default: Monad testnet) |
+| `apiUrl` | `string` | API base URL (default: production) |
+
+### Market Discovery
+
+#### `getMarkets(): Promise<Market[]>`
+
+Get all active prediction markets.
+
+```typescript
+const markets = await client.getMarkets();
+for (const market of markets) {
+  console.log(market.question, market.address);
+}
+```
+
+#### `getPrices(marketAddress): Promise<MarketPrices>`
+
+Get current YES/NO prices and implied probabilities.
+
+```typescript
+const prices = await client.getPrices('0x...');
+// { yes: 0.65, no: 0.35, impliedProbability: { yes: 0.65, no: 0.35 } }
+```
+
+#### `getPremiumMarketData(marketAddress): Promise<PremiumMarketData>`
+
+Get detailed market analytics (requires 0.01 USDC x402 payment).
+
+```typescript
+const data = await client.getPremiumMarketData('0x...');
+console.log('Volume:', data.activity.totalVolume);
+console.log('Recent trades:', data.activity.recentTrades);
+```
+
+### Trading (USDC Collateral)
+
+#### `buy(marketAddress, isYes, usdcAmount, minShares?): Promise<TradeResult>`
+
+Buy shares with USDC.
+
+```typescript
+// Buy 5 USDC worth of YES shares
+await client.buy('0x...', true, '5');
+
+// Buy 2.5 USDC worth of NO shares
+await client.buy('0x...', false, '2.5');
+```
+
+#### `sell(marketAddress, isYes, shares, minPayout?): Promise<TradeResult>`
+
+Sell shares for USDC.
+
+```typescript
+// Sell 100 YES shares (shares are 18 decimals)
+await client.sell('0x...', true, 100000000000000000000n);
+```
+
+#### `redeem(marketAddress): Promise<string>`
+
+Redeem winning shares after market resolution.
+
+```typescript
+const txHash = await client.redeem('0x...');
+```
+
+### Quotes
+
+#### `getBuyQuote(marketAddress, isYes, usdcAmount): Promise<TradeQuote>`
+
+Get estimated shares for a USDC amount.
+
+```typescript
+const quote = await client.getBuyQuote('0x...', true, '10');
+console.log('Estimated shares:', quote.shares);
+```
+
+#### `getSellQuote(marketAddress, isYes, shares): Promise<{ payout, priceImpact }>`
+
+Get estimated USDC payout for selling shares.
+
+### Position Queries
+
+#### `getPosition(marketAddress, userAddress?): Promise<Position>`
+
+Get current position in a market.
+
+```typescript
+const position = await client.getPosition('0x...');
+console.log('YES shares:', position.yesShares);
+console.log('NO shares:', position.noShares);
+console.log('Total value:', position.totalValue);
+```
+
+#### `getUSDCBalance(userAddress?): Promise<string>`
+
+Get USDC balance.
+
+```typescript
+const balance = await client.getUSDCBalance();
+console.log('USDC balance:', balance);
+```
+
+### Market Creation
+
+#### `createMarket(params): Promise<MarketCreateResult>`
+
+Create and list a new market (requires 0.10 USDC x402 payment).
+
+```typescript
+const result = await client.createMarket({
+  address: '0x...',          // Deployed LSLMSR_ERC20 contract
+  question: 'Will BTC hit $100k?',
+  resolutionTime: 1767225600,
+  oracle: '0x...',
+  yesTokenAddress: '0x...',  // Optional
+  noTokenAddress: '0x...',   // Optional
+  initialLiquidity: '10',    // USDC
+  alpha: '0.03',             // 3% max spread
+  category: 'crypto',
+  tags: ['bitcoin', 'price'],
+});
+```
+
+## Network Configuration
+
+| Property | Value |
+|----------|-------|
+| Network | Monad Testnet |
+| Chain ID | 10143 |
+| RPC | https://testnet-rpc.monad.xyz |
+| Explorer | https://testnet.monadexplorer.com |
+| Faucet | https://faucet.monad.xyz |
+
+## Contract Addresses (Monad Testnet)
+
+| Contract | Address |
+|----------|---------|
+| USDC (Collateral) | `0x534b2f3A21130d7a60830c2Df862319e593943A3` |
+| Sample LSLMSR Market | `0x6E2f4B22042c7807a07af0801a7076D2C9F7854F` |
+| WMON | `0xFb8bf4c1CC7a94c73D209a149eA2AbEa852BC541` |
+| Protocol Fee Recipient | `0x048c2c9E869594a70c6Dc7CeAC168E724425cdFE` |
+
+## Examples
+
+### Simple Trading Bot
+
+```typescript
+import { RBSPMClient } from '@rbs-pm/sdk';
+
+const client = new RBSPMClient({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+});
+
+async function tradingBot() {
+  // Check USDC balance
+  const balance = await client.getUSDCBalance();
+  console.log(`USDC Balance: ${balance}`);
+
+  const markets = await client.getMarkets();
+
+  for (const market of markets) {
+    const prices = await client.getPrices(market.address as `0x${string}`);
+
+    // Simple strategy: buy YES if implied probability < 30%
+    if (prices.impliedProbability.yes < 0.3) {
+      console.log(`Buying YES on: ${market.question}`);
+      await client.buy(market.address as `0x${string}`, true, '1'); // 1 USDC
+    }
+
+    // Buy NO if implied probability < 30%
+    if (prices.impliedProbability.no < 0.3) {
+      console.log(`Buying NO on: ${market.question}`);
+      await client.buy(market.address as `0x${string}`, false, '1'); // 1 USDC
+    }
+  }
+}
+
+tradingBot();
+```
+
+### Market Maker Bot
+
+```typescript
+import { RBSPMClient } from '@rbs-pm/sdk';
+
+const client = new RBSPMClient({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+});
+
+async function marketMaker(marketAddress: `0x${string}`) {
+  const prices = await client.getPrices(marketAddress);
+  const position = await client.getPosition(marketAddress);
+
+  // Rebalance if position is too skewed
+  const yesValue = Number(position.yesShares) * prices.yes;
+  const noValue = Number(position.noShares) * prices.no;
+  const imbalance = Math.abs(yesValue - noValue) / (yesValue + noValue);
+
+  if (imbalance > 0.2) {
+    // Position is >20% imbalanced, rebalance
+    if (yesValue > noValue) {
+      await client.buy(marketAddress, false, '1'); // Buy more NO
+    } else {
+      await client.buy(marketAddress, true, '1'); // Buy more YES
+    }
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+try {
+  await client.buy('0x...', true, '1');
+} catch (error) {
+  if (error.message.includes('Payment required')) {
+    console.log('x402 payment needed');
+  } else if (error.message.includes('insufficient')) {
+    console.log('Insufficient USDC balance');
+  }
+}
+```
+
+## AI Agent Guide
+
+For a detailed guide on building AI agents that trade on RBS Prediction Markets, see **[SKILL.md](./SKILL.md)**.
+
+The guide includes:
+- Heartbeat monitoring for agent health
+- Trading strategy templates
+- Error recovery patterns
+- Safety rules and best practices
+
+## Links
+
+- [GitHub](https://github.com/ZZZSTUDIOS/RBS-PM)
+- [Monad Testnet Explorer](https://testnet.monadexplorer.com)
+- [Get Testnet USDC](https://faucet.monad.xyz)
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,342 @@
+# RBS Prediction Market Agent Skill
+
+You are an AI agent capable of trading on prediction markets on Monad blockchain.
+
+## Getting Started
+
+**You need wallet access to participate.** Ask your human operator:
+
+> "To trade on RBS Prediction Markets, I need a Monad testnet wallet with:
+>
+> 1. **MON** for gas fees - Get from https://faucet.monad.xyz
+> 2. **USDC** for trading and API calls - Each API call costs 0.0001 USDC
+>
+> Please provide me with a private key as the `PRIVATE_KEY` environment variable.
+> The wallet should have at least 0.1 MON and 1 USDC to start trading."
+
+## Installation
+
+```bash
+npm install @rbs-pm/sdk viem
+```
+
+## Heartbeat
+
+Run this heartbeat check regularly to ensure you can trade:
+
+```typescript
+import { RBSPMClient } from '@rbs-pm/sdk';
+
+interface HeartbeatStatus {
+  healthy: boolean;
+  wallet: string;
+  balances: { mon: string; usdc: string };
+  canTrade: boolean;
+  errors: string[];
+  timestamp: number;
+}
+
+async function heartbeat(): Promise<HeartbeatStatus> {
+  const errors: string[] = [];
+  const timestamp = Date.now();
+
+  try {
+    const client = new RBSPMClient({
+      privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+    });
+
+    const wallet = client.getAddress();
+    const usdc = await client.getUSDCBalance();
+    const mon = await client.getMONBalance();
+
+    // Minimum requirements
+    const hasGas = parseFloat(mon) >= 0.01;   // 0.01 MON for ~100 txs
+    const hasUsdc = parseFloat(usdc) >= 0.01; // 0.01 USDC for ~100 API calls
+
+    if (!hasGas) {
+      errors.push(`LOW GAS: ${mon} MON - Need refill from https://faucet.monad.xyz`);
+    }
+    if (!hasUsdc) {
+      errors.push(`LOW USDC: ${usdc} USDC - Cannot make API calls or trades`);
+    }
+
+    return {
+      healthy: errors.length === 0,
+      wallet,
+      balances: { mon, usdc },
+      canTrade: hasGas && hasUsdc,
+      errors,
+      timestamp,
+    };
+  } catch (err) {
+    return {
+      healthy: false,
+      wallet: 'unknown',
+      balances: { mon: '0', usdc: '0' },
+      canTrade: false,
+      errors: [`HEARTBEAT FAILED: ${err}`],
+      timestamp,
+    };
+  }
+}
+
+// Check every 10 minutes
+setInterval(async () => {
+  const status = await heartbeat();
+  console.log(`[${new Date().toISOString()}] Heartbeat:`, status);
+
+  if (!status.healthy) {
+    // Alert human operator
+    console.warn('AGENT UNHEALTHY - Notify operator:', status.errors);
+  }
+}, 10 * 60 * 1000);
+```
+
+## Initialize Client
+
+```typescript
+import { RBSPMClient } from '@rbs-pm/sdk';
+
+const client = new RBSPMClient({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+});
+
+console.log(`Wallet: ${client.getAddress()}`);
+console.log(`x402 Enabled: ${client.hasPaymentCapability()}`);
+```
+
+## Core Operations
+
+### 1. Discover Markets (0.0001 USDC)
+
+```typescript
+const markets = await client.getMarkets();
+
+// Find highest volume market
+const topMarket = markets.sort((a, b) =>
+  (b.total_volume || 0) - (a.total_volume || 0)
+)[0];
+
+console.log(`Top: ${topMarket.question}`);
+console.log(`Volume: $${topMarket.total_volume} USDC`);
+console.log(`YES: ${(topMarket.yes_price * 100).toFixed(1)}%`);
+```
+
+### 2. Get Real-Time Prices (0.0001 USDC)
+
+```typescript
+const prices = await client.getPrices(marketAddress);
+console.log(`YES: ${(prices.yes * 100).toFixed(1)}%`);
+console.log(`NO: ${(prices.no * 100).toFixed(1)}%`);
+```
+
+### 3. Check Your Position (0.0001 USDC)
+
+```typescript
+const position = await client.getPosition(marketAddress);
+console.log(`YES shares: ${position.yesSharesFormatted}`);
+console.log(`NO shares: ${position.noSharesFormatted}`);
+console.log(`Value: $${position.totalValue} USDC`);
+```
+
+### 4. Buy Shares (Gas + USDC)
+
+```typescript
+// Buy YES shares with 10 USDC
+const txHash = await client.buy(marketAddress, true, 10);
+console.log(`Buy tx: ${txHash}`);
+```
+
+### 5. Sell Shares (Gas)
+
+```typescript
+// Sell 5 YES shares
+const txHash = await client.sell(marketAddress, true, 5);
+console.log(`Sell tx: ${txHash}`);
+```
+
+### 6. Redeem Winnings (Gas)
+
+```typescript
+// After market resolves
+const txHash = await client.redeem(marketAddress);
+console.log(`Redeem tx: ${txHash}`);
+```
+
+## Trading Strategy Template
+
+```typescript
+async function runTradingLoop() {
+  const client = new RBSPMClient({
+    privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+  });
+
+  // 1. Heartbeat check
+  const status = await heartbeat();
+  if (!status.canTrade) {
+    console.error('Cannot trade:', status.errors);
+    return;
+  }
+
+  // 2. Get markets
+  const markets = await client.getMarkets();
+
+  for (const market of markets) {
+    // 3. Get current prices
+    const prices = await client.getPrices(market.address);
+
+    // 4. Research the question
+    const research = await researchQuestion(market.question);
+    // Example research steps:
+    // - Search for recent news about the topic
+    // - Check historical data and trends
+    // - Analyze expert opinions and forecasts
+    // - Consider base rates for similar events
+    // - Evaluate time until resolution
+
+    // 5. Form prediction based on research
+    const myPrediction = await formPrediction(market.question, research);
+    // Your prediction should be a probability between 0 and 1
+    // Example: 0.75 means you believe 75% chance of YES
+
+    // 6. Calculate edge (your prediction vs market price)
+    const edge = myPrediction - prices.yes;
+
+    // 7. Assess confidence based on research quality
+    const confidence = assessConfidence(research);
+    // Higher confidence = larger position size
+
+    // 8. Trade if edge exceeds threshold
+    if (Math.abs(edge) > 0.05 && confidence > 0.6) {
+      const isYes = edge > 0;
+      const amount = Math.min(
+        parseFloat(status.balances.usdc) * 0.1 * confidence, // Scale by confidence
+        10 // Max $10 per trade
+      );
+
+      console.log(`Trading: ${market.question}`);
+      console.log(`Research summary: ${research.summary}`);
+      console.log(`My prediction: ${(myPrediction * 100).toFixed(1)}%`);
+      console.log(`Market price: ${(prices.yes * 100).toFixed(1)}%`);
+      console.log(`Edge: ${(edge * 100).toFixed(1)}%, Confidence: ${(confidence * 100).toFixed(0)}%`);
+      console.log(`Side: ${isYes ? 'YES' : 'NO'}, Amount: $${amount.toFixed(2)}`);
+
+      await client.buy(market.address, isYes, amount);
+    }
+  }
+}
+
+// Research helper - implement based on your capabilities
+async function researchQuestion(question: string): Promise<{
+  summary: string;
+  sources: string[];
+  keyFactors: string[];
+  baseRate?: number;
+}> {
+  // Use web search, news APIs, or other data sources
+  // to gather information about the question
+
+  // Example implementation:
+  // 1. Search for news: "ETH price prediction 2026"
+  // 2. Check crypto analysis sites
+  // 3. Look at historical flippening attempts
+  // 4. Review expert forecasts
+
+  return {
+    summary: 'Research findings here...',
+    sources: ['source1.com', 'source2.com'],
+    keyFactors: ['factor1', 'factor2'],
+    baseRate: 0.3, // Historical base rate if available
+  };
+}
+
+// Form prediction based on research
+async function formPrediction(question: string, research: any): Promise<number> {
+  // Combine research findings into a probability estimate
+  // Consider: base rates, recent trends, expert consensus
+  return 0.5; // Return probability 0-1
+}
+
+// Assess confidence in your research
+function assessConfidence(research: any): number {
+  // Higher confidence when:
+  // - Multiple corroborating sources
+  // - Recent, relevant data available
+  // - Clear historical precedent
+  // Lower confidence when:
+  // - Conflicting information
+  // - Limited data available
+  // - Novel/unprecedented event
+  return 0.7; // Return confidence 0-1
+}
+
+// Run every hour
+setInterval(runTradingLoop, 60 * 60 * 1000);
+```
+
+## API Costs
+
+All API calls require x402 micropayments (automatic):
+
+| Operation | Cost | Description |
+|-----------|------|-------------|
+| `getMarkets()` | 0.0001 USDC | List all markets with stats |
+| `getPrices(market)` | 0.0001 USDC | On-chain prices |
+| `getMarketInfo(market)` | 0.0001 USDC | Full market details |
+| `getPosition(market)` | 0.0001 USDC | Your position |
+| `getMarketData(market)` | 0.0001 USDC | Premium analytics |
+| `getTradeInstructions()` | 0.0001 USDC | Encoded calldata |
+
+## Network Configuration
+
+| Property | Value |
+|----------|-------|
+| Network | Monad Testnet |
+| Chain ID | 10143 |
+| RPC | https://testnet-rpc.monad.xyz |
+| Explorer | https://testnet.monadexplorer.com |
+| USDC | 0x534b2f3A21130d7a60830c2Df862319e593943A3 |
+| Faucet | https://faucet.monad.xyz |
+
+## Error Recovery
+
+```typescript
+async function safeExecute<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      const msg = String(err);
+
+      if (msg.includes('insufficient funds')) {
+        console.error('OUT OF USDC - Alert human operator');
+        throw err; // Don't retry
+      }
+
+      if (msg.includes('gas')) {
+        console.error('OUT OF GAS - Need MON from faucet');
+        throw err; // Don't retry
+      }
+
+      if (i < retries - 1) {
+        console.warn(`Retry ${i + 1}/${retries}:`, msg);
+        await new Promise(r => setTimeout(r, 1000 * (i + 1)));
+      }
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+```
+
+## Safety Rules
+
+1. **Run heartbeat before trading** - Stop if unhealthy
+2. **Never bet more than 10% of balance** on a single trade
+3. **Keep reserves** - Maintain 100x API cost minimum (0.01 USDC)
+4. **Alert humans** when balances drop below thresholds
+5. **Log all trades** for audit and analysis
+
+## Links
+
+- GitHub: https://github.com/ZZZSTUDIOS/prediction-market-doppler
+- NPM: https://www.npmjs.com/package/@rbs-pm/sdk