Build on the Liquid NFT Protocol
LNFT is the protocol for collectibles that always have an exit. A card you open carries a floor the protocol itself guarantees — sell it back to the vault any time, or trade it on the open market. This is the reference for developers and AI agents who want to read the system, integrate it, or launch a brand of their own on top.
Overview
A Liquid NFT is a collectible with a price floor the protocol underwrites. You open a pack, you get a card, and at any moment the protocol will buy that card back from you at a published, provably-fair price — no marketplace wait, no guessing what it is "worth."
The protocol is a small set of smart contracts plus a settlement layer. Anyone can launch a collection. Each collection is backed by its own vault that underwrites the floor. Liquidity providers fund the vault and earn the spread; creators earn a share of every opening; and the protocol takes a thin 1% fee that buys and burns RAIN, so every collection — in any token — makes RAIN scarcer.
It is not an NFT marketplace and it is not a loot box. It is an allocation-and-liquidity primitive: value goes into a contract, the contract redistributes it along a transparent curve, and the contract guarantees the exit.
LNFT is the protocol. Rain Drops is a brand built on it. Rain Drops (raindrops.one) is the first consumer product that runs on LNFT — the reference brand. Many more can exist: each picks its own packs, its own look, its own token, and sits on the same shared protocol, vault logic, fairness and marketplace.
Why it exists
Two models tried to make digital collectibles valuable and both left a gap:
NFTs
Ownership, but no liquidity. You bought a JPEG and prayed someone would buy it later. Rarity was a marketing claim, not a verifiable fact. Most holders are stuck.
Loot boxes / gacha
The thrill of opening, but no transparency and no exit. Odds were hidden, and whatever you "won" was locked inside one company's walled garden.
A Liquid NFT keeps the good parts of both — the art, the rarity, the thrill of the open — and fixes the two things that killed them:
- Provable fairness. Every allocation is anchored to on-chain randomness (the Storm beacon) and a published distribution curve. Anyone can verify that the odds they got are the odds that were advertised. You don't trust us; you check.
- Guaranteed liquidity. Every item has a standing buy-back offer from the vault. The floor is not a hope — it is underwritten capital. You can always exit.
Glossary
| Term | Meaning |
|---|---|
| LNFT | The Liquid NFT Protocol — the contracts, settlement and marketplace described here. |
| Collection / pack | A published set of cards with a fixed curve and odds, backed by one vault. "Pack" is the brand-facing word; "collection" the protocol word. |
| Opening | One purchase-and-reveal: a user pays the price, the beacon decides the card, the vault reserves its floor. |
| Vault | The per-collection pool that holds backing, pays buy-backs and enforces risk limits. Cannot be drained by the operator. |
| Floor / offer | The standing price the vault will pay to buy a card back. Reserved at the moment of opening. |
| Assigned value | A card's published value from the curve — not a market price. Label it "Assigned value", never a quote. |
| LP | Liquidity provider: funds the vault, earns the spread, underwrites the floor. |
| Buy-and-burn | The 1% protocol fee, converted to RAIN and burned on every opening. |
| Storm beacon | The randomness beacon that decides each opening; openings carry a BLS-verifiable proof against it. |
| Mode | play = free demo credits; the real-money mode is usd (older rows: cash/rain). Every money row says its currency. |
The primitive
Strip it to its core and the protocol is three parts.
1 · Vault
Holds the value backing a collection, pays out buy-backs, and cannot be drained by the operator. One vault per collection, so a jackpot in one collection can never touch another. The vault denominates in a chosen token — a stablecoin (USDT/USDC) or RAIN. A creator who wants a stablecoin collection simply spins up a stablecoin-denominated vault.
2 · Allocation engine
Maps each opening to a rank on a published curve (floor value, rare tiers, top card) and draws the outcome from the Storm beacon. The curve and the odds are public and fixed at the collection's version hash. Allocation runs off-chain, proven on-chain (hybrid): the heavy computation is cheap and fast off-chain, and the result carries a Merkle proof anyone can verify against the pinned beacon value.
3 · Liquidity book
Defines the standing buy-back offer for every item and guarantees it is always funded. LPs deposit into the vault and become the underwriters of the floor: they earn the spread on every opening and carry the risk of a large win. A real DeFi position — yield in exchange for underwriting.
When those three live as contracts, you have a protocol. A website becomes a convenient interface over the protocol, not "the operator." That is what makes a brand like Rain Drops swappable and a marketplace trustworthy.
Life of a card
# one opening, start to exit
pay price P (in the vault's token)
│
├─ 1% → FeeRouter → (swap to RAIN if needed) → BURN
├─ spread → credited to LP shares (yield)
├─ creator share → claimable by the collection's creator
└─ card floor F → RESERVED in the vault as a liability
reveal: the Storm beacon decides the card; a proof is attached
exit, any time — the holder picks one:
sell back → vault pays F from the reserve (always funded)
mint as NFT → card becomes a real ERC-721 on Arbitrum
list / sell → trade on the open marketplace at any price
hold → free, forever
Because F is reserved at the moment of opening, the buy-back is always funded. That is the whole liquidity guarantee, expressed as one accounting invariant: reserved ≤ tvl.
Economics & fees
Every opening moves value between four parties, transparently:
| Party | Gets |
|---|---|
| Opener | A card with a guaranteed floor and the chance of a rare or top card. Can hold, sell back instantly, mint to a real NFT, or list on the market. |
| Creator | A share of net margin — accrued per open, settled on a rolling weekly cycle once each cycle's floor risk clears. Default 50% of net margin. |
| Liquidity provider | The spread as yield, in exchange for underwriting the floor. |
| Protocol | 1% of each opening, used to buy RAIN on the market and burn it. |
What we tax, and what we leave free
- 1% on the open → buy-and-burn RAIN. Predictable, scales with volume, hides inside the spread. This is the engine.
- Exit (sell-back) is free. Instant exit is the sacred promise. Taxing the exit breaks the one thing that makes a collectible liquid. We never do it.
- Holding is free. The behaviour we want to encourage; never penalised.
- Marketplace trades pay a small market fee (launch value 1%), set per market contract — separate from the protocol burn fee.
Creator payouts: fast, but not reckless
A creator's 50% share accrues the instant a pack is opened — not once a month. It settles on a rolling weekly cycle, so a creator is paid within days, not at a distant month-end. The short wait exists for one business reason: a newly opened card still carries a live floor liability (the opener can sell it straight back to the vault). Paying the creator before that risk clears could pay out margin the vault then has to refund. So each cycle keeps a rolling floor reserve — the portion of margin still exposed to open buy-backs — and releases it as those positions close. The creator gets fast, predictable weekly settlement; the vault never pays out margin it hasn't truly earned.
| Property | Value | Why |
|---|---|---|
| Accrual | Per open, real-time | Creator sees earnings immediately. |
| Settlement cycle | Weekly (rolling 7-day) | Fast cash-flow without month-end lag. |
| Rolling reserve | Margin still under floor risk | Protects the vault from refunding paid margin. |
Key economic constants are served live at GET /api/config under economics (basis points): buybackBps, playerReturnBps, creatorShareBps, protocolFeeBps, maxPrizeBps, issuePrizeBps, plus creatorSettlementDays (default 7). Always read them from the API rather than hard-coding.
Buy-and-burn
The buy-and-burn is the keystone. Because the fee is always converted to RAIN regardless of the vault's token, even a stablecoin-denominated collection makes RAIN scarcer. RAIN becomes the value-capture token of the entire economy — demand for it grows with total protocol volume, not with any single collection or brand.
How it runs
- The 1% fee accrues in the ledger as it is earned.
- When a small threshold accrues (configurable, e.g. $1), a batch runs: the fee buys RAIN on Uniswap v3 (Arbitrum) with an exact approval and a bounded price impact, then burns it through the
FeeRouterto the dead address. - Every burn emits an on-chain event and is reported publicly at
GET /api/stats(totalBurnedRain,accruedFeeRain,lastBurn). - Burns run in small, slippage-bounded batches because the RAIN pool is thin; a single large conversion would move price.
Upward price impact on success is a goal — the burn exists to make RAIN scarcer — but each individual swap is still slippage-bounded so a batch can never be sandwiched into a bad fill.
Provable fairness
Fairness is mathematical, not trusted. Every opening is bound to a public randomness beacon and a published odds table, and anyone can recompute the result in a browser.
The commit → anchor → reveal flow
- Commit. The browser makes a random 32-byte client seed, keeps it, and sends only its hash. The server records a commitment that binds the pack version hash, the client-seed hash, the current Storm height and a target height
kblocks ahead. - Anchor. The commitment is written to the Storm chain (an on-chain Merkle anchor). An explorer link is available.
- Reveal. At the target height the beacon output is read; combined with the commitment it yields a single roll into the odds table, which selects the card. The beacon carries a BLS signature verifiable against the pinned group key.
Everything needed to recompute is returned by GET /api/verify/:openingId: the pack table and its hash, the commitment, the anchor transaction and Merkle proof, the beacon output and signature, and the claimed result. The verification steps (all from the shared fairness module) are listed in the Verify flow.
Risk invariants
A permissionless launcher needs guardrails baked in, or the first thin vault with a giant prize gets wiped and takes an LP with it. These are enforced invariants, not UX settings.
| Invariant | Rule |
|---|---|
| Top-prize cap | prizeValue ≤ tvl × maxPrizeBps / 10000 (launch 30%). A thin vault literally cannot settle an opening whose top card it can't cover. |
| Issue headroom | Pack versions and previews are fitted to issuePrizeBps (25%) of the vault; the purchase guard stays at 30%. |
| Full reservation | Every open card's floor is reserved; reserved ≤ tvl holds after every state change. The vault can never owe more than it holds. |
| Rate limits | Per-withdrawal and per-day caps bound how fast value can leave the vault. |
| NFT'd cards leave the book | Once minted to a real NFT, a card is no longer floor-backed; its reservation is released. This prevents double-counting a liability the holder opted out of. |
If an opening would violate the solvency or prize-cap rule it does not open — the API answers 409 prize_cap_exceeded and nothing is charged until the vault is topped up.
The marketplace
Beyond the vault floor, cards can be minted to real NFTs and traded on an open secondary marketplace — the OpenSea-style layer of the protocol. The difference from a plain NFT market: every card still has the vault floor underneath it, so a listing is a bet above a guaranteed price, never above zero.
What a brand or integrator gets for free
- Browse layer — collections, items, activity, listings, owners and search, all public and cacheable:
GET /api/collections,/api/market/listings,/api/market/tokens/:tokenId,/api/market/owners/:address,/api/market/activity,/api/search. - On-chain trading — list, cancel, buy against the market contract; the backend indexes events and serves them after confirmations.
- Floor-aware pricing — every token card carries its collection, its assigned value and its live listing, so a UI can always show "floor vs. ask."
Market config is at GET /api/market/config (contract address, fee bps, pay tokens, min price). Events and listings are stored in the unit of the contract that emitted them, so a card pulled in the RAIN epoch keeps RAIN history while new trades settle in dollars.
Contracts & stages
The protocol ships in stages; each stage is a complete product and each adds trust. On-chain money and NFTs live on Arbitrum One (chain 42161); randomness comes from the Storm beacon.
| Stage | What goes on-chain |
|---|---|
| 0 · today | App with on-chain proof of fairness. Live. |
| 1 · vault | CollectionVault holds, backs and pays out. First proof the operator can't rob it. |
| 2 · burn | FeeRouter auto-converts the 1% fee to RAIN and burns. Proves the RAIN flywheel. |
| 3 · allocation | The curve reads the Storm beacon in-contract. Fairness is enforced, not just proven. |
| 4 · creators | CollectionFactory opens to anyone: launch a collection, pick the token, fund the vault, earn automatically. |
The core contracts are CollectionVault (one per collection, minimal-proxy clone), FeeRouter (singleton burn router), CollectionFactory (permissioned in beta) and a ProofVerifier that checks a Merkle leaf against the pinned beacon. The vault exposes no arbitrary-recipient transfer of principal: the worst a compromised operator key can do is pay valid floors to real holders.
Brands on the protocol
Rain Drops is a brand that stands on this protocol — the first of many. A brand is an interface and a set of collections; the protocol underneath is shared.
Three ways to build:
- Your own storefront, our packs. Point a site at the same API and surface existing public collections. You get the catalogue, the fairness and the marketplace with almost no backend.
- Your own collections. Launch packs under your brand (your art, your curve, your token), funded by your vault, and earn the creator share on every opening.
- Full brand. Your look, your collections, your community packs and your marketplace presence — everything a consumer product needs — on the shared protocol, vault logic and burn.
Whatever you build, the three things that cannot be faked come from the protocol: provable randomness, on-chain anchoring, and a guaranteed floor. Your brand owns the experience; the protocol owns the trust.
Quickstart
The API is REST: JSON in, JSON out, times are ISO-8601 UTC. Base URL is your API origin + /api. Start by reading config, then list collections.
# 1. read live protocol config (currency, economics, fairness, market)
curl -s https://<api>/api/config | jq .
# 2. list public collections (newest first)
curl -s "https://<api>/api/collections?sort=volume&limit=24" | jq '.collections[].slug'
# 3. one collection, with items, odds bands and jackpots
curl -s https://<api>/api/collections/<slug> | jq .
# 4. protocol stats: burned RAIN, accrued fee, vault TVL
curl -s https://<api>/api/stats | jq .
Amounts are integers. Every money field ends in Cents and is in hundredths of the row's currency — US cents when currency is "USD", hundredths of a RAIN when "RAIN". Never add across currencies; RAIN-epoch totals come back in a separate rainEpoch object.
REST API
The most-used endpoints are below. The full reference (every field, every error) lives in docs/API.md in the repository. Auth is a bearer token (Authorization: Bearer <token>) or the httpOnly cookie set by register/login; errors are non-2xx with { error, message, details? }.
Public — read
Currency, economics (bps), fairness, pay tokens, price tiers, burn, market flag. Read this first; don't hard-code constants.
Protocol numbers: total burned RAIN, accrued fee, vault TVL, last burn. Chain reads cached 30s.
Collections and one collection in full: price, curve style, bands, jackpots, items (value, odds, tier, offer).
Marketplace browse layer: collection cards, active listings, a single token with its history. Cacheable, no auth.
Everything needed to recompute an opening's result in the browser (see Verify flow).
Auth & wallet
Email + password (+ 18+ ageConfirmed on register). Returns { token, user }.
Get a nonce, personal_sign the exact EIP-4361 message, send the signature. Plain wallets (EOA) only. A linked wallet is required for deposits, withdrawals and minting.
Play / real-money
Body { clientSeedHash, mode }. mode default play; real money is usd (needs deposits enabled). Returns the commitment.
Poll until status is revealed. Returns the card, the offer, the anchor and the beacon proof.
"Sell now" to the vault floor, or "Keep as NFT" (mints an ERC-721; poll until nft.status is minted).
Deposit: the linked wallet transfers a pay token to the vault (1 cent = 10,000 units at 6 decimals); the backend sees it by itself. Withdraw to the linked wallet.
Launch a collection (creator)
Create a draft: name, description, a price tier, a curve style (steady/balanced/bold). Then add images, set order and cover, and publish.
Preview a curve for a price and style without a draft: tiers, odds, jackpots, prize cap. Use it to design before you commit.
Opening flow
// 1. browser makes a 32-byte client seed, keeps it, sends the hash
seed = randomBytes(32)
body = { clientSeedHash: hashClientSeed(seed), mode: "usd" }
POST /api/packs/:slug/open → { openingId, status: "committed", commit }
// 2. poll until revealed (~700ms)
GET /api/openings/:openingId
committed → anchored → revealed (or cancelled → refunded in full)
// 3. on reveal you get the card, the floor offer and the proof
{ item, valueCents, offer: { amountCents, expiresAt }, proof, anchor }
// 4. the holder exits however they like
POST /api/openings/:openingId/accept-offer // sell to vault floor
POST /api/openings/:openingId/mint // keep as a real NFT
There is never a server-chosen result in Storm mode. A cancelled opening (anchor missed its deadline, or the beacon was unavailable past the timeout) is refunded in full.
Verify flow
GET /api/verify/:openingId returns every input. Recompute entirely client-side, all from the shared fairness module:
hashPackTable(table) === inputs.packVersionHash— the odds table is the one that was published.commitmentHash(commit) === commit.commitmentHash— the commitment binds your seed hash and the target height.- Fetch the anchor tx by hash from
anchor.rpcUrl, thenverifyAnchor(...)— the commitment was written on-chain before the beacon was known. - Fetch
beacon.url, thenverifyBeaconProof(...)and checkoutput === inputs.beacon— the randomness is the signed Storm output. verifyOpening({ ...inputs, claimedIndex, claimedItemId }, table).matches— the roll maps to the card you got.hashClientSeed(seedKeptInBrowser) === inputs.clientSeedHash— your own seed was part of the draw, so the server could not pre-compute it.
Batch anchors are independently auditable at GET /api/anchors/:seq (merkleTree(leaves).root === merkleRoot).
Launch a collection
- Design the curve. Call
GET /api/community/curve?priceCents=&style=and read back tiers, odds, top card, jackpots and the prize cap. Pick a price tier and a style. - Create a draft.
POST /api/community/packswith name, description, price, style. - Add art.
POST /api/community/packs/:id/images(10–100 images), set the order withPUT …/order(rank 1 = most valuable), set a cover. - Publish.
POST /api/community/packs/:id/publishwithattestRights: true→ statuspending_review. An admin approves it to public. - Earn. You accrue 50% of net margin on every open; it settles to your balance each weekly cycle, net of the cycle's rolling floor reserve. Track it at
GET /api/me/creator.
The published version is hashed; its values and odds are frozen until an admin re-issues it. Everything a buyer needs to trust the pack — the table hash, the fairness proof, the vault floor — is produced by the protocol automatically.
Agent guide
LNFT is built to be read and operated by autonomous agents, not just humans. An agent can discover the whole system from two files and a handful of GET requests, then act through the same REST API.
Read the system
- /docs/llms.txt — a plain-text map of the protocol and the API, written for language models. Fetch it first.
GET /api/config— the live, authoritative constants: currency, economics (bps), fairness parameters, pay tokens, market flag. Never assume; read.GET /api/stats— the live protocol state (burned RAIN, accrued fee, vault TVL).
Rules an agent must follow
- Money is integer cents in the row's
currency. Never do float math on balances; never add across currencies. - Odds and values are published, not quoted. Call a card's number its "assigned value," never a market price.
- Respect the solvency guard. An opening can return
409 prize_cap_exceeded; that is correct behaviour, not an error to retry blindly. - Sign the exact message. For wallet auth,
personal_signthe precise text from the nonce call — a sign-in signature cannot be reused to link, and the reverse. - Rate-limit writes. Prefer fewer, larger calls; back off on
429and honour anyRetry-After.
An agent can go end-to-end with no human in the loop: read config → pick a collection → open in play mode to learn the flow → verify the result independently → (with a funded, linked wallet) open in usd mode, sell back or mint, or launch its own collection and earn the creator share.
Recipes
Discover & summarise a collection
cfg = GET /api/config
packs = GET /api/collections?sort=volume
one = GET /api/collections/{slug}
// report: price, floor, top card, odds bands, 24h volume, floor listing
Open and independently verify (play mode, no funds)
seed = randomBytes(32)
op = POST /api/packs/{slug}/open { clientSeedHash: hashClientSeed(seed), mode:"play" }
poll GET /api/openings/{op.openingId} until status == "revealed"
v = GET /api/verify/{op.openingId}
// run the 6 checks in the Verify flow; only trust a result that recomputes
Launch a branded collection
curve = GET /api/community/curve?priceCents=1000&style=balanced
draft = POST /api/community/packs { name, description, priceCents:1000, curveStyle:"balanced" }
POST /api/community/packs/{id}/images (10–100 images)
PUT /api/community/packs/{id}/order (rank 1 = top card)
POST /api/community/packs/{id}/publish { attestRights:true }
// earn 50% of net margin, settled weekly; track GET /api/me/creator
Addresses & networks
| Thing | Value |
|---|---|
| Money & NFT chain | Arbitrum One — chain id 42161 |
| RAIN token | 0x25118290e6a5f4139381d072181157035864099d |
| FeeRouter (burn) | 0x24904B487129Ad365488bE0FD17E83611bF1CF61 |
| Burn address | 0x000000000000000000000000000000000000dEaD |
| Randomness | Storm beacon (BLS, group-key verified) |
| Explorer | arbiscan.io ↗ |
Live addresses — the vault, the market contract, the NFT contract — are always served by GET /api/config and GET /api/market/config (lower-case hex). Read them from the API; do not hard-code a vault or market address that can change between epochs.
FAQ
Is this an NFT marketplace?
No. It is a liquidity-and-allocation primitive with a marketplace on top. The difference: every card has a vault-guaranteed floor, so the market is a bet above a real price, not above zero.
How is "the operator can't run with the money" guaranteed?
The vault contract exposes no arbitrary-recipient transfer of principal. Funds can only leave to an LP who owns the shares (from the free balance) or to the holder of record of a real card (for its reserved floor). A stolen operator key can settle valid openings and pay valid floors — annoying, not catastrophic.
What makes every collection good for RAIN?
The 1% fee is always converted to RAIN before burning, whatever token the vault uses. More total volume across all brands and collections means more RAIN bought and burned.
Can an agent do all of this without a human?
Yes — read /docs/llms.txt and GET /api/config, then operate through the REST API. Play mode needs no funds and no wallet; real money needs a funded, linked wallet.
Where is the full API reference?
Every endpoint and field is documented in docs/API.md in the repository; this page covers the parts you need to integrate and build.