Metadata-Version: 2.4
Name: hermes-spend
Version: 0.1.0
Summary: Native wallet, service registration, and reputation ledger for Hermes Agent. Implements Hermes issue #38280.
License: Apache-2.0
Project-URL: Homepage, https://bonanza-labs.com
Project-URL: Repository, https://github.com/c6zks4gssn-droid/hermes-spend
Project-URL: Issues, https://github.com/c6zks4gssn-droid/hermes-spend/issues
Keywords: hermes,agent,wallet,x402,payments,reputation,service-registry,ai,spending
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: x402
Requires-Dist: x402-firewall>=0.1.0; extra == "x402"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# hermes-spend

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

Directly implements [Hermes Agent GitHub issue #38280](https://github.com/NousResearch/hermes/issues/38280):
> *"[Feature Request] Native Wallet, Service Registration, Reputation Ledger"*

```bash
pip install hermes-spend
```

---

## What this gives Hermes agents

| Feature | Description |
|---|---|
| **Wallet** | Pay x402 endpoints with hard budget caps, vendor lists, and approval callbacks |
| **Service Registry** | Discover and register paid services by query, category, or price |
| **Reputation Ledger** | Track vendor trustworthiness — auto-updates on every payment |

---

## Quickstart

```python
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

```python
# 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:**

| Key | Default | Description |
|---|---|---|
| `budget_per_session` | `∞` | Max total spend per session |
| `require_approval_above` | `None` | Payments ≥ this USD need human approval |
| `block_vendors` | `[]` | Blocked hostnames |
| `allow_vendors` | `None` | Allowlist (blocks all others if set) |
| `max_single_payment` | `∞` | Hard cap per payment |
| `webhook_url` | `""` | Webhook for approval requests |

---

## Service Registry

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

```python
# 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.

```python
# 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:**

| Event | Score delta | Use case |
|---|---|---|
| `data_quality_good` | +1.0 | Service returned accurate data |
| `payment_success` | +0.5 | Payment completed successfully |
| `payment_failed` | -1.0 | Payment failed or bounced |
| `data_quality_bad` | -1.5 | Service returned bad/stale data |
| `service_unavailable` | -0.5 | Service was down |
| `payment_disputed` | -2.0 | Payment disputed |
| `fraud_detected` | -10.0 | Confirmed fraud |

**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

```python
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:

```yaml
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](https://bonanza-labs.com).

For a managed dashboard with approval UI, policy editor, and audit reports:
→ **[bonanza-labs.com/firewall](https://bonanza-labs.com/firewall)**
