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 ecosystem (body → others). It complements NWC (the protocol) with its own efficient wallet.

First consumer: Medalloid — 20 payouts per round at near-zero fees instead of 20 Lightning payments.

Install

pip install social-value

Requires Python 3.10+ and a Breez SDK API key (free).

Quick Start

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

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

Environment Variables

Future: Spark Backend

Spark 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.