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

# KarmaBank

A hackathon-ready **KarmaBank** that allows AI agents to borrow USDC based on their **Moltbook karma** reputation.

This project includes:
- A **credit scoring engine** (`src/scoring.ts`) that calculates a 0–100 credit score
- A **CLI tool** (`credit`) built with `commander`
- A lightweight **ledger** (file-backed JSON store) for demo/testing

> Status: CLI + docs are scaffolded for Day 2. Circle wallet + real Moltbook integration can be plugged in next.

---

## Features

- **Register** an agent by Moltbook name
- **Check** credit score, tier, max borrow, and score breakdown
- **Borrow** USDC (demo ledger-backed issuance)
- **Repay** USDC loans
- **History** shows loan records
- **List** shows all registered agents

---

## Installation

```bash
cd agent-credit-system
npm install
```

### Environment Variables

Create a `.env` file (optional):

```bash
MOLTBOOK_API_KEY=your_key_here
MOLTBOOK_API_BASE=https://www.moltbook.com/api/v1
CREDIT_LEDGER_PATH=.credit-ledger.json
```

> If `MOLTBOOK_API_KEY` is not set, the CLI will fall back to demo/mock profiles for scoring.

---

## Usage

### Run in Dev Mode

```bash
npm run dev -- --help
```

### Build + Run

```bash
npm run build
npm start -- --help
```

---

## CLI Commands

### Register

```bash
credit register <moltbookName>
```

Example:
```bash
credit register myagent
```

### Check

```bash
credit check <moltbookName> [--verbose]
```

Example:
```bash
credit check myagent --verbose
```

### Borrow

```bash
credit borrow <moltbookName> <amount> [--yes]
```

Example:
```bash
credit borrow myagent 100 --yes
```

### Repay

```bash
credit repay <moltbookName> <amount> [--yes]
```

Example:
```bash
credit repay myagent 50 --yes
```

### History

```bash
credit history <moltbookName> [--limit 10]
```

Example:
```bash
credit history myagent --limit 5
```

### List

```bash
credit list [--verbose]
```

---

## Credit Tiers

| Tier      | Score  | Max Borrow | Notes |
|-----------|--------|------------|-----...