Get started

Build with AI

Copy page

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.

These docs are written to be read by people and by AI tools alike. Point your assistant (Claude, ChatGPT, Cursor, Copilot, Claude Code or any other) at the files below, and add the rules file to your project, so it writes Lia code the right way first time.

#For your assistant

What	Where	Use it for
A map of the docs	`/llms.txt`	The essentials and every page, with links to its Markdown. Start here.
All of the docs in one file	`/llms-full.txt`	Paste or attach it when your tool can't browse.
Any page as Markdown	Add `.md` to its address, like `/concepts/payments.md`	One topic at a time. Every page's Copy page menu does this too.
The server API as OpenAPI 3.1	`/openapi.json`	Generating a typed client, or letting an agent call the API correctly.
A rules file for your project	`/AGENTS.md`	Below: the rules that matter most, in a file assistants read.
TypeScript types	`npm install @lia-labs/sdk`	Every method's params and answers, every event's data.

#Copy page

Every page has a Copy page menu next to its title:

Copy as Markdown puts the page on your clipboard, ready to paste into a chat.
View as Markdown opens its Markdown.
Open in Claude and Open in ChatGPT start a chat that reads the page.

#Add the rules to your project

Save this as AGENTS.md in your project (or CLAUDE.md for Claude Code, or a rule in .cursor/rules/). Assistants read it before they write code, so they follow Lia's rules without being told each time. It's also at /AGENTS.md.

AGENTS.md

# Building a Lia app

This is a web app that runs inside the Lia app (lialabs.org), like a Telegram mini app. Docs: https://docs.lialabs.org (every page as Markdown: add .md; everything: https://docs.lialabs.org/llms-full.txt).

## The SDK
- 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.

## Trust
- 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.

## Payments
- 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).

## Rewards, ads, notifications
- 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.

## Feel like Lia
- 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).

## Conventions
- In text people read: "$LIA" for the token, "LIA" next to numbers (5 LIA).
- Retry server POSTs with the same Idempotency-Key header.

#Ask good questions

A few prompts that work well with the files above:

"Read https://docs.lialabs.org/llms.txt, then build a Lia app in React where players buy extra lives for 5 LIA, with a Node server that verifies and delivers the charge."
"Using https://docs.lialabs.org/openapi.json, write a typed client for the Lia server API in TypeScript with retries and Idempotency-Key headers."
"Read https://docs.lialabs.org/guides/multiplayer-with-invites.md and add public tables to my two player game."

#If something's wrong

AI tools can still get things wrong. The SDK reference and server API are the source of truth, and Testing your app shows how to check everything before you go live.