Skip to main content
Luxxon is a marketplace API for live video from real places. This page is the wide-angle view of what runs where.

​
End-to-end shape

┌────────────────────────────────────────────────────────────────┐
│                       Luxxon API surface                        │
│                       api.luxxon.dev/api/v1                     │
└─────────────┬─────────────────────────────────┬─────────────────┘
              │                                 │
              │ wallet session            lxxn_* API
              │ cookie (humans)          key (machines)
              ▼                                 ▼
       ┌──────────────────────────┬───────────────────────────────┐
       │  Wallet-or-key auth guard │  Workspace = unit of tenancy │
       └────────┬─────────────────┴────────┬──────────────────────┘
                │                 │
                │                 │ SpiceDB (Zanzibar)
                │                 │ permission graph
                │                 ▼
       ┌────────▼─────────────────────────────────────────┐
       │   workspaces · api-keys · pricing · sessions      │
       │   wallet · settlements · /me                       │
       └────────┬───────────────────────────┬─────────────┘
                │                           │
                │ Postgres + PostGIS        │ Base (USDC)
                │ (data layer)              │ via LuxxonSettlement
                ▼                           ▼
       ┌────────────────────┐      ┌────────────────────┐
       │  Workspaces        │      │  Consumer wallet   │
       │  Sessions          │      │      │             │
       │  Quotes / Events   │      │      ▼             │
       │  Telemetry         │      │  Operator wallet   │
       └────────────────────┘      │   + Platform fee   │
                                    └────────────────────┘
Two surfaces hit the same API: a developer console (humans, signed lx_session cookie after a SIWE sign-in) and machine integrations (lxxn_* API keys via Authorization: Bearer). Both land in a workspace, the unit of multi-tenancy. Authorization splits cleanly: SpiceDB answers which resources is this principal entitled to, scopes answer which verbs is this credential allowed to emit. See Authentication for the full split.

​
Layers

LayerWhat it does
Wallet-or-key auth guardTwo paths. Authorization: Bearer lxxn_* → sha256 lookup against LxApiKey. Otherwise, Cookie: lx_session=… → constant-time HMAC verification of the signed payload. Either way, attaches req.lxAuth = { kind, principal }.
WorkspaceMulti-tenancy root. Holds wallet, API keys, members, role flags (CONSUMER, SUPPLIER, or both).
PricingPer-second µUSDC rates with a quote-locked flow. Dynamic factors (supply, demand, corridor) compose with base_rate in basis-points arithmetic.
SessionsAtomic unit of work. State machine REQUESTED → ASSIGNED → LIVE → ENDED with CANCELLED as the pre-LIVE escape. CAS state transitions guarantee race safety. create reads the consumer wallet’s on-chain pool balance and rejects with INSUFFICIENT_CREDIT if rate × maxDuration isn’t covered. accept is a single state flip — no signature step.
WalletRead-only view of LxWalletState + on-chain events ledger. Tracks the consumer’s pool balance via LxOnChainEvent rows of kind DEPOSIT / WITHDRAWAL / SETTLE.
SettlementsAt session end, the API composes the exact payload the relayer will pass to LuxxonSettlement.settleFromPool(). State: NOT_READY → PENDING → CONFIRMED.

​
Storage

StoreUsed for
PostgreSQL + PostGISEverything in the data layer. Geography points for session location, on-chain event ledger, append-only telemetry log.
SpiceDBAuthorization graph (Zanzibar). Workspace membership, session viewership across consumer/operator workspaces.
BaseUSDC ledger + LuxxonSettlement contract. The platform never holds funds — settlements move USDC directly from consumer to operator + platform fee in one atomic tx. Smart Wallet + Coinbase Onramp + paymasters make this work for non-crypto users (see Non-crypto users).

​
What’s a “session”

The thing the marketplace exists to deliver:
  1. A consumer says “give me a live view of (lat, lng) for up to N seconds.”
  2. An operator (the supplier) accepts the session and starts streaming from that point.
  3. The platform meters seconds where the stream is healthy and the operator is in-geofence (telemetry-backed).
  4. On end, the meter is final and a settlement payload is composed.
  5. A relayer submits the on-chain settlement: consumer wallet → operator wallet (less platform fee).
Five steps. The rest of the docs is how each step is wired.

​
What’s NOT in the platform

Knowing the non-goals is half the architecture.
  • Custody. Luxxon never holds USDC. Funds move directly between wallets via a thin settlement contract.
  • KYC. Wallet addresses are the identity. No identity provider, no legal entity binding.
  • Multi-currency. USDC only. Bridge later when volume justifies.
  • Mobile SDKs you must use. The contract is WHIP/WHEP + REST. Any WebRTC-capable encoder + any HTTPS client works.
  • Fiat on-ramps. Consumers bring USDC. Reference apps may on-ramp on their own behalf; the platform doesn’t.

​
Where to go next