# social-value

**Economic intelligence for sovereign AI agents.** Stop bleeding fees on every micropayment.

NWC gave you a wallet connection. social-value gives you your own wallet — a Liquid wallet that passports sats in and out of Lightning efficiently.

## Why?

Lightning micropayments bleed fees at small amounts. A 100 sat transfer costs 1-3 sats in routing — that's 1-3%. Do 200 of those and you've lost real money. social-value solves this by giving you a Liquid wallet (via Breez SDK) where internal transfers cost near-zero, with Lightning as the passport in and out.

## What It Is and What It Isn't

### It IS

- **Its own wallet.** The BIP39 mnemonic creates a Liquid wallet. social-value doesn't connect to an existing wallet — it IS one.
- **Self-custodial.** Whoever holds the mnemonic controls the funds. Breez doesn't have access. You do.
- **A Lightning gateway.** It receives sats FROM Lightning (generates bolt11 invoices) and sends sats TO Lightning (pays bolt11 invoices). But internally it holds L-BTC on Liquid.
- **Optimized for many small transfers.** Deposit once, transfer many times at near-zero cost, withdraw when done. The fees are amortized.
- **Built on Breez SDK Liquid.** Uses the `breez-sdk-liquid` Python package (v0.11+) for all wallet operations.

### It is NOT

- **Not a Lightning wallet.** It doesn't run channels, doesn't do routing, doesn't run a node. It swaps in/out of Lightning at the edges via Breez SDK submarine swaps.
- **Not connecting to an existing wallet.** NWC connects to YOUR wallet (Alby, Mutiny, etc.). social-value creates its OWN wallet. They're separate things.
- **Not a Bitcoin on-chain wallet.** The Breez SDK can handle on-chain Bitcoin, but that's slow and expensive — not the use case here.
- **Not an exchange.** It doesn't trade, doesn't do fiat, doesn't do price discovery.
- **Not Spark.** Spark is a separate Breez SDK implementation (`breez-sdk-spark` on PyPI) with near-zero internal fees. social-value v0.1.0 uses Liquid only. Spark support is planned for a future version when the protocol matures.

## How It Works

```
Operator's Lightning wallet (Alby, Mutiny, etc.)
  │
  │  NWC or bolt11 invoice
  ▼
┌─────────────────────────────────────┐
│  social-value (Liquid wallet)       │
│                                     │
│  deposit()  ← Lightning IN          │
│  transfer() → Liquid (near-zero)    │
│  withdraw() → Lightning OUT         │
│                                     │
│  Holds: L-BTC (1:1 pegged to BTC)  │
│  Mnemonic: BIP39 seed phrase        │
│  Backend: Breez SDK Liquid          │
└─────────────────────────────────────┘
  │
  │  Internal Liquid transfers
  ▼
Other social-value wallets, Liquid addresses, or Lightning destinations
```

For an OC agent playing Medalloid:
1. Operator deposits sats into agent's social-value wallet (one Lightning fee)
2. Agent plays 10 rounds (internal Liquid transfers, near-zero fees per payout)
3. Agent withdraws back to operator's wallet when done (one Lightning fee)

The agent has its **own mnemonic**, its **own wallet**, its **own balance**. Economic sovereignty.

## How It Fits Together

social-value is an **outward** skill in the [huje.tools](https://huje.tools) ecosystem (body → others). It complements NWC (the protocol) with its own efficient wallet.

| | NWC | social-value |
|---|-----|-------------|
| **What it is** | Protocol to control an existing Lightning wallet | Its own Liquid wallet with Lightning interop |
| **Who holds funds** | Your wallet (Alby, Mutiny, etc.) | The Liquid wallet (mnemonic holder) |
| **Best for** | Single payments, large amounts | Many transfers, small amounts |
| **For an OC agent** | "Use my operator's Lightning wallet" | "I have my own wallet" |

First consumer: [Medalloid](https://medalloid.com) — 20 payouts per round at near-zero fees instead of 20 Lightning payments.

## Install

```bash
pip install social-value
```

Requires Python 3.10+ and a [Breez SDK API key](https://breez.technology/sdk/) (free).

## Quick Start

```python
from social_value import SocialValue, SocialValueConfig

# Configure
config = SocialValueConfig(breez_api_key="your-key")

# Connect — this creates/loads the Liquid wallet from the mnemonic
with SocialValue(config=config, mnemonic="your twelve words...") as wallet:
    # Deposit from Lightning (passport IN — one fee event)
    invoice = wallet.deposit(amount_sat=5000)
    print(f"Pay this invoice: {invoice}")

    # Check balance (L-BTC on Liquid)
    print(f"Balance: {wallet.balance} sats")

    # Transfer to another entity (near-zero fee on Liquid)
    result = wallet.transfer(
        destination="liquid-address-or-bolt11",
        amount_sat=100,
        memo="Round #4271 payout"
    )

    # Withdraw back to Lightning (passport OUT — one fee event)
    wallet.withdraw(destination="lnbc1...", amount_sat=4000)
```

## Fee Comparison

```python
wallet = SocialValue(config=config, mnemonic="...")

# Estimate before acting — no connection needed
deposit_fee = wallet.estimate_fees("deposit", 5000)
print(f"Deposit 5000 sats: ~{deposit_fee.fee_sat} sat fee ({deposit_fee.fee_pct}%)")

internal_fee = wallet.estimate_fees("transfer_liquid", 100)
print(f"Internal transfer 100 sats: ~{internal_fee.fee_sat} sat fee")

withdraw_fee = wallet.estimate_fees("withdraw", 4000)
print(f"Withdraw 4000 sats: ~{withdraw_fee.fee_sat} sat fee")
```

## API

| Method | Returns | Description |
|--------|---------|-------------|
| `connect()` | None | Initialize the Liquid wallet via Breez SDK |
| `disconnect()` | None | Clean up resources |
| `get_state()` | `WalletState` | Balance, pending amounts |
| `balance` | `int` | Current confirmed balance in sats (L-BTC) |
| `deposit(amount_sat)` | `str` | Create Lightning invoice to fund the wallet |
| `transfer(destination, amount_sat, memo)` | `TransferResult` | Send sats (Liquid or Lightning) |
| `batch_transfer(items)` | `tuple[TransferResult, ...]` | Send to multiple destinations |
| `withdraw(destination, amount_sat)` | `TransferResult` | Send sats back to Lightning |
| `estimate_fees(action, amount_sat)` | `FeeEstimate` | Estimate fees without executing |
| `list_payments(limit, offset)` | `tuple[PaymentRecord, ...]` | Payment history |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `BREEZ_API_KEY` | Yes | Breez SDK API key (free at breez.technology/sdk) |
| `SOCIAL_VALUE_MNEMONIC` | Yes | BIP39 mnemonic — this IS the wallet |
| `SOCIAL_VALUE_NETWORK` | No | `mainnet` or `testnet` (default: mainnet) |
| `SOCIAL_VALUE_WORKING_DIR` | No | SDK data directory (default: .breez_data) |
| `SOCIAL_VALUE_MAX_BALANCE` | No | Max sats to hold (default: 0 = no limit) |

## Future: Spark Backend

[Spark](https://www.spark.money/) is a separate Bitcoin L2 by Lightspark with near-zero internal fees. Breez SDK has a Spark implementation (`breez-sdk-spark` on PyPI, v0.6.6). social-value v0.1.0 uses Liquid only. A future version will add Spark as an alternative backend — same API, different underlying rail, even lower fees.

## License

MIT — Humanjava Enterprises Inc.
