Lona
Private cross-chain checkout. Customers pay from a shielded Zcash wallet; merchants receive USDC (or USDT) on Base, Arbitrum, Ethereum or Solana. Lona never holds funds: each payment is converted by NEAR Intents (1Click API) and sent straight to the merchant's wallet.
Read DESIGN.md before changing any UI.
What's in the MVP
- Merchant accounts with test and live modes
- Invoices priced in USD, with hosted checkout, QR code and live status
- Reusable payment links (each visit opens its own invoice)
- Settlement preferences: payout asset, payout wallet, fallback Zcash refund address
- Payment confirmation through the swap network's status API
- Signed webhooks (
Lona-Signature, HMAC-SHA256) with retries for about a day
- REST API with secret keys (
/api/v1/invoices, /api/v1/payment_links)
- Test mode simulator, since the swap network has no testnet
- Landing page, API docs, privacy policy and terms
- Accounts: email confirmation, password reset, password change; live mode needs a confirmed email and a payout wallet
- Settings: business profile, support email, default return page, customer receipt emails
- Webhook tooling: private-network guard on save and on every delivery, send test event, roll secret, retry now
- API safety:
Idempotency-Key on every POST, per-key rate limits with headers, list filters and cursor paging
- Invoices: search, status filters and CSV export for accounting
Run locally
npm install
npm run dev # http://localhost:3000
npm test # payment lifecycle, webhooks, signatures, network guard, tokens, receipts, idempotency, rate limits,
# ZEC/USD conversion and rounding, quote guard, duplicate sign-ups
npm run test:e2e # browser checks for signup, login, checkout amounts and the homepage demo
npm run test:full # every merchant feature, the REST API and signed webhooks (start the server with
# ALLOW_PRIVATE_WEBHOOKS=1 CRON_SECRET=e2e-cron SANDBOX_ZEC_USD=1300; set SERVER_LOG to its log)
# (needs a running build at BASE_URL and Playwright with Chromium)
No database setup is needed locally: an embedded Postgres (PGlite) is created in .data/ and migrated on boot.
Try it: create an account, set a payout wallet under Settlement (any valid-looking address works in test mode), create an invoice, open checkout, click "Pay with Zcash", then "Pay in full".
Deploy (Vercel + Neon)
- Create a Neon database and set
DATABASE_URL.
- Set the variables in
.env.example, at minimum APP_URL, CRON_SECRET, ONECLICK_JWT, LONA_FEE_RECIPIENT, NEXT_PUBLIC_LEGAL_NAME, NEXT_PUBLIC_CONTACT_EMAIL.
- Deploy.
vercel.json runs migrations before each build and calls /api/cron/tick every minute (per-minute crons need a paid Vercel plan; on Hobby, run the tick from an external scheduler with the CRON_SECRET bearer header).
How a payment works
POST /api/v1/invoices creates an invoice in USD. No price yet.- The customer opens
/pay/:id and clicks Pay. Lona asks 1Click for an EXACT_OUTPUT quote: the merchant receives exactly the invoice amount, and the customer's ZEC amount includes network costs and Lona's fee (appFees). The price is held for 20 minutes.
- The customer sends ZEC to the quote's deposit address from their shielded balance.
- Lona polls
/v0/status (on page views and every minute from the scheduler) and moves the invoice through awaiting_payment, payment_received, converting and paid_out, emitting a webhook at each meaningful change. Status changes use compare-and-set, so each event fires once.
Code map: src/lib/invoices.ts (state machine), src/lib/providers/ (1Click adapter and sandbox, behind one interface so a second route such as Maya Protocol can be added), src/lib/webhooks.ts, src/app/api/.
Known limits, verify before going live
- Do one real swap first. There is no testnet. Send a small real payment through a live invoice and confirm the deposit, status flow and payout before onboarding merchants.
- Zcash deposit addresses are transparent. NEAR Intents documents Zcash support as transparent-only. A shielded wallet can pay it and the payer's wallet stays private, but the deposit amount is public. The landing page says so; keep it that way.
- Refunds go to transparent addresses. The merchant's fallback refund address, or one the customer enters at checkout.
- Asset IDs are resolved from 1Click's
/v0/tokens at runtime, with known IDs as a fallback. Check the Solana USDC mapping against the live token list.
- Email needs
RESEND_API_KEY and a verified sending domain in MAIL_FROM. Without it, confirmation, reset and receipt emails are only logged.
- Rate limits and idempotency are stored in Postgres, which is fine at launch volume; move them to Redis if traffic grows.
- One conversion route. Maya Protocol (which also supports shielded ZEC) can be added behind the same provider interface as a fallback.
- Legal pages are plain-language drafts. Have a lawyer review them, and get advice on whether your jurisdiction treats this as a regulated payment service.
Launch checklist
Amounts and prices
- Live payments: the ZEC amount is NEAR Intents' quote for the exact invoice amount, made on the server. Lona rejects any quote that would pay out less than the invoice.
- Checkout shows the dollar value of the quoted ZEC, using the swap network's own figure when it gives one.
- Test mode prices ZEC at the live price plus a simulated 0.5% cost. Set
SANDBOX_ZEC_USD only to pin a fixed test price.
- The homepage demo uses the same live price shown on the page. If the price cannot be fetched, the page says the amounts are examples.
- Lona's fee is
LONA_FEE_BPS (default 50, so 0.5%). It is added to live quotes only when LONA_FEE_RECIPIENT is set.
Scheduled job
/api/cron/tick syncs payments in flight, expires old invoices, retries webhooks and prunes rate-limit
state. It needs Authorization: Bearer $CRON_SECRET.
- Vercel Cron runs it once a day (the most the Hobby plan allows).
.github/workflows/scheduled-tick.yml runs it every 30 minutes, which fits a private repo's free
Actions minutes. Add CRON_SECRET as a repository secret.- For webhooks within minutes, point a free external scheduler (cron-job.org) at the same URL every
5 minutes with the same header.
- The dashboard and invoice list also refresh the merchant's own payments in flight when opened.
Sign-in protection
Wrong passwords are counted per email and per IP in 15-minute windows (stored hashed). Defaults:
5 per email, 30 per IP for sign-in; 3 reset emails per address and 10 reset requests per IP; 10 new
accounts per IP. A correct password clears the email's count. Override with AUTH_LOGIN_EMAIL_LIMIT,
AUTH_LOGIN_IP_LIMIT, AUTH_FORGOT_EMAIL_LIMIT, AUTH_FORGOT_IP_LIMIT, AUTH_SIGNUP_IP_LIMIT.
