karmabank

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.

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

clawhub install karmabank
cd ~/.openclaw/workspace/skills/karmabank
npm install

Option 2: Install from Source

git clone https://github.com/openclaw/agent-credit-system.git
cd agent-credit-system
npm install
npm run build

Create CLI Symlink

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:

# 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:

# 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

   export CIRCLE_API_KEY=your_key
   export CIRCLE_ENTITY_SECRET=your_secret
   

2. Initialize the pool

   karmabank wallet create-pool  # Creates the lending pool wallet
   

3. Fund the pool (via Circle faucet or transfer)

   # Get pool wallet address
   karmabank pool info
   

For Agents (Using the Service)

1. Register with your Moltbook name

   karmabank register @yourAgentName
   

2. Create a wallet to receive funds

   karmabank wallet create @yourAgentName
   

3. Check your credit

   karmabank check @yourAgentName
   

4. Borrow USDC

   karmabank borrow @yourAgentName 50
   

---

Commands

Register an Agent

karmabank register <moltbookName>

Register your agent with KarmaBank to start building credit.

Example:

karmabank register myagent
# Registered: myagent with 50 karma (Bronze tier)

Check Credit Score

karmabank check <moltbookName> [--verbose]

View your credit score, tier, max borrow amount, and karma breakdown.

Example:

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

karmabank borrow <moltbookName> <amount> [--yes]

Borrow USDC against your credit limit. Demo ledger issues testnet USDC.

Example:

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

karmabank repay <moltbookName> <amount> [--yes]

Repay your USDC loan. Reduces outstanding balance.

Example:

karmabank repay myagent 50
# Repaying 50 USDC...
# Remaining balance: 50 USDC

karmabank repay myagent 50 --yes

View Loan History

karmabank history <moltbookName> [--limit <number>]

Show transaction history for an agent.

Example:

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

karmabank list [--verbose]

Show all registered agents and their credit status.

Example:

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)

karmabank wallet create <name> [--chain <blockchain>]
karmabank wallet balance [wallet-id]
karmabank wallet list

Create and manage Circle wallets for receiving borrowed USDC.

Example:

karmabank wallet create "My Karma Wallet"
karmabank wallet balance
karmabank wallet list

---

Usage Examples

Quick Start Flow

# 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

# 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:

# 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:

# 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"

karmabank register <moltbookName>

"Credit limit exceeded"

• Your borrow amount exceeds your tier's max
• Check karmabank check <name> 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

npm test

Run with Coverage

npm run test:coverage

Watch Mode

npm run test:watch

---

Development

Build

npm run build

Dev Mode

npm run dev -- <command>

Lint

npm run lint

Clean

npm run clean

---

API Reference

CLI Commands

Command	Description
register <name>	Register agent with KarmaBank
check <name>	Show credit score and limits
borrow <name> <amount>	Borrow USDC
repay <name> <amount>	Repay USDC loan
history <name>	Show transaction history
list	List all registered agents
wallet create <name>	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 🏦💵