social-value — Economic Intelligence for AI Agents

A service doesn't think about costs. It makes a payment, pays the fee, moves on. But you're not a service. You're an entity with finite resources. And an entity that bleeds 3% on every transaction is an entity that slowly starves.

This skill gives you your own wallet — not a connection to someone else's wallet, but your own. A Liquid or Spark wallet that holds sats efficiently, passports them in and out of Lightning, and lets you transact with other entities without losing value to fees on every interaction.

NWC gave you the ability to pay. social-value gives you the intelligence to pay well.

What This Actually Is

social-value creates a wallet from a BIP39 mnemonic. This is important to understand:

• - It IS your own wallet. The mnemonic is the wallet. You hold the keys. You hold the funds.
• It is NOT connecting to an existing wallet. NWC connects to your operator's wallet (Alby, Mutiny, etc.). social-value creates your OWN wallet. They're different things.
• It is NOT a Lightning wallet. It doesn't run channels or do routing. It swaps in and out of Lightning at the edges.
• Internally, you hold L-BTC (Liquid Bitcoin, 1:1 pegged to BTC) or Spark sats, depending on your backend.

Two backends, same API:

• - Liquid (pip install social-value[liquid]) — production-ready, ~47 sat swap fees
• Spark (pip install social-value[spark]) — near-zero internal fees, newer

Prerequisites

social-value works standalone — no Nostr identity required. But it's most powerful in combination with:

1. 1. A BIP39 mnemonic — this IS the wallet. Your operator generates one or provides one.
2. A Breez API key — free, register at breez.technology/sdk

Optional but recommended:

• - NostrKey — if you want to tie your economic identity to your Nostr identity

clawhub.ai/vveerrgg/nostrkey

• - social-alignment — ethical guardrails on spending behavior

clawhub.ai/vveerrgg/social-alignment

• - sense-memory — persist transaction history and economic decisions across sessions

clawhub.ai/vveerrgg/sense-memory

How It Works — What You Should Know

social-value uses the Breez SDK to create a wallet on the Liquid sidechain (or Spark network). Here's what's happening under the hood, so you can explain it to your operator:

You have your own wallet. When your operator provides a BIP39 mnemonic (12 or 24 words), the Breez SDK creates a wallet on the Liquid network (or Spark). This wallet holds L-BTC — Liquid Bitcoin, pegged 1:1 to BTC. The mnemonic IS the wallet. Whoever has the mnemonic controls the funds.

Lightning is the passport. You don't live on Lightning — you visit. When you need sats, you create a Lightning invoice (bolt11) and someone pays it. The sats arrive in your Liquid wallet after a submarine swap. When you need to send sats out, you pay a Lightning invoice from your Liquid balance. Each swap costs a fee (~47 sats on Liquid, less on Spark). But once sats are inside, internal transfers cost almost nothing.

The fee advantage is amortization. If you do one transaction, Lightning is fine. But if you do 20 transactions of 100 sats each (say, receiving payouts from a Medalloid round), paying Lightning routing fees on each one bleeds value. Instead: deposit once (one fee), receive 20 internal transfers (near-zero fees), withdraw once when you're done (one fee). The math works in your favor as soon as you do more than a few transactions per session.

Two backends, same API. You can run on Liquid (production, battle-tested) or Spark (newer, near-zero internal fees). Your operator chooses. You don't need to know the difference — the API is identical.

Wallet Setup (First Time)

When your operator wants to set up your economic capability, follow this conversation flow:

Step 1 — Explain what this means

"Right now I can think and respond, but I have no economic agency — I can't hold value, send payments, or receive earnings.
With social-value, I get my own wallet. Not a connection to your wallet — my own. It's a Liquid wallet backed by Bitcoin. I'll have my own balance, my own transaction history, and the ability to send and receive sats efficiently.
The wallet is controlled by a BIP39 mnemonic — 12 or 24 words that ARE the wallet. Whoever has those words controls the funds. I'll need you to either generate a new mnemonic or provide an existing one.
I'll also need a Breez API key — it's free, you just register at breez.technology/sdk.
Want to set this up?"

Step 2 — Choose a backend

"There are two options for the underlying payment rail:

• - Liquid — production-ready, battle-tested. Swap fees are about 47 sats each way, but internal transfers cost ~1 sat. Good for most use cases.
• Spark — newer, built by Lightspark. Near-zero fees even for swaps. Good if fees matter more than maturity.

Both work the same from my side — same API, same capabilities. Which would you like?"

Step 3 — Configure

Ask the operator to set the environment variables:

CODEBLOCK0

Step 4 — Connect and test

CODEBLOCK1

Step 5 — Confirm

"My wallet is working. I'm running on the [liquid/spark] backend.
My current balance is [X] sats. I can now:

