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:**
- 🥉 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 <moltbookName>
```

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 <moltbookName> [--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 <moltbookName> <amount> [--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 <moltbookName> <amount> [--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 <moltbookName> [--limit <number>]
```

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 <name> [--chain <blockchain>]
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 <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
```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 -- <command>
```

### Lint
```bash
npm run lint
```

### Clean
```bash
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** 🏦💵