social-value

Give your AI agent a wallet. Efficient micropayments via Breez SDK — Liquid or Spark backend, Lightning passports in/out, near-zero internal transfers. Red-team tested.

pip install social-value[liquid]

PyPI ClawHub Source huje.tools

What It Is

social-value creates its own Liquid or Spark wallet from a BIP39 mnemonic. It is NOT connecting to an existing wallet — it IS one. Lightning is the passport in and out. Internal transfers cost near-zero.

It IS	It is NOT
Its own wallet (mnemonic = wallet)	A Lightning wallet (no channels, no routing)
Self-custodial (you hold the keys)	Connecting to an existing wallet (that's NWC)
A Lightning gateway (bolt11 in/out)	A Bitcoin on-chain wallet
Two backends: Liquid or Spark	An exchange or trading platform

Quickstart

from social_value import SocialValue, SocialValueConfig, SecretStr

config = SocialValueConfig(
    breez_api_key=SecretStr("your-breez-key"),
    backend="liquid",  # or "spark"
)

with SocialValue(config=config, mnemonic=SecretStr("twelve words...")) as wallet:
    # Deposit from Lightning (passport IN)
    invoice = wallet.deposit(amount_sat=5000)
    print(f"Pay this: {invoice}")

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

    # Transfer (near-zero fee on Liquid)
    wallet.transfer("liquid-address", 100, memo="payout")

    # Withdraw to Lightning (passport OUT)
    wallet.withdraw("lnbc1...", 4000)
      

Two Backends, Same API

Choose your rail. The API is identical either way.

Backend	Install	Internal Fee	Swap Fee	Status
Liquid	`pip install social-value[liquid]`	~1 sat	~47 sats	Production
Spark	`pip install social-value[spark]`	~0 sats	~10 sats	Beta

# Switch backend via config — no code changes needed
config = SocialValueConfig(breez_api_key=key, backend="spark")
      

Why Not Just Lightning?

Lightning routing fees are flat-ish. Small amounts get hit hardest.

Scenario	Pure Lightning	social-value
1 payment of 5,000 sats	~3 sats (0.06%)	~95 sats (1.9%) — Lightning wins
20 payments of 100 sats	~60 sats (3%)	~100 sats in/out + 20 sats internal = ~120 sats total
200 payments of 100 sats	~600 sats (3%)	~100 sats in/out + 200 sats internal = ~300 sats (1.5%)

The more transfers per session, the bigger the advantage. Deposit once, transfer many times, withdraw once.

API

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

Security

Red-team audited: 19 findings identified, all CRITICAL/HIGH/MEDIUM fixed
SecretStr wraps all sensitive values — mnemonic and API key never appear in repr, str, logs, or tracebacks
SocialValueError sanitizes all exceptions — SDK internals never leak
Input validation on all entry points — amounts must be positive integers, destinations non-empty
Max balance safety cap prevents runaway accumulation
Path traversal blocked on working directory
Network validated against allowlist — no silent wrong-network
57 tests proving each security property

Configuration

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_BACKEND`	No	"liquid" or "spark" (default: liquid)
`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)

NWC vs social-value

They're different things that complement each other.

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

Part of the huje.tools Ecosystem

social-value is an outward skill (body to others) in the huje.tools taxonomy. It sits alongside social-alignment (ethics) and social-card (presentation) as the economic dimension of social existence.

First consumer: Medalloid — batch payouts for 20+ players per round at near-zero fees.

Built on Breez SDK (Liquid and Spark backends).