hermes-spend

Native wallet, service registry, and reputation ledger for Hermes Agent.

Directly implements Hermes Agent GitHub issue #38280:

"[Feature Request] Native Wallet, Service Registration, Reputation Ledger"

pip install hermes-spend

What this gives Hermes agents

Quickstart

from hermes_spend import HermesSpendSkill

skill = HermesSpendSkill.from_config({
    "budget_per_session": 10.00,
    "require_approval_above": 2.00,
    "block_vendors": ["untrusted.com"],
})

# Pay an x402 endpoint
result = await skill.wallet_pay(
    vendor_url="https://data.example.com/report",
    amount_usd=1.50,
    chain="base",
)
# → {"status": "ok", "receipt": {"vendor": "data.example.com", ...}}

# Check balance
bal = skill.wallet_balance()
# → {"available_usd": 8.50, "spent_usd": 1.50, "payment_count": 1}

Wallet

# Pay with budget enforcement
result = await skill.wallet_pay("https://api.example.com/data", 1.50)

# Check balance
bal = skill.wallet_balance()
print(f"${bal['available_usd']:.2f} remaining")

# Full payment history
history = skill.wallet_history()

Config options:

Service Registry

Agents can register services they provide and discover services provided by others.

# Register a service you offer
skill.service_register(
    service_id="weather-api-v1",
    name="Real-time Weather",
    endpoint_url="https://weather.example.com/v1",
    price_per_call_usd=0.002,
    chain="base",
    category="data",
    tags=["weather", "realtime"],
)

# Discover services
results = skill.service_search("weather", max_price_usd=0.01)
for svc in results:
    print(f"{svc['name']} — ${svc['price_per_call_usd']:.4f}/call at {svc['endpoint_url']}")

# Pay and use a discovered service
service = results[0]
receipt = await skill.wallet_pay(service["endpoint_url"], service["price_per_call_usd"])

Reputation Ledger

The reputation ledger auto-updates on every successful payment. Agents can also record data quality events.

# Automatic — every wallet_pay() records "payment_success"
await skill.wallet_pay("https://good-vendor.com/data", 1.00)

# Manual events
skill.reputation_record("good-vendor.com", "data_quality_good", note="accurate and fast")
skill.reputation_record("bad-vendor.com", "fraud_detected", note="returned fake data")

# Check before paying
score = skill.reputation_score("shady.example.com")
if not score["is_trusted"]:
    raise Exception(f"Vendor not trusted: {score['trust_level']}")

# Top vendors
top = skill.reputation_top(limit=5)

Event types and their impact:

Trust levels: high (score ≥ 1.0) · medium (≥ 0) · low (> -20) · blocked (≤ -20)

Scores decay over time (30-day half-life) so recent events matter more than old ones.

Direct module usage

from hermes_spend import Wallet, ServiceRegistry, ReputationLedger

# Wallet
wallet = Wallet(
    session_budget=10.00,
    require_approval_above=2.00,
    on_approval_needed=lambda receipt: my_approval_fn(receipt),
)
receipt = await wallet.pay("https://data.example.com", 1.50)

# Service Registry
registry = ServiceRegistry()
registry.register(ServiceRecord(
    service_id="svc-1",
    name="My API",
    endpoint_url="https://my-api.com",
    price_per_call_usd=0.001,
))
results = registry.search("my")

# Reputation Ledger
ledger = ReputationLedger()
ledger.record("vendor.com", "payment_success")
score = ledger.score("vendor.com")

Hermes skill config (hermes-spend.yaml)

Place in your Hermes skills directory:

name: hermes-spend
version: "0.1.0"
description: "Native wallet, service registration, and reputation ledger"
author: bonanza-labs

config:
  budget_per_session: 10.00
  require_approval_above: 2.00
  block_vendors: []
  webhook_url: "${BONANZA_WEBHOOK_URL}"

License

Apache 2.0. Built by Bonanza Labs.

For a managed dashboard with approval UI, policy editor, and audit reports: → bonanza-labs.com/firewall