KarmaBank

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:

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:

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

> 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 

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  [--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   [--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   [--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  [--limit ]

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  [--chain ]
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 

"Credit limit exceeded"

"Mock mode enabled"

"Ledger not found"

"Circle wallet error"

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

Lint

npm run lint

Clean

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

License

ISC

Built for the USDC Agentic Hackathon 🏦💵

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.

"Agent not registered"

karmabank register 

"Credit limit exceeded"

"Mock mode enabled"

"Ledger not found"

"Circle wallet error"