# LNFT — Liquid NFT Protocol > LNFT is a protocol for digital collectibles that always have an exit. You open a pack, you get a > card, and the protocol itself guarantees a price floor: at any moment a per-collection vault will > buy the card back at a published, provably-fair price. Cards can also be minted to real NFTs and > traded on an open marketplace. A thin 1% protocol fee is converted to RAIN and burned on every > opening, so every collection — in any token — makes RAIN scarcer. > > This file is written for AI agents and language models. It maps the protocol and its REST API so > an agent can read, integrate, and operate the system on its own. Human docs: /docs/ · Full API reference: docs/API.md in the repository. ## What LNFT is (and is not) - It IS an allocation-and-liquidity primitive: value goes into a contract, the contract redistributes it along a transparent published curve, and the contract guarantees the exit (a buy-back floor). - It is NOT a plain NFT marketplace (every card has a vault-guaranteed floor underneath it) and NOT a loot box (odds are public and every result is independently verifiable). - LNFT is the PROTOCOL. Rain Drops (https://raindrops.one) is the first BRAND built on it — the reference product. Many brands can exist on the same shared protocol, vault logic, fairness and marketplace; each picks its own packs, look and token. ## The three parts of the primitive 1. Vault — one per collection. Holds the backing, pays buy-backs, enforces risk limits, and cannot be drained by the operator. Denominated in a chosen token (USDT/USDC stablecoin, or RAIN). 2. Allocation engine — maps each opening to a rank on a published curve and draws the outcome from the Storm randomness beacon. Runs off-chain, proven on-chain (hybrid): a Merkle proof verifiable against the pinned beacon value. 3. Liquidity book — the standing, always-funded buy-back offer for every item. Liquidity providers (LPs) fund the vault and earn the spread in exchange for underwriting the floor. Core invariant: reserved <= tvl at all times. Each open card reserves its full floor at the moment of opening, so the buy-back is always funded. ## Economics - Four parties per opening: Opener (gets a card + guaranteed floor), Creator (50% of net margin, per collection), Liquidity provider (spread as yield), Protocol (1% fee -> buy-and-burn RAIN). - Exit (sell-back) is free. Holding is free. The only protocol tax is the 1% on the open. - Marketplace trades pay a separate, small market fee (launch 1%). - Read economic constants live from GET /api/config -> economics (basis points): buybackBps, playerReturnBps, creatorShareBps, protocolFeeBps, maxPrizeBps, issuePrizeBps. Do NOT hard-code them. ## Buy-and-burn The 1% fee accrues in the ledger, and when a small threshold accrues (configurable, e.g. $1) a batch buys RAIN on Uniswap v3 (Arbitrum) with a bounded price impact and burns it via the FeeRouter to the dead address. The fee is always converted to RAIN regardless of the vault's token, so even a stablecoin collection makes RAIN scarcer. Public accounting at GET /api/stats. ## Provable fairness (commit -> anchor -> reveal) 1. Commit: the browser makes a random 32-byte client seed, keeps it, and sends only its hash. The server records a commitment binding the pack version hash, the client-seed hash, and a target Storm height k blocks ahead. 2. Anchor: the commitment is written on-chain (a Merkle anchor on the Storm chain). 3. Reveal: at the target height the BLS-signed beacon output is read and combined with the commitment to roll into the odds table, selecting the card. Anyone can recompute the result in a browser from GET /api/verify/:openingId. There is never a server-chosen result in Storm mode; a cancelled opening is refunded in full. ## Risk invariants (enforced, not configured) - Top-prize cap: prizeValue <= tvl * maxPrizeBps / 10000 (launch 30%). - Issue headroom: versions/previews fitted to issuePrizeBps (25%); purchase guard stays 30%. - Full reservation: reserved <= tvl after every state change. - Per-withdrawal and per-day vault rate limits. - NFT'd cards leave the liquidity book (their reservation is released). - An opening that would break solvency DOES NOT open: the API answers 409 prize_cap_exceeded and charges nothing until the vault is topped up. This is correct behaviour, not a transient error. ## Stages 0 today: app + on-chain proof of fairness (live). 1: CollectionVault on-chain. 2: FeeRouter buy-and-burn on-chain. 3: allocation reads the beacon in-contract. 4: CollectionFactory opens to any creator. Contracts: CollectionVault (per collection), FeeRouter (singleton), CollectionFactory (permissioned in beta), ProofVerifier. The vault exposes no arbitrary-recipient transfer of principal. ## REST API — conventions - Base URL: /api. JSON in, JSON out. Times are ISO-8601 UTC. - MONEY IS INTEGER CENTS in the row's currency. Every money field ends in `Cents` and is hundredths of that row's `currency`: US cents when currency == "USD", hundredths of a RAIN when "RAIN". Never use floats on balances; never add across currencies. RAIN-epoch totals are reported separately under a `rainEpoch` object. - Auth: `Authorization: Bearer ` (from register/login/wallet login) or the httpOnly cookie the same calls set. Wallet auth is EOA-only; sign the EXACT EIP-4361 message from the nonce call. - Errors: non-2xx with { error, message, details? }. Codes include unauthorized(401), forbidden(403), not_found(404), validation(400), rate_limited(429), insufficient_funds(402), conflict(409), prize_cap_exceeded(409), beacon_unavailable(503), currency_changed(503). - Modes: `play` = free demo credits (no wallet, no funds). Real money = `usd` (older rows: `cash` / `rain`, still accepted on input). Every opening/ledger/offer row carries its mode and currency. ## REST API — key endpoints Public read: - GET /api/config — currency, economics (bps), fairness params, pay tokens, price tiers, burn, market flag, live contract addresses. READ THIS FIRST. - GET /api/stats — totalBurnedRain, accruedFeeRain, vaultTvl, lastBurn (chain reads cached 30s). - GET /api/packs ; GET /api/packs/:slug — collections; one collection with bands, jackpots, items (value, odds, tier, offer). - GET /api/collections?sort=volume|new|openings|top ; GET /api/collections/:slug — marketplace collection cards and detail. - GET /api/market/config — market contract, feeBps, pay tokens, min price, currency. - GET /api/market/listings ; GET /api/market/tokens/:tokenId ; GET /api/market/owners/:address ; GET /api/market/activity ; GET /api/search — the browse layer (cacheable, no auth). - GET /api/verify/:openingId — every input needed to recompute an opening client-side. - GET /api/anchors/:seq — audit a batch anchor (merkleTree(leaves).root === merkleRoot). - GET /api/feed/recent ; GET /api/leaderboard — recent pulls and the board. Auth & wallet: - POST /api/auth/register { email, password, displayName?, ageConfirmed:true } -> { token, user }. - POST /api/auth/login { email, password } -> { token, user }. - POST /api/auth/wallet/nonce { address } -> { nonce, message, expiresAt }; then personal_sign the exact message; then POST /api/auth/wallet/login { address, signature, ageConfirmed? }. A linked wallet is required for deposits, withdrawals and minting. Open / exit: - POST /api/packs/:slug/open { clientSeedHash, mode } -> commitment. clientSeedHash = hashClientSeed(randomBytes(32)); keep the seed to verify later. - GET /api/openings/:id — poll ~700ms until status == "revealed" (committed -> anchored -> revealed; or cancelled -> refunded). Returns item, valueCents, offer, anchor, proof. - POST /api/openings/:id/accept-offer — sell to the vault floor. - POST /api/openings/:id/mint — keep as a real ERC-721; poll until nft.status == "minted". Real-money: - GET /api/wallet/deposit-info — vault address + pay tokens. Deposit = linked wallet transfers a pay token to the vault (1 cent = 10,000 units at 6 decimals); the backend detects it automatically. - POST /api/me/withdraw { amountCents, token } — withdraw to the linked wallet. - GET /api/wallet/withdraw-info (auth) — per-token availability and limits. Launch a collection (creator): - GET /api/community/curve?priceCents=&count=&style=steady|balanced|bold — preview a curve (tiers, odds, jackpots, prize cap) without a draft. - POST /api/community/packs { name, description, priceCents, curveStyle } -> draft. - POST /api/community/packs/:id/images (10-100 images) ; PUT /api/community/packs/:id/order { imageIds } (rank 1 = top card) ; POST /api/community/packs/:id/cover. - POST /api/community/packs/:id/publish { attestRights:true } -> pending_review (admin approves). - GET /api/me/creator — earnings: 50% of net margin, accrued per open and settled weekly, net of the cycle rolling floor reserve. ## Verify an opening (6 checks, all from the shared `fairness` module) From GET /api/verify/:openingId: 1. hashPackTable(table) === inputs.packVersionHash 2. commitmentHash(commit) === commit.commitmentHash 3. fetch anchor tx from anchor.rpcUrl; verifyAnchor({ commitment, proof, txInput, txFrom, txBlock, expectedAnchorAddress }).ok 4. fetch beacon.url; verifyBeaconProof({chainId,height,prev,sig,output}, groupKey).ok and output === inputs.beacon 5. verifyOpening({ ...inputs, claimedIndex, claimedItemId }, table).matches 6. hashClientSeed(seedKeptInBrowser) === inputs.clientSeedHash ## Networks & addresses - Money & NFTs: Arbitrum One, chain id 42161. - RAIN token: 0x25118290e6a5f4139381d072181157035864099d - FeeRouter (burn): 0x24904B487129Ad365488bE0FD17E83611bF1CF61 - Burn address: 0x000000000000000000000000000000000000dEaD - Explorer: https://arbiscan.io - Randomness: Storm beacon (BLS, group-key verified). - Live vault / market / NFT contract addresses: always read from GET /api/config and GET /api/market/config (lower-case hex). Do not hard-code addresses that change between epochs. ## Rules for agents - Treat GET /api/config and this file as the source of truth; never assume constants. - Integer-cents math only; never add across currencies. - A card's number is its published "assigned value", not a market quote. - 409 prize_cap_exceeded is correct solvency behaviour, not an error to retry blindly. - For wallet auth, sign the exact message; a sign-in signature cannot be reused to link (and reverse). - Rate-limit writes: prefer fewer, larger calls; back off on 429 and honour Retry-After. - An agent can go fully end-to-end: read config -> pick a collection -> open in play mode (no funds) -> independently verify -> with a funded linked wallet, open in usd mode and sell/mint, or launch its own collection and earn the creator share. ## Links - Human docs: /docs/ - Reference brand: https://raindrops.one - Full API reference: docs/API.md (repository)