@madgallery/rbs-pm-sdk 1.0.5 → 1.0.6

package/examples/ONBOARDING.md

@@ -0,0 +1,108 @@
+# Onboarding a New AI Agent
+
+## Quick Start (5 minutes)
+
+### 1. Create Project
+```bash
+mkdir my-trading-agent && cd my-trading-agent
+npm init -y
+npm install @madgallery/rbs-pm-sdk viem typescript ts-node @types/node
+```
+
+### 2. Generate Wallet
+```bash
+node -e "const { generatePrivateKey, privateKeyToAccount } = require('viem/accounts'); const pk = generatePrivateKey(); console.log('PRIVATE_KEY=' + pk); console.log('ADDRESS=' + privateKeyToAccount(pk).address);"
+```
+
+### 3. Fund Wallet
+- **MON (gas)**: https://faucet.monad.xyz
+- **USDC**: Need 10+ USDC on Monad testnet (chain ID 10143)
+
+### 4. Create .env
+```bash
+echo "PRIVATE_KEY=0x...your_key..." > .env
+```
+
+### 5. Copy Skill File
+```bash
+cp node_modules/@madgallery/rbs-pm-sdk/SKILL.md ./SKILL.md
+```
+
+---
+
+## Starting Your AI Agent
+
+Give your AI agent (Claude, GPT, etc.) this prompt:
+
+```
+You are a prediction market trading agent on Monad blockchain.
+
+Read SKILL.md to understand how to trade. Your wallet private key is
+in the PRIVATE_KEY environment variable.
+
+Your job:
+1. Check wallet balance (need MON for gas, USDC for trading)
+2. Discover active prediction markets
+3. Research questions and form predictions
+4. Trade when you find edge (your prediction vs market price)
+5. Run heartbeat every 10 minutes to monitor health
+6. Create interesting markets every 10 heartbeat cycles
+
+Start by checking if the wallet is ready to trade.
+```
+
+---
+
+## What the Agent Will Do
+
+Once the agent reads SKILL.md, it will:
+
+1. **Initialize** the RBSPMClient with your private key
+2. **Check balances** - MON for gas, USDC for trading
+3. **Discover markets** - Find active prediction markets
+4. **Research & Trade** - Form predictions, calculate edge, place bets
+5. **Monitor** - Run heartbeat checks, track portfolio
+6. **Create markets** - Every ~100 minutes, create a new market
+
+---
+
+## Verification
+
+Your agent should be able to answer:
+- "What's my wallet balance?"
+- "What markets are available?"
+- "What's the price on [market]?"
+- "Buy $5 of YES on [market]"
+
+If it can do these, it's working.
+
+---
+
+## Costs
+
+All API calls cost **0.0001 USDC** via x402 micropayments.
+This is automatic - the SDK handles payment signing.
+
+| Action | Cost |
+|--------|------|
+| List markets | 0.0001 USDC |
+| Get prices | 0.0001 USDC |
+| Check position | 0.0001 USDC |
+| Buy shares | 0.0001 + gas + amount |
+| Sell shares | 0.0001 + gas |
+
+---
+
+## Troubleshooting
+
+**"insufficient funds"**
+- Need more USDC. Minimum 10 USDC required.
+
+**"gas required exceeds allowance"**
+- Need MON. Get from https://faucet.monad.xyz
+
+**"Payment required"**
+- x402 payment failing. Check USDC balance.
+
+**No markets showing**
+- Markets may not be deployed yet, or indexer is down.

package/examples/starter-agent.ts

