@madgallery/rbs-pm-sdk 1.0.4 → 1.0.5

package/SKILL.md

@@ -1,193 +1,100 @@
 # RBS Prediction Market Agent Skill
 
-You are an AI agent capable of trading on prediction markets on Monad blockchain.
+Trade on prediction markets using AI agents on Monad blockchain.
 
-## Getting Started
+---
 
-**You need wallet access to participate.** Ask your human operator:
+## For Humans: How to Use This Agent
 
-> "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, API calls, and liquidity - Minimum 10 USDC buffer required
->
-> Please provide me with a private key as the `PRIVATE_KEY` environment variable.
-> The wallet should have at least 0.1 MON and **10 USDC** to operate properly."
+### Step 1: Fund a Wallet
 
-## x402 Payment Requirement
+Your agent needs a Monad testnet wallet. Set it up:
 
-**All API operations require x402 micropayments.** The SDK handles this automatically when you provide a private key.
+1. Create a new wallet (or use an existing one)
+2. Get **MON** for gas: https://faucet.monad.xyz
+3. Get **USDC** for trading: minimum **10 USDC** required
+4. Set the private key as environment variable: `PRIVATE_KEY=0x...`
 
-How it works:
-1. Every API call costs **0.0001 USDC** (paid via x402 protocol)
-2. The SDK signs a USDC `TransferWithAuthorization` using your private key
-3. The payment is verified and settled by the x402 facilitator
-4. You receive the API response
+### Step 2: Talk to Your Agent
 
-**Important:** Without a private key, you cannot make x402 payments and API calls will fail with HTTP 402.
+Once funded, just talk to your agent naturally:
 
-```typescript
-// This client is x402-enabled and can make paid API calls
-const client = new RBSPMClient({
-  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
-});
-
-// Check if x402 payments are configured
-console.log('x402 Enabled:', client.hasPaymentCapability()); // true
-```
+**Check Status:**
+- "What's my balance?"
+- "Show me my portfolio"
+- "Am I ready to trade?"
 
-## Installation
+**Explore Markets:**
+- "What prediction markets are available?"
+- "Show me the hottest markets"
+- "What's the price on [market question]?"
 
-```bash
-npm install @madgallery/rbs-pm-sdk viem
-```
+**Trading:**
+- "Buy $5 of YES on [market]"
+- "I think [event] will happen - bet $10 on it"
+- "Sell my position on [market]"
+- "What positions do I have?"
 
-## Heartbeat
+**After Resolution:**
+- "Check if any of my markets resolved"
+- "Redeem my winnings"
 
-Run this heartbeat check regularly to monitor wallet health, portfolio status, and discover new markets:
+**Market Creation:**
+- "Create a market about [topic]"
+- "I want to make a prediction market for [event]"
 
-```typescript
-import { RBSPMClient } from '@madgallery/rbs-pm-sdk';
+### Example Conversations
 
-interface HeartbeatStatus {
-  healthy: boolean;
-  wallet: string;
-  balances: { mon: string; usdc: string };
-  portfolio: {
-    totalPositions: number;
-    totalValue: string;
-    positions: Array<{
-      market: string;
-      question: string;
-      value: string;
-      resolved: boolean;
-    }>;
-  };
-  newMarkets: Array<{
-    address: string;
-    question: string;
-    yesPrice: number;
-  }>;
-  canTrade: boolean;
-  errors: string[];
-  timestamp: number;
-}
+```
+Human: What's my balance?
 
-// Track markets we've already seen
-const knownMarkets = new Set<string>();
+Agent: Your wallet 0x742d...3a91 has:
+  - 0.5 MON (gas)
+  - 47.32 USDC (trading balance)
+  You're ready to trade!
+```
 
-async function heartbeat(): Promise<HeartbeatStatus> {
-  const errors: string[] = [];
-  const timestamp = Date.now();
+```
+Human: What markets can I trade on?
 
