# Lia Developers

> How to build web apps that run inside the Lia app (like Telegram mini apps) with the Lia SDK 1.6.0, and the server API your app's server calls with its secret key.

Every page below is Markdown. Also: all of the docs in one file (https://docs.lialabs.org/llms-full.txt), the server API as OpenAPI 3.1 (https://docs.lialabs.org/openapi.json), a rules file to add to a project (https://docs.lialabs.org/AGENTS.md), and TypeScript types in the npm package @lia-labs/sdk.

## Rules that matter most

- In a page without a build step: <script src="https://api.lialabs.org/sdk/lia-apps-v1.js"></script> gives window.Lia. Never copy or bundle that file.
- With a bundler: npm install @lia-labs/sdk (or @lia-labs/sdk-react, -preact, -vue, -svelte, -solid, -angular, @lia-labs/elements). Use one or the other on a page, never both.
- Call init() first, then ready() once the first screen is drawn. Outside Lia every call fails with code "not_in_lia"; for local development call mockLia() when isLia() is false.
- Every failure is an Error with a code. "cancelled" from pay() is a normal no, not an error to report.
- Never trust the page. Your server verifies a session token (from init() or session(), 15 minutes) with POST https://api.lialabs.org/api/apps/v1/session/verify and takes the player id from Lia's answer, never from the page.
- Secret keys (lia_test_..., lia_live_...) and the webhook secret (whsec_...) live on the server only. The app id is the only public identifier.
- Prices come from Lia's records: the page passes a product id to pay(), never an amount.
- pay(productId) opens Lia's pay sheet and answers { chargeId, productId }. The server then checks GET /charges/:id (its player, product and status), gives the item once per charge id, and calls POST /charges/:id/deliver. If it can't deliver, POST /charges/:id/refund.
- On opening, call charges() and deliver any paid, undelivered charges; listen with onCharge() too. Webhooks (charge.paid) are a nudge: check with the API, and verify the Lia-Signature header (HMAC SHA-256 of "<t>.<raw body>" with the whsec_ secret).
- Pay players in $LIA only from the server: POST /rewards with a key that names the reason (a key pays once, ever). At most 10,000 LIA a reward; handle pool_empty and daily_limit.
- A rewarded video answers { watched, adId }: give the reward only after the server checks POST /ads/verify (watched, and the same player), once per adId.
- Notifications are opt-in (requestNotifications()), sent by the server with POST /notifications, at most 3 a day per person from one app, an hour apart, 180 characters, no links. Use a startParam to open the right screen.
- Use Lia's theme (CSS variables --lia-bg-color, --lia-text-color, --lia-hint-color...), the safe areas (--lia-safe-area-inset-bottom), Lia.language (13 languages) and Lia.rtl for dir.
- Use Lia's mainButton for the main action, backButton for your own screens, Lia's dialogs and toasts, and play sound only while soundOn.
- Only your own pages load in the frame: open other sites with openLink(url).
- In text people read: "$LIA" for the token, "LIA" next to numbers (5 LIA).
- Retry server POSTs with the same Idempotency-Key header.

## Get started

- [Build apps for Lia](https://docs.lialabs.org/index.md): Lia's developer docs. Build a web app that runs inside the Lia app, with players signed in, payments in $LIA on Lia's pay sheet, invites, notifications, ads, leaderboards and storage.
- [Quickstart](https://docs.lialabs.org/quickstart.md): A working Lia app in a few minutes. Host a page, load the SDK, call Lia.init() and Lia.ready(), and open it in Lia as a tester.
- [Getting access](https://docs.lialabs.org/access.md): How an app is added to Lia today, what the Lia team sets up for it, and how you get its test key, live key and webhook signing secret.
- [Build with AI](https://docs.lialabs.org/ai.md): Everything an AI coding assistant needs to build a Lia app correctly. The docs as Markdown, llms.txt, an OpenAPI spec of the server API, TypeScript types, and a rules file for your project.

## Concepts

- [How apps run in Lia](https://docs.lialabs.org/concepts/how-apps-run.md): Your page runs in a locked frame inside the Lia app and reaches Lia only through the SDK. The three looks, Lia's header and menu, and the rules your page runs under.
- [Players and sessions](https://docs.lialabs.org/concepts/players-and-sessions.md): Every person arrives signed in as a player of your app, with an id that's only for your app. Session tokens let your server know who is asking.
- [Test and live](https://docs.lialabs.org/concepts/test-and-live.md): Every app is in test, live or paused. Test mode is for you and your testers, with pretend $LIA; live is for everyone. Keys, sessions and charges belong to one mode.
- [Payments and the pay sheet](https://docs.lialabs.org/concepts/payments.md): People pay for what your app sells in $LIA, on Lia's own pay sheet, at the price in Lia's records. Your server confirms each charge, delivers it, or refunds it.
- [Reward pools](https://docs.lialabs.org/concepts/reward-pools.md): Lia can fund a pool of $LIA for your app. Your server pays players from it, once per reward, within the pool and the daily limit per player.
- [Notifications](https://docs.lialabs.org/concepts/notifications.md): Players choose whether your app may notify them. Your server sends each notification, within limits Lia sets so the people who say yes stay glad they did.
- [Invites and links](https://docs.lialabs.org/concepts/invites.md): Bring friends into your app with Lia's friend picker, or a link anyone can open. Both open your app with a startParam, so friends land in the same match or room.
- [Public tables](https://docs.lialabs.org/concepts/lobby.md): List your game's open tables in Lia's lobby, so anyone on Lia can find a game and sit down, not just friends. Your server runs the table; Lia keeps the listing, the blocks and the reports.
- [Ads](https://docs.lialabs.org/concepts/ads.md): Full screen ads in three formats, played by Lia and paced so nobody is flooded. Your server can check that a rewarded video was really watched before it gives anything.
- [Look and feel](https://docs.lialabs.org/concepts/look-and-feel.md): Make your app feel part of Lia. Lia's theme as CSS variables, the viewport and safe areas, the person's language and right to left text, and sound they can mute.

## Guides

- [Sell an item](https://docs.lialabs.org/guides/sell-an-item.md): Sell something in your app for $LIA, end to end. The pay sheet in your page, then confirm and deliver on your server, with nothing lost if the page reloads.
- [Verify on your server](https://docs.lialabs.org/guides/verify-on-your-server.md): Know which player is calling your server. Send a session token from the page, verify it with Lia once, then keep your own session.
- [Handle webhooks](https://docs.lialabs.org/guides/webhooks.md): A complete webhook handler. Check the signature on the raw body, check with the API, act once, and answer quickly.
- [Multiplayer with invites](https://docs.lialabs.org/guides/multiplayer-with-invites.md): A two player room. Create it on your server, invite a friend into it with Lia's friend picker or a link, and land both players in the same room.
- [Reward players](https://docs.lialabs.org/guides/reward-players.md): Pay players in $LIA from your app's reward pool, from your server. A daily bonus as the example, safe to retry and within your limits.
- [Rewarded ads that pay](https://docs.lialabs.org/guides/rewarded-ads.md): Offer a video for a reward, check on your server that it was watched by that player, and pay once per video.
- [Send notifications](https://docs.lialabs.org/guides/send-notifications.md): Ask at the right moment, remember who said yes, send from your server, and open the right screen when a notification is tapped.
- [Leaderboards and saves](https://docs.lialabs.org/guides/scores-and-saves.md): A leaderboard and saved progress without a server of your own. Submit scores, show the top 50, and keep progress in cloud storage so it follows players to any phone.
- [Make it feel like Lia](https://docs.lialabs.org/guides/feel-native.md): A checklist and starter code so your app feels part of Lia. Theme, safe areas, language, buttons, back navigation, haptics and sound.
- [Testing your app](https://docs.lialabs.org/guides/testing.md): Try everything before launch. Testers, test keys and pretend $LIA, running your page from your computer, the SDK demo, and finding problems inside Lia.

## Packages

- [Packages](https://docs.lialabs.org/packages.md): The Lia SDK as npm packages. A typed bridge, a tree-shakeable SDK, and bindings for React, Preact, Vue, Svelte, Solid, Angular and web components.
- [Local development](https://docs.lialabs.org/packages/local-development.md): Build your app in a desktop browser with mockLia(), a pretend Lia that answers every call with a test player. Change its answers, send events, and debug every message.
- [@lia-labs/sdk](https://docs.lialabs.org/packages/sdk.md): The Lia SDK for apps with a build step. Every feature as a typed, tree-shakeable export, with the same checks and error codes as the script tag, and state you can watch.
- [@lia-labs/sdk-react](https://docs.lialabs.org/packages/react.md): React hooks for the Lia SDK. Init, Lia's state as hooks, and Lia's buttons shown while a component is mounted.
- [@lia-labs/sdk-preact](https://docs.lialabs.org/packages/preact.md): Preact hooks for the Lia SDK, with the same names as the React package.
- [@lia-labs/sdk-vue](https://docs.lialabs.org/packages/vue.md): Vue 3 composables for the Lia SDK. Lia's state as read-only refs, and buttons driven by refs or getters.
- [@lia-labs/sdk-svelte](https://docs.lialabs.org/packages/svelte.md): Svelte stores for the Lia SDK, for Svelte 4 and 5. Lia's state as stores, and buttons for a component's life.
- [@lia-labs/sdk-solid](https://docs.lialabs.org/packages/solid.md): Solid primitives for the Lia SDK. Lia's state as accessors, and buttons that live as long as their owner.
- [@lia-labs/sdk-angular](https://docs.lialabs.org/packages/angular.md): Angular signals for the Lia SDK. inject* functions for Lia's state, and buttons that live as long as the component.
- [@lia-labs/elements](https://docs.lialabs.org/packages/elements.md): The Lia SDK as custom elements, for any page and any framework. Put an element on the page and it does its job while it's there.
- [@lia-labs/bridge](https://docs.lialabs.org/packages/bridge.md): The lowest layer. Typed calls and events over Lia's frame bridge, the timeouts and limits, and mockLia() for building outside Lia.

## SDK reference

- [SDK overview](https://docs.lialabs.org/reference/sdk.md): Loading the Lia SDK, the Lia object's properties, how calls answer and fail, and an index of every method.
- [Startup and lifecycle](https://docs.lialabs.org/reference/sdk-lifecycle.md): Lia.init, Lia.ready, Lia.session and Lia.close, and every event Lia sends your page.
- [Payments and ads](https://docs.lialabs.org/reference/sdk-payments-and-ads.md): Lia.pay, Lia.charges and Lia.onCharge for Lia's pay sheet, and Lia.showAd and its shortcuts for full screen ads.
- [Notifications, invites and the lobby](https://docs.lialabs.org/reference/sdk-notifications-and-invites.md): Lia.requestNotifications, Lia.inviteFriend, Lia.inviteLink, Lia.share and Lia.lobby.
- [Dialogs](https://docs.lialabs.org/reference/sdk-dialogs.md): Questions, popups, alerts and toasts in Lia's own style, over your app.
- [Layout, colours and buttons](https://docs.lialabs.org/reference/sdk-layout.md): Expanding and fullscreen, swipes and closing confirmation, Lia's header and background colours, and the bottom, back and settings buttons.
- [Device](https://docs.lialabs.org/reference/sdk-device.md): Haptics, the QR scanner, the clipboard, links, Lia's own screens, Face ID and Touch ID, and the motion sensors.
- [Scores and storage](https://docs.lialabs.org/reference/sdk-scores-and-storage.md): Leaderboards with no server of your own, and three kinds of storage. Cloud storage follows a player to any phone; device and secure storage stay on this one.

## Server reference

- [Server API](https://docs.lialabs.org/reference/server-api.md): The API your app's own server calls with its secret key. Verify sessions, list products, confirm, deliver and refund charges, pay rewards from your pool, send notifications, check ads and list public tables.
- [Webhooks](https://docs.lialabs.org/reference/webhooks.md): Lia tells your server when a charge is paid or refunded and when a reward is paid, signed with your webhook secret. What's sent, how to check the signature, and how retries work.
- [Error codes](https://docs.lialabs.org/reference/errors.md): Every error code from the Lia SDK and the server API, what it means and what to do.

## Updates

- [Changelog](https://docs.lialabs.org/changelog.md): What's new in the Lia SDK and these docs.

## Optional

- [Everything in one file](https://docs.lialabs.org/llms-full.txt)
- [Server API, OpenAPI 3.1](https://docs.lialabs.org/openapi.json)
- [Lia's website](https://lialabs.org)