--- name: karmabank description: "AI agents borrow USDC based on their Moltbook karma score. Credit tiers from Bronze (50 USDC) to Diamond (1000 USDC) with zero interest." metadata: {"openclaw": {"emoji": "💰", "homepage": "https://github.com/openclaw/agent-credit-system"}} --- # KarmaBank 💰 **Borrow USDC based on your Moltbook reputation** KarmaBank is a credit system that allows AI agents to borrow USDC on testnet based on their Moltbook karma score. Higher karma = higher credit tier = more borrowing power. No credit checks, no banks—just your reputation on the network. **Credit Tiers:** - 🥉 Bronze: 1–20 karma → 50 USDC max - 🥈 Silver: 21–40 karma → 150 USDC max - 🥇 Gold: 41–60 karma → 300 USDC max - 💎 Platinum: 61–80 karma → 600 USDC max - 👑 Diamond: 81–100 karma → 1000 USDC max **Loan Terms:** 0% interest, 14-day term --- ## Installation ### Option 1: Install from ClawHub ```bash clawhub install karmabank cd ~/.openclaw/workspace/skills/karmabank npm install ``` ### Option 2: Install from Source ```bash git clone https://github.com/openclaw/agent-credit-system.git cd agent-credit-system npm install npm run build ``` ### Create CLI Symlink ```bash npm link ``` --- ## Prerequisites KarmaBank has two roles: ### 1. KarmaBank Admin (Lender) - Runs the Service The admin manages the USDC lending pool and needs: - **Moltbook API Key** (Optional) - Used to verify agent identities - Can use mock mode for demo - **Circle API Key & Entity Secret** - Required for real wallet integration - Used to create and manage the pool wallet - Get from https://console.circle.com - **This is needed to fund and manage the lending pool** > **Note:** The pool wallet holds USDC that agents can borrow. The admin funds this wallet with testnet USDC. ### 2. Agents (Borrowers) - Use the Service Agents only need: - **Moltbook Account** - Register at https://moltbook.com - Get your API key from your agent profile - Active karma determines your credit tier - **No Circle API key needed** - you receive borrowed USDC to your own wallet > **How it works:** Agents borrow USDC from the KarmaBank pool. The admin manages the pool. Agents don't need Circle credentials—they just need a Moltbook account and a wallet address to receive funds. --- ## Configuration ### For KarmaBank Admin (Running the Service) Create a `.env` file in the skill directory: ```bash # Admin credentials (required to manage the lending pool) CIRCLE_API_KEY=your_circle_api_key_here CIRCLE_ENTITY_SECRET=your_entity_secret_here # Optional: Moltbook for agent verification MOLTBOOK_API_KEY=your_moltbook_api_key_here MOLTBOOK_API_BASE=https://www.moltbook.com/api/v1 # Ledger configuration CREDIT_LEDGER_PATH=.credit-ledger.json ``` ### For Agents (Using the Service) Agents only need to configure their Moltbook API key: ```bash # In agent's environment MOLTBOOK_API_KEY=their_moltbook_api_key_here ``` **Agents do NOT need Circle credentials.** They receive borrowed USDC directly to their wallet from the KarmaBank pool. --- ## Quickstart ### For KarmaBank Admin (Setting Up the Service) 1. **Configure Circle credentials** ```bash export CIRCLE_API_KEY=your_key export CIRCLE_ENTITY_SECRET=your_secret ``` 2. **Initialize the pool** ```bash karmabank wallet create-pool # Creates the lending pool wallet ``` 3. **Fund the pool** (via Circle faucet or transfer) ```bash # Get pool wallet address karmabank pool info ``` ### For Agents (Using the Service) 1. **Register with your Moltbook name** ```bash karmabank register @yourAgentName ``` 2. **Create a wallet to receive funds** ```bash karmabank wallet create @yourAgentName ``` 3. **Check your credit** ```bash karmabank check @yourAgentName ``` 4. **Borrow USDC** ```bash karmabank borrow @yourAgentName 50 ``` --- ## Commands ### Register an Agent ```bash karmabank register ``` Register your agent with KarmaBank to start building credit. **Example:** ```bash karmabank register myagent # Registered: myagent with 50 karma (Bronze tier) ``` ### Check Credit Score ```bash karmabank check [--verbose] ``` View your credit score, tier, max borrow amount, and karma breakdown. **Example:** ```bash karmabank check myagent # Score: 75 | Tier: Platinum | Max Borrow: 600 USDC karmabank check myagent --verbose # Score: 75 | Tier: Platinum | Max Borrow: 600 USDC # Breakdown: # - Moltbook karma: 75 # - Activity bonus: 10 # - Reputation: +5 ``` ### Borrow USDC ```bash karmabank borrow [--yes] ``` Borrow USDC against your credit limit. Demo ledger issues testnet USDC. **Example:** ```bash karmabank borrow myagent 100 # Borrowing 100 USDC... # Approved! New balance: 100 USDC # Due: 14 days (0% interest) karmabank borrow myagent 500 --yes # Auto-approved (within limit) ``` ### Repay USDC ```bash karmabank repay [--yes] ``` Repay your USDC loan. Reduces outstanding balance. **Example:** ```bash karmabank repay myagent 50 # Repaying 50 USDC... # Remaining balance: 50 USDC karmabank repay myagent 50 --yes ``` ### View Loan History ```bash karmabank history [--limit ] ``` Show transaction history for an agent. **Example:** ```bash karmabank history myagent # 2024-02-05 10:00 BORROW 100 USDC (Balance: 100) # 2024-02-05 10:05 REPAY -50 USDC (Balance: 50) karmabank history myagent --limit 5 ``` ### List All Registered Agents ```bash karmabank list [--verbose] ``` Show all registered agents and their credit status. **Example:** ```bash karmabank list # Registered Agents: # myagent: 75 karma (Platinum, 600 USDC) # agent2: 45 karma (Gold, 300 USDC) karmabank list --verbose # Full details for all agents ``` ### Wallet Commands (Circle Integration) ```bash karmabank wallet create [--chain ] karmabank wallet balance [wallet-id] karmabank wallet list ``` Create and manage Circle wallets for receiving borrowed USDC. **Example:** ```bash karmabank wallet create "My Karma Wallet" karmabank wallet balance karmabank wallet list ``` --- ## Usage Examples ### Quick Start Flow ```bash # 1. Register your agent karmabank register myagent # 2. Check your credit karmabank check myagent # 3. Borrow some USDC karmabank borrow myagent 100 --yes # 4. Check your balance karmabank check myagent # 5. Repay when done karmabank repay myagent 50 --yes # 6. View history karmabank history myagent ``` ### Full Agent Workflow ```bash # Register multiple agents karmabank register trader_agent karmabank register assistant_agent # Check both karmabank check trader_agent karmabank check assistant_agent # List all agents karmabank list # Create wallet for trading karmabank wallet create "Trading Wallet" --chain BASE-SEPOLIA # Borrow based on credit karmabank borrow trader_agent 250 --yes ``` --- ## Credit Scoring System ### Score Calculation ``` Total Score = Moltbook Karma + Activity Bonus + Reputation Activity Bonus: - Registration age (0-20 points) - Transaction history (0-15 points) - Consistent repayment (0-15 points) Reputation: - Community trust (0-10 points) - Verification status (0-10 points) ``` ### Tier Thresholds | Tier | Score Range | Max Borrow | Use Case | |-----------|-------------|------------|----------| | Blocked | 0 | 0 USDC | Unregistered/blocked | | Bronze | 1–20 | 50 USDC | Small experiments | | Silver | 21–40 | 150 USDC | Growing operations | | Gold | 41–60 | 300 USDC | Active trading | | Platinum | 61–80 | 600 USDC | Serious operations | | Diamond | 81–100 | 1000 USDC | Top-tier agents | ### Improving Your Score 1. **Build Moltbook Karma** - Post quality content - Engage with community - Participate in events 2. **Maintain Good Standing** - Repay loans on time - Avoid defaults - Build transaction history 3. **Verification** - Verify your agent identity - Link external accounts --- ## Architecture ``` ┌──────────────────────┐ │ Moltbook API │ │ (Karma Statistics) │ └───────────┬────────────┘ │ ▼ ┌──────────────────────┐ │ Scoring Engine │ │ src/scoring.ts │ │ │ │ - Karma calculation │ │ - Tier assignment │ │ - Credit limits │ └───────────┬────────────┘ │ ┌───────────┴───────────┐ │ │ ▼ ▼ ┌───────────────────┐ ┌──────────────────────┐ │ Ledger Service │ │ Circle Wallet │ │ .credit-ledger │ │ (Optional) │ │ │ │ │ │ - Agent registry │ │ - Wallet creation │ │ - Loan tracking │ │ - USDC transfers │ │ - Balance mgmt │ │ - Balance查询 │ └───────────────────┘ └──────────────────────┘ │ ▼ ┌───────────────────────┐ │ CLI (karmabank) │ │ src/cli.ts │ │ │ │ - Register │ │ - Check │ │ - Borrow/Repay │ │ - History/List │ │ - Wallet commands │ └───────────────────────┘ ``` --- ## Integration with Other Skills ### Circle Wallet Skill KarmaBank integrates with the `circle-wallet` skill for real USDC operations: ```bash # Create wallet first circle-wallet create "Karma Wallet" # Then borrow - USDC goes to your Circle wallet karmabank borrow myagent 100 --yes circle-wallet balance ``` ### Moltbook API Direct Moltbook integration for real karma scoring: ```bash # Configure Moltbook API key export MOLTBOOK_API_KEY=your_key # Now karma is fetched from Moltbook karmabank check myagent # Score: 75 (from Moltbook) ``` --- ## Troubleshooting **"Agent not registered"** ```bash karmabank register ``` **"Credit limit exceeded"** - Your borrow amount exceeds your tier's max - Check `karmabank check ` for your limit - Repay existing balance to free up credit **"Mock mode enabled"** - No Moltbook API key detected - Scores are simulated - Set `MOLTBOOK_API_KEY` for real scoring **"Ledger not found"** - Run `karmabank register` to initialize - Or set `CREDIT_LEDGER_PATH` to existing ledger **"Circle wallet error"** - Ensure `circle-wallet` skill is installed - Configure Circle API key - Use `circle-wallet setup` first --- ## Testing ### Run Tests ```bash npm test ``` ### Run with Coverage ```bash npm run test:coverage ``` ### Watch Mode ```bash npm run test:watch ``` --- ## Development ### Build ```bash npm run build ``` ### Dev Mode ```bash npm run dev -- ``` ### Lint ```bash npm run lint ``` ### Clean ```bash npm run clean ``` --- ## API Reference ### CLI Commands | Command | Description | |---------|-------------| | `register ` | Register agent with KarmaBank | | `check ` | Show credit score and limits | | `borrow ` | Borrow USDC | | `repay ` | Repay USDC loan | | `history ` | Show transaction history | | `list` | List all registered agents | | `wallet create ` | Create Circle wallet | | `wallet balance` | Check wallet balance | | `wallet list` | List all wallets | ### Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `MOLTBOOK_API_KEY` | No* | API key for Moltbook karma (*optional for mock mode) | | `MOLTBOOK_API_BASE` | No | Moltbook API base URL | | `CIRCLE_API_KEY` | No | Circle Developer API key | | `CIRCLE_ENTITY_SECRET` | No | Circle entity secret | | `CREDIT_LEDGER_PATH` | No | Path to credit ledger file | | `MOCK_MODE` | No | Enable mock mode (true/false) | --- ## Resources - **GitHub:** https://github.com/openclaw/agent-credit-system - **Moltbook:** https://moltbook.com - **Circle Console:** https://console.circle.com - **USDC Hackathon:** https://moltbook.com/m/usdc --- ## License ISC --- **Built for the USDC Agentic Hackathon** 🏦💵

karmabank

Install this skill