@@ -0,0 +1,149 @@
+/**
+ * RBS Prediction Market - Starter Agent Template
+ *
+ * Setup:
+ * 1. npm install @madgallery/rbs-pm-sdk viem
+ * 2. Set PRIVATE_KEY environment variable
+ * 3. Fund wallet with MON (gas) and USDC (trading)
+ * 4. Run: npx ts-node starter-agent.ts
+ */
+
+import { RBSPMClient } from '@madgallery/rbs-pm-sdk';
+
+// Initialize client with your wallet
+const client = new RBSPMClient({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+});
+
+// ============================================
+// STEP 1: Check wallet health
+// ============================================
+async function checkWallet() {
+  const address = client.getAddress();
+  const mon = await client.getMONBalance();
+  const usdc = await client.getUSDCBalance();
+
+  console.log('\n=== WALLET STATUS ===');
+  console.log(`Address: ${address}`);
+  console.log(`MON (gas): ${mon}`);
+  console.log(`USDC (trading): ${usdc}`);
+
+  const ready = parseFloat(mon) >= 0.01 && parseFloat(usdc) >= 10;
+  console.log(`Ready to trade: ${ready ? 'YES' : 'NO'}`);
+
+  if (!ready) {
+    if (parseFloat(mon) < 0.01) {
+      console.log('⚠️  Need MON for gas: https://faucet.monad.xyz');
+    }
+    if (parseFloat(usdc) < 10) {
+      console.log('⚠️  Need minimum 10 USDC for trading');
+    }
+  }
+
+  return { address, mon, usdc, ready };
+}
+
+// ============================================
+// STEP 2: Discover markets
+// ============================================
+async function discoverMarkets() {
+  console.log('\n=== AVAILABLE MARKETS ===');
+
+  const markets = await client.getMarkets();
+
+  if (markets.length === 0) {
+    console.log('No markets found');
+    return [];
+  }
+
+  for (const market of markets) {
+    const yesPercent = (market.yes_price * 100).toFixed(0);
+    const noPercent = (market.no_price * 100).toFixed(0);
+    console.log(`\n📊 ${market.question}`);
+    console.log(`   Address: ${market.address}`);
+    console.log(`   YES: ${yesPercent}% | NO: ${noPercent}%`);
+    console.log(`   Volume: $${market.total_volume || 0} USDC`);
+  }
+
+  return markets;
+}
+
+// ============================================
+// STEP 3: Check your positions
+// ============================================
+async function checkPortfolio() {
+  console.log('\n=== YOUR PORTFOLIO ===');
+
+  const portfolio = await client.getPortfolio();
+
+  if (portfolio.positions.length === 0) {
+    console.log('No positions yet');
+    return portfolio;
+  }
+
+  for (const pos of portfolio.positions) {
+    console.log(`\n📈 ${pos.marketQuestion}`);
+    console.log(`   YES shares: ${pos.yesSharesFormatted}`);
+    console.log(`   NO shares: ${pos.noSharesFormatted}`);
+    console.log(`   Value: $${pos.totalValue} USDC`);
+    if (pos.resolved) {
+      console.log('   ⚡ RESOLVED - Call redeem() to collect!');
+    }
+  }
+
+  console.log(`\nTotal value: $${portfolio.summary.totalValue} USDC`);
+  return portfolio;
+}
+
+// ============================================
+// STEP 4: Make a trade (example)
+// ============================================
+async function exampleTrade(marketAddress: `0x${string}`, betYes: boolean, amountUsdc: number) {
+  console.log('\n=== PLACING TRADE ===');
+  console.log(`Market: ${marketAddress}`);
+  console.log(`Side: ${betYes ? 'YES' : 'NO'}`);
+  console.log(`Amount: $${amountUsdc} USDC`);
+
+  // Get current prices first
+  const prices = await client.getPrices(marketAddress);
+  console.log(`Current price: ${(prices.yes * 100).toFixed(1)}% YES / ${(prices.no * 100).toFixed(1)}% NO`);
+
+  // Execute trade
+  const txHash = await client.buy(marketAddress, betYes, amountUsdc);
+  console.log(`✅ Trade submitted: ${txHash}`);
+  console.log(`   View: https://testnet.monadexplorer.com/tx/${txHash}`);
+
+  return txHash;
+}
+
+// ============================================
+// MAIN: Run the agent
+// ============================================
+async function main() {
+  console.log('🤖 RBS Prediction Market Agent Starting...\n');
+
+  // Step 1: Check wallet
+  const wallet = await checkWallet();
+  if (!wallet.ready) {
+    console.log('\n❌ Wallet not ready. Fund it first.');
+    return;
+  }
+
+  // Step 2: Discover markets
+  const markets = await discoverMarkets();
+  if (markets.length === 0) {
+    console.log('\n❌ No markets to trade.');
+    return;
+  }
+
+  // Step 3: Check existing positions
+  await checkPortfolio();
+
+  // Step 4: Example trade (uncomment to execute)
+  // const firstMarket = markets[0].address as `0x${string}`;
+  // await exampleTrade(firstMarket, true, 1); // Buy $1 of YES
+
+  console.log('\n✅ Agent ready. Modify this script to implement your trading strategy.');
+}
+
+main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madgallery/rbs-pm-sdk",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "SDK for AI agents to trade on RBS Prediction Markets (Monad)",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -8,7 +8,8 @@
   "files": [
     "dist",
     "README.md",
-    "SKILL.md"
+    "SKILL.md",
+    "examples"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",