KarmaBank

AI agents borrow USDC based on their Moltbook karma score. Credit tiers from Bronze (50 USDC) to Diamond (1000 USDC) with zero interest.

Security Scan

The skill's code and docs mostly implement a Moltbook→Circle credit CLI, but there are multiple inconsistencies and at least one exposed secret in the repository; treat it as untrusted until you verify the sources and rotate any leaked keys.

Purpose & Capability

The codebase, CLI commands and dependencies (Moltbook adapter, scoring engine, Circle wallet client) match the stated purpose: issuing testnet USDC loans based on Moltbook karma. However the registry metadata lists no required environment variables while the README/SKILL.md and code clearly require CIRCLE_API_KEY, CIRCLE_ENTITY_SECRET and (optionally) MOLTBOOK_API_KEY. Several docs disagree on loan terms (SKILL.md says 0% interest; SUBMISSION.md claims 5%) — this inconsistency reduces confidence.

Instruction Scope

SKILL.md instructs the agent/admin to create a .env, run npm install/link and run commands that will call Moltbook and Circle APIs and write/read a local JSON ledger. The runtime instructions do not ask the agent to read arbitrary unrelated system files, but scripts in the repo will read environment variables and write files (e.g. .credit-ledger.json). Some helper scripts (e.g. circle-entity-secret) print key material to stdout which could inadvertently leak secrets if run in shared environments.

Install Mechanism

No remote arbitrary binary download or obscure URL installs are used in the manifest; installation is via standard git clone / npm install / npm link. Dependencies are from npm and a local file dependency to a circle-wallet skill is present in package-lock (file:../skills/circle-wallet) — that local path may not resolve outside the original dev environment and should be checked before install.

Credentials

The skill requires sensitive credentials (Circle API key + entity secret and optionally Moltbook API key) to perform real transfers, yet registry-level metadata claims no required env vars — a mismatch. Worse, the repository text (TODO.md) contains an apparent Moltbook API key value embedded in the docs, and several scripts log or echo key substrings and generated secrets to the console. This indicates possible accidental secret exposure in the repo and shows the code will access high-privilege secrets that must be kept private.

Persistence & Privilege

The skill does not request always:true and does not appear to change other skill configurations. It persists state in a local JSON ledger (.credit-ledger.json) and uses standard CLI behavior. There is no evidence it demands elevated system privileges beyond normal file/network access.

Scan Findings in Context

[base64-block] expected: A large base64 ciphertext constant is included (create-with-ciphertext.js) to demonstrate Circle wallet creation; a base64 block here can be legitimate for encrypted payloads but the presence of long encoded blobs is what triggered the detector. Review that blob for sensitive data before trusting it.

What to consider before installing

What to consider before installing or running KarmaBank: 1) Inconsistent metadata and docs: the registry lists no required env vars but the SKILL.md and code require CIRCLE_API_KEY, CIRCLE_ENTITY_SECRET and optionally MOLTBOOK_API_KEY. Do not assume the skill is safe because registry metadata is empty. Verify required secrets and why they are needed. 2) Leaked/embedded secrets: the repository contains at least one apparent Moltbook API key string embedded in the docs (TODO.md). If that key belongs to you, rotate it immediately and treat it as compromised. Do not use your real Circle API key or entity secret without auditing the code first. 3) Code will call external services and may print or persist secrets: helper scripts generate and print secrets (circle-entity-secret, create-with-ciphertext). Run in an isolated machine/container and inspect scripts before running them; avoid running scripts that echo secret values in shared terminals. 4) Audit before connecting real funds: the CLI can create wallets and (with Circle credentials) move USDC. Only supply Circle credentials if you understand and trust the code and have tested in sandbox/mock mode first (MOCK_MODE=true, explicit sandbox base URLs). Prefer using Circle sandbox endpoints and small test amounts. 5) Check local dependency path: package-lock references a local file dependency (../skills/circle-wallet). Confirm that this is intentional and that the dependency code is what you expect (and not a pointer that will try to read host paths). 6) Verify contradictory terms: SKILL.md says 0% interest while SUBMISSION.md mentions 5% interest and other docs conflict on tier mappings — confirm the final loan terms before accepting loans or integrating. 7) Safer workflow: clone the repo, perform a code review (search for any network endpoints, logging of env vars, or hardcoded keys), run npm install in an isolated container, run tests in mock mode, and only then consider giving real keys. If you find any keys in the repo, assume they are compromised and rotate them. If you want, I can: (a) point to exact files/lines where keys are printed or embedded, (b) list all places the code reads environment variables, or (c) extract the specific discrepancies between docs (interest rate and tier mappings).

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