social-value 0.1.0

Economic intelligence for sovereign AI agents — efficient micropayments via Breez SDK (Liquid or Spark)

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.

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

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