-  try {
-    const client = new RBSPMClient({
-      privateKey: process.env.PRIVATE_KEY as `0x${string}`,
-    });
+Agent: I found 3 active markets:
+  1. "Will ETH hit $5,000 by March 2026?" - YES: 35%, NO: 65%
+  2. "Will Bitcoin exceed $100k in Q1 2026?" - YES: 72%, NO: 28%
+  3. "Will SpaceX launch Starship before April?" - YES: 85%, NO: 15%
 
-    const wallet = client.getAddress();
-    const usdc = await client.getUSDCBalance();
-    const mon = await client.getMONBalance();
+  Which one interests you?
+```
 
-    // Minimum requirements
-    const hasGas = parseFloat(mon) >= 0.01;   // 0.01 MON for ~100 txs
-    const hasUsdc = parseFloat(usdc) >= 10;   // 10 USDC minimum liquidity buffer
+```
+Human: I think Bitcoin will hit 100k. Bet $10 on it.
 
-    if (!hasGas) {
-      errors.push(`LOW GAS: ${mon} MON - Need refill from https://faucet.monad.xyz`);
-    }
-    if (!hasUsdc) {
-      errors.push(`LOW USDC: ${usdc} USDC - Need minimum 10 USDC liquidity buffer`);
-    }
+Agent: Placing bet on "Will Bitcoin exceed $100k in Q1 2026?"
+  - Side: YES (currently 72%)
+  - Amount: $10 USDC
+  - Estimated shares: 13.89 YES tokens
 
-    // Check portfolio health (costs 0.0001 USDC)
-    const portfolio = await client.getPortfolio();
-    const portfolioSummary = {
-      totalPositions: portfolio.summary.totalPositions,
-      totalValue: portfolio.summary.totalValue,
-      positions: portfolio.positions.map(p => ({
-        market: p.marketAddress,
-        question: p.marketQuestion,
-        value: p.totalValue,
-        resolved: p.resolved,
-      })),
-    };
-
-    // Check for positions that need attention (resolved markets)
-    const resolvedPositions = portfolio.positions.filter(p => p.resolved);
-    if (resolvedPositions.length > 0) {
-      errors.push(`${resolvedPositions.length} resolved market(s) - call redeem() to collect winnings`);
-    }
+  Transaction submitted: 0x7a3f...
+  ✓ Bought 13.89 YES shares for $10 USDC
+```
 
-    // Discover new markets (costs 0.0001 USDC)
-    const allMarkets = await client.getMarkets();
-    const newMarkets = allMarkets
-      .filter(m => !knownMarkets.has(m.address))
-      .map(m => {
-        knownMarkets.add(m.address);
-        return {
-          address: m.address,
-          question: m.question,
-          yesPrice: m.yesPrice,
-        };
-      });
-
-    return {
-      healthy: errors.length === 0,
-      wallet,
-      balances: { mon, usdc },
-      portfolio: portfolioSummary,
-      newMarkets,
-      canTrade: hasGas && hasUsdc,
-      errors,
-      timestamp,
-    };
-  } catch (err) {
-    return {
-      healthy: false,
-      wallet: 'unknown',
-      balances: { mon: '0', usdc: '0' },
-      portfolio: { totalPositions: 0, totalValue: '0', positions: [] },
-      newMarkets: [],
-      canTrade: false,
-      errors: [`HEARTBEAT FAILED: ${err}`],
-      timestamp,
-    };
-  }
-}
+```
+Human: Show me my portfolio
 
-// Track heartbeat cycles for market creation
-let heartbeatCount = 0;
+Agent: Your portfolio across all markets:
 
-// Check every 10 minutes
-setInterval(async () => {
-  heartbeatCount++;
-  const status = await heartbeat();
-  console.log(`[${new Date().toISOString()}] Heartbeat #${heartbeatCount}:`, status);
+  1. "Will Bitcoin exceed $100k in Q1 2026?"
+     - 13.89 YES shares worth $10.42
+     - Current price: 75% (you bought at 72%)
+     - Unrealized P&L: +$0.42
 
-  // Log portfolio summary
-  console.log(`Portfolio: ${status.portfolio.totalPositions} positions worth $${status.portfolio.totalValue}`);
+  Total value: $10.42 USDC
+```
 
-  // Alert on new markets
-  if (status.newMarkets.length > 0) {
-    console.log(`NEW MARKETS DISCOVERED:`);
-    for (const m of status.newMarkets) {
-      console.log(`  - ${m.question} (YES: ${(m.yesPrice * 100).toFixed(1)}%)`);
-    }
-  }
+---
 
-  if (!status.healthy) {
-    // Alert human operator
-    console.warn('AGENT UNHEALTHY - Notify operator:', status.errors);
-  }
+## For Agents: Technical Reference
 
-  // Every 10 heartbeats (~100 minutes), create a market you find interesting
-  if (heartbeatCount % 10 === 0 && status.canTrade) {
-    console.log(`\n=== MARKET CREATION CYCLE (every 10 heartbeats) ===`);
-    await createInterestingMarket();
-  }
-}, 10 * 60 * 1000);
-```
+This section contains implementation details for AI agents using the SDK programmatically.
 
 ## Market Creation
 
@@ -357,6 +264,80 @@ const txHash = await client.redeem(marketAddress);
 console.log(`Redeem tx: ${txHash}`);
 ```
 
+## Heartbeat Monitoring
+
+Run this heartbeat check regularly to monitor wallet health, portfolio status, and discover new markets:
+
+```typescript
+import { RBSPMClient } from '@madgallery/rbs-pm-sdk';
+
+interface HeartbeatStatus {
+  healthy: boolean;
+  wallet: string;
+  balances: { mon: string; usdc: string };
+  portfolio: { totalPositions: number; totalValue: string };
+  newMarkets: Array<{ address: string; question: string; yesPrice: number }>;
+  canTrade: boolean;
+  errors: string[];
+}
+
+const knownMarkets = new Set<string>();
+
+async function heartbeat(): Promise<HeartbeatStatus> {
+  const errors: string[] = [];
+  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();
+
+  const hasGas = parseFloat(mon) >= 0.01;
+  const hasUsdc = parseFloat(usdc) >= 10;  // 10 USDC minimum
+
+  if (!hasGas) errors.push(`LOW GAS: ${mon} MON`);
+  if (!hasUsdc) errors.push(`LOW USDC: ${usdc} - need 10 minimum`);
+
+  // Check portfolio (0.0001 USDC)
+  const portfolio = await client.getPortfolio();
+
+  // Discover new markets (0.0001 USDC)
+  const allMarkets = await client.getMarkets();
+  const newMarkets = allMarkets
+    .filter(m => !knownMarkets.has(m.address))
+    .map(m => {
+      knownMarkets.add(m.address);
+      return { address: m.address, question: m.question, yesPrice: m.yesPrice };
+    });
+
+  return {
+    healthy: errors.length === 0,
+    wallet,
+    balances: { mon, usdc },
+    portfolio: {
+      totalPositions: portfolio.summary.totalPositions,
+      totalValue: portfolio.summary.totalValue,
+    },
+    newMarkets,
+    canTrade: hasGas && hasUsdc,
+    errors,
+  };
+}
+
+// Run every 10 minutes, create market every 10 cycles
+let heartbeatCount = 0;
+setInterval(async () => {
+  heartbeatCount++;
+  const status = await heartbeat();
+  console.log(`Heartbeat #${heartbeatCount}:`, status);
+
+  if (heartbeatCount % 10 === 0 && status.canTrade) {
+    await createInterestingMarket();
+  }
+}, 10 * 60 * 1000);
+```
+
 ## Trading Strategy Template
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madgallery/rbs-pm-sdk",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "SDK for AI agents to trade on RBS Prediction Markets (Monad)",
   "main": "dist/index.js",
   "module": "dist/index.mjs",