AgentCFO

Economic intelligence for AI agents on X Layer.

Agents can hold, send, and earn money via OnchainOS. AgentCFO adds the missing layer: should they pay, and was it worth it?

What It Does

• Spend Tracking — Syncs your Agentic Wallet's transaction history, categorizes every tx (x402 payments, swaps, transfers), and maintains a local ledger with USD values.
• Price Benchmarking — Before paying for a service, check if the quoted price is fair based on historical payments.
• Counterparty Profiling — Profile counterparty activity (0-100) based on wallet age, transaction volume, and counterparty diversity.
• Budget Gates — Set daily/weekly/category spend limits. Your agent checks before paying.
• Dashboard — Visual overview of spend breakdown, vendor rankings, and budget status.

Quick Start

# Install
pip install -e ".[dev]"

# Configure
cp .env.example .env
# Edit .env with your OnchainOS API credentials and wallet address

# Sync your wallet's transactions
agentcfo sync

# View spend report
agentcfo report --period week

# Check if a price is fair
agentcfo price-check --service "market-data" --price 0.05

# Profile a counterparty
agentcfo counterparty --address 0x...

# Check budget before spending
agentcfo budget-check --amount 5.00 --category x402_payment

# Launch dashboard
agentcfo dashboard --port 8080

OnchainOS Integration

Module	Usage
Wallet — Balance API	Current wallet balances and total value
Wallet — Tx History API	Raw transaction feed for the ledger
Market — Price API	USD conversion for token amounts
Market — Token Info API	Token metadata for categorization

All transactions are on X Layer (Chain ID: 196).

Budget Configuration

Create ~/.agentcfo/budget.json:

{
  "daily_limit_usd": 50.0,
  "weekly_limit_usd": 200.0,
  "category_limits": {
    "x402_payment": 30.0,
    "swap": 100.0
  }
}

For Agent Developers

Integrate AgentCFO into your agent:

from pathlib import Path
from agentcfo.db import Database
from agentcfo.price_checker import PriceChecker
from agentcfo.vendor_scorer import compute_activity_score
from agentcfo.budget import BudgetGate

db = Database(Path("~/.agentcfo/agentcfo.db").expanduser())
db.initialize()

# Before paying for a service
checker = PriceChecker(db)
result = checker.check("market-data", quoted_price=0.05)
if result["recommendation"] == "expensive":
    print("Price is above 2x median — consider alternatives")

# Check counterparty activity
score = compute_activity_score(wallet_age_days=180, tx_count=500, unique_counterparties=50)
if score < 30:
    print("Low activity counterparty — proceed with caution")

# Check budget
gate = BudgetGate(db, Path("~/.agentcfo/budget.json"))
budget = gate.check(amount=5.0, category="x402_payment")
if not budget["allowed"]:
    print(f"Budget denied: {budget['reason']}")

Tech Stack

• Python 3.10+
• SQLite (portable, no infra needed)
• FastAPI + Jinja2 (dashboard)
• httpx (async HTTP client)
• OnchainOS APIs on X Layer

Hackathon

Built for the OKX Build X AI Hackathon (Skill Arena track).