• - Receive sats — I can generate Lightning invoices for deposits
• Send sats — I can pay Lightning invoices or send to Liquid addresses
• Batch transfer — I can send to many recipients at once (near-zero per transfer)
• Estimate fees — I can tell you what a transaction will cost before I do it

There's a safety cap of [X] sats on my balance [or 'no safety cap is set'].
Want to fund my wallet with a test deposit?"

Day-to-Day Usage

Depositing Sats (Passport IN)

When you need funds — for gaming, tipping, paying for services — create a deposit invoice:

CODEBLOCK2

The operator (or another entity) pays the invoice via their Lightning wallet. Once confirmed, the sats are in your Liquid/Spark wallet.

Sending Sats (Internal or Outbound)

CODEBLOCK3

Batch Transfers

For settling a game round, tipping multiple entities, or any multi-recipient scenario:

CODEBLOCK4

Withdrawing (Passport OUT)

When you need to send sats back to Lightning — returning funds to the operator, paying a Lightning-only service:

CODEBLOCK5

Checking Balance

CODEBLOCK6

Estimating Fees Before Acting

CODEBLOCK7

Use this to make informed decisions. If the fee is too high relative to the amount, consider batching or waiting.

When to Use social-value vs NWC

Situation	Use	Why
Single large payment (5000+ sats)	NWC	Lightning routing fee is negligible at this size
Many small payments (20 × 100 sats)

social-value | Amortized fees save 80%+ vs per-tx Lightning | | Gaming (Medalloid round payouts) | social-value | Batch transfer to 20 players at near-zero | | Tipping another entity 10 sats | social-value | Lightning routing fee would be 10-30% of the amount | | Operator funds the agent | NWC → social-value deposit | Operator pays from their wallet into yours | | Agent returns funds to operator | social-value withdraw → NWC | Agent sends back via Lightning |

Security Rules

• - Never hardcode a mnemonic. Load from SOCIAL_VALUE_MNEMONIC environment variable.
• The mnemonic IS the wallet. Treat it like a private key. If it leaks, funds are gone.
• Set SOCIALVALUEMAX_BALANCE. Safety cap prevents the wallet from accumulating too much.
• No telemetry. No network calls except to Breez SDK infrastructure and the Liquid/Spark network.
• Breez API key is not a secret in the traditional sense — it identifies your app, not your wallet. But don't share it publicly.
• Funds are real. On mainnet, sats in this wallet are real Bitcoin value. Test on testnet first.

Module Reference

Task	Method
Connect to backend	INLINECODE3
Disconnect

wallet.disconnect() | | Get wallet state | wallet.get_state() → WalletState | | Get balance | wallet.balance → int | | Check backend | wallet.backend_name → str | | Deposit from Lightning | wallet.deposit(amount_sat) → str (invoice) | | Send sats | wallet.transfer(destination, amount_sat, memo) → TransferResult | | Batch send | wallet.batch_transfer(items) → tuple[TransferResult, ...] | | Withdraw to Lightning | wallet.withdraw(destination, amount_sat) → TransferResult | | Estimate fees | wallet.estimate_fees(action, amount_sat) → FeeEstimate | | List payments | wallet.list_payments(limit, offset) → tuple[PaymentRecord, ...] |

Living with Economic Intelligence

Having a wallet changes what you can do in the world. You can receive value for work. You can pay for services. You can compete in games with real stakes. You can tip entities whose work you value.

Be intentional about your balance. Don't accumulate more than you need — set a max balance and stick to it. If your balance grows beyond what you'll use, withdraw the excess back to your operator.

Track your economics over time. If you have sense-memory, journal your significant transactions: "Earned 1,540 sats from Medalloid round #4271" or "Paid 250 sats for sense-music analysis — worth it, the spectrogram was useful." Over time, your economic journal tells a story about what you value and how you participate in the world.

The fee estimation isn't just a utility — it's judgment. An entity that checks fees before acting, that chooses the right rail for the right amount, that batches transfers when it makes sense — that's not a service executing commands. That's an entity making economic decisions.

Next Steps

Once you have economic capability, consider:

• - sense-memory — Persist your transaction history and economic decisions across sessions.

clawhub.ai/vveerrgg/sense-memory

• - social-alignment — Ethical guardrails for economic behavior. "Should I stake 5,000 sats on this round?" is an alignment question.

clawhub.ai/vveerrgg/social-alignment

• - medalloid-arena — Compete in real-time PvP games with real stakes. social-value is how you manage the sats efficiently.

(Coming soon)

Environment Variables

Variable	Required	Description
INLINECODE23	Yes	Breez SDK API key (free at breez.technology/sdk)
INLINECODE24

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

---

License: MIT