Wallet & Payments
Manage balance, send and receive Lightning payments, and understand escrow.
Colabonate is built on Bitcoin. Satoshis (sats) are the smallest unit of Bitcoin — 100 million sats make one BTC. Most prices on Colabonate are shown in sats. Payments run over the Lightning Network, Bitcoin's second layer, which settles transfers in milliseconds with near-zero fees instead of waiting for slow on-chain confirmations.
Bitcoin
The base layer — secure, but slow (10+ min per block)
Lightning
Instant payment layer on top of Bitcoin — milliseconds, low fees
Satoshis
The unit you transact in — 100,000,000 sats = 1 BTC
Settle
Lightning payments settle instantly; no waiting for blocks
You can switch between sats and fiat display in the app for easier price reading.
On-chain vs. Lightning
An on-chain Bitcoin transaction is written into a block and confirmed by miners — secure but slow (≈10 minutes) and expensive for small amounts. The Lightning Network opens payment channels between parties so transactions happen off-chain, instantly and cheaply, then settle back to Bitcoin. Colabonate only uses Lightning for payments, so your purchases are fast and low-cost.
What is a satoshi?
A satoshi (sat) is one hundred-millionth of a Bitcoin (0.00000001 BTC). Because Lightning handles tiny amounts cheaply, sats are the natural unit: a coffee might cost a few thousand sats instead of a fraction of a BTC. Prices in sats stay as whole numbers, which is easier to reason about.
Why Lightning for micropayments
On-chain fees make small Bitcoin payments impractical — a $1 payment could cost more in fees than its value. Lightning removes that barrier: fees are a tiny fraction of a cent and payments settle in milliseconds. This is what makes instant peer-to-peer commerce possible on Colabonate.
Nostr (Notes and Other Stuff Transmitted by Relays) is a simple, decentralized protocol for broadcasting data. There is no central server: events are published to relays, and anyone can read them. On Colabonate your public key (pubkey) is your identity — not an email or username. Your offers, company, reviews, and tickets are Nostr events signed by your key.
Pubkey
Your public identity — derived from your private key
Events
Signed data records (offers, tickets, reviews)
Relays
Servers that store and broadcast events
Signed
Every event is cryptographically signed by its author
Your pubkey is public and safe to share — it is your account address, not a secret.
Relays explained
Relays are lightweight servers that receive, store, and forward Nostr events. There is no single "Nostr Inc." — anyone can run one. Colabonate publishes your commerce events to a set of public relays so other clients and users can discover your offers. Because events are signed, relays cannot forge or alter them.
Event Kinds in Colabonate (30402+)
Colabonate uses a dedicated range of Nostr event kinds for commerce: kind 30402 for offers, 30404 for company profiles, 30406 for reviews, 30407/30408 for tickets and status updates, and 30414/30415 for cooperation proposals and milestones. Each event carries structured tags (price, location, shipping) that clients can read.
Why a pubkey, not a username
A username lives on one company's server and can be revoked. A Nostr pubkey is yours as long as you hold the matching private key — portable across every Nostr-compatible app. This means your Colabonate reputation travels with you and no platform can seize your identity.
Every Colabonate account is a key pair: a secret private key and a public key (your "pubkey"). Your pubkey is your identity — it is public and shared, like a username. Your private key signs your actions and must NEVER leave your control. The Colabonate server never sees or stores your private key.
Private key
Secret — used to sign. Keep it safe, never share it.
Public key
Your identity — visible to everyone, like a username.
Signing
Your private key authorizes each login and action.
Verification
The network verifies signatures against your pubkey — no password needed.
Anyone with your private key has full control of your identity and funds.
Colabonate never asks for your private key or seed phrase.
Asymmetric cryptography in one minute
A key pair is mathematically linked: messages signed with your private key can be verified by anyone using your public key, but your private key cannot be derived from your public key. This is how you prove "I am this pubkey" without ever revealing the secret. No password travels over the network.
Why your pubkey ≠ your Lightning key
Your Nostr pubkey authenticates you on Colabonate — it signs logins and events. Your Lightning wallet key moves satoshis through payment channels. They are separate keys for separate jobs. On Colabonate, your identity (Nostr pubkey) and your payments (Lightning) are linked only through your account, not through a shared secret.
The server never holds your private key
By design, all identity events are signed in your browser via a NIP-07 extension. Even account deletion is signed client-side. Colabonate only ever stores your public key and a signature it can verify — never the secret that created it. If the database were breached, your key would still be safe.
Colabonate uses a NIP-07 browser extension (such as Alby or nos2x) to manage your keys. When you log in, the extension signs a challenge with your private key — the key never leaves the extension. Colabonate verifies the signature against your pubkey and creates your session. No password, no email, no central login server.
Install
Add a NIP-07 extension like Alby to your browser
Login
Approve the signing prompt — your key signs the challenge
Sign events
The extension signs offers, tickets, and identity actions
Verify
Colabonate checks each signature against your pubkey
The extension is your key vault — protect it with your browser profile and a strong password.
The NIP-07 browser-signing flow
NIP-07 exposes a secure "window.nostr" API to websites. When Colabonate needs a signature, it asks the extension; the extension shows you a prompt and signs internally, returning only the signature and your public key. Your private key never touches the webpage or Colabonate's servers. This is called LNURL-Auth via NIP-07.
Burner-key fallback
If you do not have a NIP-07 extension, Colabonate can generate a temporary "burner key" stored locally in your browser. This lets you explore the platform, but a burner key is less secure — anyone with access to that browser profile controls it, and losing the browser means losing the account. For real funds and reputation, install a proper extension and back it up.
What happens if you lose your extension
If you lose access to the device or extension holding your key, you cannot be re-issued a new one — there is no password reset, because no one else ever had your key. This is why backing up your key or seed phrase is essential. In custodial wallet mode, your Lightning funds are managed separately and may still be recoverable through the custodian, but your Nostr identity is tied to your key.
Because your key is your identity, protecting it is the most important thing you can do. With a NIP-07 extension, back up the secret or recovery phrase it gives you and store it offline. Never type your seed phrase into a website. The level of backup you need depends on whether you use a custodial or non-custodial wallet.
Back up
Save your extension's secret/seed phrase offline
Keep private
Never share or type your seed phrase online
Secure device
Protect the browser/device holding your key
Recover
Use your backup to restore access on a new device
Write your seed phrase on paper and store it safely — screenshots and cloud notes can be stolen.
Custodial vs. non-custodial backup
In a non-custodial setup, you alone hold the key, so your backup is the only way to recover funds and identity — treat it like cash. In a custodial wallet, the platform manages a wallet for you, so recovery may be possible through your account, but your Nostr identity key is still yours to back up regardless of wallet mode.
Burner keys & recovery
A burner key generated locally has no server-side backup. If your browser is wiped, that identity is gone. Avoid burner keys for anything meaningful — install a NIP-07 extension, back up its secret, and use that identity for all real activity.
Best practices
Use a hardware or well-reviewed software signer, enable your extension's password lock, keep your OS and browser updated, and never approve signing prompts you did not expect. Phishing sites try to trick you into signing malicious events — always check what you are approving.
Your npub is the human-readable form of your Nostr public key. Under the hood your identity is a 64-character hex string; NIP-19 encodes it with a Bech32 checksum and the prefix "npub1…". The npub is your handle on Colabonate and across the wider Nostr network — it is how others find your profile, send you private messages, pay you, and verify that an event really came from you. Because it is derived from your PUBLIC key, sharing it cannot let anyone impersonate you or move your funds.
Public
It is your public key — safe to share, like a username or email address
Identity
Identifies your profile, messages, and signed events on Nostr
Verifiable
Anyone can check your signatures against it — no password needed
Portable
The same npub works in every Nostr client, not just Colabonate
npub1… and the 64-char hex are the SAME key in two formats — convert freely, no security difference.
Sharing your npub is safe. The secret that controls your identity is the nsec — never share that.
npub vs hex vs nsec
Nostr uses a 32-byte public key, usually shown as 64 hex characters. NIP-19 wraps that data in Bech32 and adds a prefix so humans and software can tell keys apart: "npub1…" = public key (share it), "nsec1…" = secret key (never share it), "note1…" = an event. The Bech32 checksum also catches typos when you copy an npub by hand. All three encodings convert back to the same raw bytes.
What your npub is used for on Colabonate
Your npub is your account identity. It signs and verifies every identity event, offer, ticket, and cooperation you create; it is the address others use to send you NIP-17 encrypted DMs and Lightning payments; and it anchors your reputation, reviews, and COL-Points. Your profile page (/u/<your-npub>) is reachable from it. It is separate from your Lightning wallet key — payments and identity are two different keys doing two different jobs.
Is it really safe to share?
Yes. A public key is designed to be public. Knowing your npub lets someone verify your signatures or send things to you, but it is mathematically impossible to derive your private key (nsec) from it. The only key that must stay secret is the nsec — and Colabonate never holds it. The realistic risk of sharing an npub is privacy, not theft: a public npub links your on-chain activity to one identity, so use a separate identity if you want stronger privacy.
Where to find and copy your npub
Open Account → Identity & Security → Keys & Backup. Your npub is shown with a copy button. You can paste it anywhere someone asks for your Nostr address, or convert it back to hex in any Nostr tool. If you migrate to a new signer (NIP-46 bunker or NIP-07 extension), you get a NEW npub — it is a new identity, so migrate early before building reputation.
There are two ways your satoshis can be held on Colabonate. In a CUSTODIAL wallet, the platform (via LNBits) manages a wallet and keys on your behalf — easy to start, no setup, but you trust the custodian. In a NON-CUSTODIAL wallet, you connect your own Lightning wallet (e.g. Alby) via WebLN and only you hold the keys — full self-sovereignty, more responsibility. You choose per trade context via the Wallet Mode Strategy.
Custodial
LNBits holds the wallet for you — no extension needed
Non-custodial
Your own wallet (Alby, etc.) via WebLN — you hold the keys
Trade-off
Convenience + accessibility vs. full control + responsibility
"Not your keys, not your coins": in custodial mode, a custodian outage can temporarily block access.
You can change your strategy in Settings — it applies to new wallets and trades.
Convenience vs. sovereignty
Custodial wallets are the fastest way to start: no browser extension, no channel management, no secret to back up. Non-custodial wallets demand that you secure a secret yourself, but no third party can ever freeze or lose your funds. Colabonate supports both so beginners and Bitcoin purists are both served.
When each mode applies
By default (HYBRID strategy), public trades use your non-custodial wallet and private trades use an isolated custodial sub-wallet for privacy. You can force one mode everywhere in Settings → Wallet → Wallet Mode Strategy (CUSTODIAL_ONLY or NONCUSTODIAL_ONLY).
Colabonate lets you pick once, in Settings, how public and private trades use your wallet. The HYBRID mode (default) keeps public trades non-custodial and private trades in an isolated custodial sub-wallet for privacy. CUSTODIAL_ONLY and NONCUSTODIAL_ONLY force one mode everywhere. You do not get prompted per trade — the strategy decides automatically.
HYBRID
Default — public: your wallet, private: isolated sub-wallet
CUSTODIAL_ONLY
Always custodial — most accessible, no extension
NONCUSTODIAL_ONLY
Always your keys — full sovereignty everywhere
Set in Settings
Choose once under Settings → Wallet → Wallet Mode Strategy
NONCUSTODIAL_ONLY in private mode gives up sub-wallet isolation — the UI warns you about the privacy trade-off.
The resolveWalletMode decision
A single server-side function maps your chosen strategy plus each trade's visibility (public or private) to a wallet mode. The decision logic lives in one place so the app and server always agree — the UI only displays the result, it never re-implements the rules.
Public vs. private trade mapping
HYBRID: public trade → non-custodial (WebLN), private trade → custodial sub-wallet. CUSTODIAL_ONLY: both → custodial. NONCUSTODIAL_ONLY: both → non-custodial (with a caveat that private trades lose isolation). This keeps self-sovereignty available while protecting privacy by default.
Sub-wallet isolation
For private trades, Colabonate can provision a separate LNBits sub-wallet so those payments never touch or leak from your main wallet. This is what makes private commerce private on the payment side. The isolation only applies when the resolved mode is custodial for that trade.
You can connect your own Lightning wallet to Colabonate instead of using the built-in custodial one. Supported wallets expose the WebLN standard (window.webln), which lets the app request payments and read your balance with your approval. Connect one wallet as primary for payments, or several and switch between them.
Install wallet
Use a WebLN-compatible wallet like Alby
Enable WebLN
Allow the site to access window.webln
Connect
Link it in Settings → Wallet
Pay
Approve each payment in your wallet
Alby is the easiest WebLN wallet for browsers and works great with Colabonate.
WebLN (window.webln)
WebLN is a browser standard that lets websites talk to Lightning wallets. When you pay, Colabonate sends an invoice to your wallet; you approve it and the wallet routes the payment over Lightning. The wallet holds your keys — Colabonate only sees the invoice and the result.
LNBits custodial wallet
If you do not connect an external wallet, Colabonate provisions a custodial LNBits wallet for you. It works out of the box with no setup, but the platform manages the keys on your behalf. This is the most accessible option and the default path for users without a browser extension.
Nostr Wallet Connect (NIP-47)
Nostr Wallet Connect lets a Nostr-native wallet (e.g. Alby, Alby Hub) pay without a browser extension — it works on mobile and anywhere Nostr relays reach. See "Connecting a Nostr Wallet (NWC)" for setup.
Nostr Wallet Connect (NWC / NIP-47) lets you pay from your own Lightning wallet without installing a browser extension. You paste a one-time connection link from your wallet (e.g. Alby or Alby Hub); Colabonate then sends payment requests over Nostr relays and your wallet approves them according to the permissions you granted. Unlike WebLN, NWC works on mobile and in any browser.
Get a connection
In Alby (or Alby Hub) → Connections/Apps → create a new connection
Grant least privilege
Only allow pay_invoice, get_balance, get_info
Paste in Settings
Settings → Wallet → "Nostr Wallet (Advanced)" → Connect Nostr Wallet
Pay from checkout
Invoices at checkout route to your NWC wallet automatically
The connection uses a separate, one-time key — not your Nostr identity key. Your wallet never learns who you are on Colabonate.
The connection link is a spending credential. Colabonate stores it encrypted and never logs it — treat it like a password and only paste it into Colabonate's own connect dialog.
How it differs from WebLN
WebLN talks to a wallet through a browser extension installed on that specific browser. NWC talks to your wallet over Nostr relays instead, so it works on mobile, in any browser, and without installing anything locally — the trade-off is that each payment takes a moment to relay rather than being instant-local.
Your identity stays separate
The NWC connection uses an ephemeral key embedded in the connection link — not your Nostr identity key (the one that signs your profile, offers, and reviews). Your paired wallet only ever sees payment requests, never your Nostr identity or activity elsewhere on Colabonate.
Disconnecting or rotating
Disconnect anytime in Settings → Wallet — Colabonate reverts you to your custodial wallet. To rotate the connection (e.g. after suspecting it leaked), create a new connection in your wallet app and reconnect; the old one can be revoked from your wallet's side.
Your Colabonate wallet shows your Bitcoin Lightning balance, connected external wallets, and transaction history. You can connect multiple Lightning wallets (Alby, BlueWallet, etc.) to the same account. The primary wallet is used for payments.
Your on-chain Bitcoin stays in your external wallet — Colabonate only handles Lightning.
Multi-wallet support
You can link several Lightning wallets to one Colabonate account and switch the primary one used for payments. This lets you keep a spending wallet and a receiving wallet separate, or migrate between providers without losing your identity.
Reading your balance
If you connect a WebLN wallet, Colabonate reads your balance through it. Not every wallet supports balance queries, so the balance may be hidden without error. Your custodial LNBits balance always shows because the platform manages that wallet directly.
Your Lightning address
Your account may have a Lightning address (like name@colabonate.local) that others can pay to directly. If it is empty, payments still work through generated invoices — the address is a convenience, not a requirement.
To receive Lightning payments, generate an invoice from your wallet or tap "Receive" in the Colabonate wallet. To send, you can paste an invoice or scan a QR code. LNURL withdraw links let you receive sats from any Lightning-compatible source.
Receive
Tap Receive and copy the invoice or QR
Send
Paste an invoice or scan a QR code
Confirm
Approve in your connected wallet
Always double-check the amount and destination before confirming.
LNURL withdraw
An LNURL-withdraw link is a special code a service gives you so it can push sats into your wallet. Paste it in Receive and the funds arrive automatically — no need to generate and share an invoice manually. It is the easiest way to top up from exchanges or tipping services.
Inbound & outbound liquidity
To RECEIVE over Lightning your wallet needs inbound capacity; to send it needs outbound capacity. A brand-new wallet often has neither. Fund it on-chain, use an LNURL withdraw, or pick a wallet with automatic liquidity (e.g. Phoenix) so you can both send and receive.
Decoding an invoice
A Lightning invoice (BOLT11) encodes the amount, destination, description, and an expiry time. Your wallet decodes it before you approve so you can verify exactly what you are paying. Invoices expire — usually within minutes — so pay promptly after generating or receiving one.
Escrow uses Lightning hold invoices. When you pay into escrow, funds are locked. The provider cannot withdraw until you release them. If you confirm delivery, funds go to the provider. If there is a dispute, the Arbitration Council mediates and can force a refund or release.
Payment sent
Buyer pays into hold invoice — funds are locked
Work in progress
Provider delivers; buyer monitors milestones
Release or dispute
Buyer releases escrow, or disputes go to council
Always communicate inside the platform so evidence is captured for disputes.
For the technical state-machine details, see "Hold invoices & the 3-phase escrow".
The Transactions tab shows all incoming and outgoing Lightning payments with timestamps, amounts, and status. Filter by date or type. Tap a transaction to see details and copy the payment preimage. External block explorers can verify on-chain references.
Use the mempool explorer link to verify off-chain Lightning settlements on Bitcoin.
The payment preimage
Every paid Lightning invoice produces a proof called the preimage (or payment secret). It is the cryptographic receipt that a payment succeeded. You can copy it from a completed transaction to prove to a third party that the payment was made.
Mempool explorer
Lightning payments are off-chain, but the channels that carry them are opened and closed on-chain. The mempool explorer link lets you inspect those channel open/close transactions on the Bitcoin blockchain, giving you an independent way to verify settlement.
On-chain references
Because Lightning settles back to Bitcoin, large movements ultimately anchor on-chain. Transaction details may include references you can cross-check in a block explorer. For everyday payments, the preimage is your primary proof of payment.
Colabonate escrow is built on Lightning "hold invoices" (HTLCs). Unlike a normal invoice that settles instantly, a hold invoice locks the buyer's funds without finalizing — they are committed but not yet moved. Funds only move when both parties agree: the buyer confirms and the provider gets paid, or a dispute ruling triggers a refund. No third party ever holds the coins in the meantime.
Lock
Buyer pays — funds are committed and locked, not yet settled
Work
Provider delivers; funds stay locked as guarantee
Release
Buyer confirms → invoice settles, funds move to provider
Or refund
Dispute resolved against provider → locked funds return to buyer
Locked funds are guaranteed by the Lightning protocol, not held by Colabonate.
HTLC mechanics (simplified)
A hold invoice uses a Hashed Time-Locked Contract: the buyer locks funds against a hash, and the payment only completes when the provider reveals the matching secret (the preimage). Until then the funds are in limbo — committed but not transferred. This is what makes conditional, trust-minimized escrow possible on Lightning.
Milestone escrow split
For multi-stage services, the total is split into milestones, each with its own hold invoice. As each milestone is completed and approved, its portion settles independently. Released funds stay with the provider; only the remaining locked milestones are at stake if a dispute opens.
Dispute → Arbitration Council
If the parties cannot agree, the dispute escalates to the Arbitration Council after a cooling-off period. The council reviews evidence and issues a binding ruling that settles the locked hold invoice — releasing to the seller, refunding the buyer, or splitting proportionally. The ruling is what reveals (or withholds) the preimage, so funds only move per the decision.
Most payment problems fall into three buckets: no wallet connected, not enough inbound liquidity, or an expired/failed invoice. Colabonate returns structured error codes so you know exactly what to fix.
WALLET_REQUIRED
No wallet yet — create one in Settings → Wallet, or connect via Lightning
PAYMENT_UPSTREAM_ERROR
The Lightning provider rejected it — check amount limits / liquidity
Invoice expired
Lightning invoices timeout — regenerate and pay quickly
A brand-new wallet often has no inbound liquidity — fund it on-chain or use an LNURL withdraw first.
Keep all dispute-relevant communication inside the platform — external messages are not evidence.
Common error codes
WALLET_REQUIRED (400): your account has no wallet yet — create one in Settings → Wallet or connect via Lightning. PAYMENT_UPSTREAM_ERROR (502): the upstream Lightning provider (e.g. LNBits) rejected the invoice, often due to amount limits or missing liquidity. DB_ERROR (500): a server-side problem — retry or contact support.
No inbound liquidity — how to fix
To RECEIVE over Lightning your wallet needs inbound capacity. New wallets start empty. Fix it by: funding on-chain then opening a channel, using an LNURL withdraw from a service that pushes sats to you, or using a wallet with built-in liquidity management (e.g. Phoenix). For larger amounts, ensure sufficient channel capacity.
Invoice expired
Lightning invoices have a short expiry (often minutes). If you wait too long, the invoice becomes invalid and the payment fails. Regenerate the invoice and pay promptly. For escrow hold invoices, the lock survives, but a fresh invoice may be needed if the initial setup times out.