Install the Alien Mini App Boilerplate

Get started with the Alien Mini App boilerplate. This template includes authentication, payments, database, and the Alien SDK pre-configured.

Mini App Boilerplate Requirements

• Bun  runtime installed
• Docker  for local PostgreSQL
• An Alien account with a Mini App registered in the Dev Portal

Clone and Install the Repository

git clone https://github.com/alien-id/miniapp-boilerplate my-miniapp
cd my-miniapp

The boilerplate ships the v2 @alien-id/miniapps-* SDK packages — the same surface documented in the React SDK reference pages.

Install Dependencies

bun install

Project Structure

my-miniapp/
├── app/
│   ├── api/
│   │   ├── me/route.ts
│   │   ├── invoices/route.ts
│   │   ├── transactions/route.ts
│   │   └── webhooks/payment/route.ts
│   ├── store/page.tsx
│   ├── profile/page.tsx
│   ├── explore/page.tsx
│   ├── layout.tsx
│   ├── page.tsx
│   ├── providers.tsx
│   ├── error.tsx
│   └── global-error.tsx
├── components/
│   └── ui/
│       └── card.tsx
├── features/
│   ├── auth/
│   │   ├── components/
│   │   │   └── connection-status.tsx
│   │   └── lib.ts
│   ├── user/
│   │   ├── components/
│   │   │   └── user-info.tsx
│   │   ├── dto.ts
│   │   ├── hooks/
│   │   │   └── use-current-user.ts
│   │   └── queries.ts
│   ├── payments/
│   │   ├── components/
│   │   │   └── diamond-store.tsx
│   │   ├── hooks/
│   │   │   └── use-diamond-purchase.ts
│   │   ├── constants.ts
│   │   ├── dto.ts
│   │   └── queries.ts
│   ├── sdk-showcase/
│   │   └── components/
│   │       ├── capabilities-card.tsx
│   │       ├── clipboard-card.tsx
│   │       ├── haptics-card.tsx
│   │       ├── host-actions-card.tsx
│   │       └── launch-params-card.tsx
│   ├── navigation/
│   │   └── components/
│   │       ├── tab-bar.tsx
│   │       └── native-back-button.tsx
│   └── debug/
│       └── eruda.tsx
├── lib/
│   ├── api/
│   │   ├── client.ts
│   │   └── with-auth.ts
│   ├── db/
│   │   ├── index.ts
│   │   └── schema.ts
│   └── env.ts
├── drizzle/
├── scripts/
│   └── migrate.ts
├── instrumentation.ts
├── drizzle.config.ts
├── next.config.ts
├── docker-compose.yml
├── .env.example
└── package.json

Configure Environment Variables

Copy the template and fill in your values:

cp .env.example .env

Default .env for local development:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/miniapp
WEBHOOK_PUBLIC_KEY=<your-webhook-public-key>
ALIEN_AUDIENCE=<your-provider-address>
ALIEN_JWKS_URL=https://sso.alien-api.com/oauth/jwks
NEXT_PUBLIC_RECIPIENT_ADDRESS=<your-solana-wallet>
NEXT_PUBLIC_ALIEN_RECIPIENT_ADDRESS=<your-alien-provider-address>
NODE_ENV=development

Where to get the values

• NEXT_PUBLIC_RECIPIENT_ADDRESS — any Solana wallet address you control. This is where USDC and SOL payments will be sent.
• NEXT_PUBLIC_ALIEN_RECIPIENT_ADDRESS — your provider address from the Developer Portal . Found on the Mini Apps and Webhooks pages. ALIEN token payments always go to your provider address.
• ALIEN_AUDIENCE — the expected aud claim of incoming auth tokens. This is the same provider address as above.
• WEBHOOK_PUBLIC_KEY — the Ed25519 public key (hex-encoded) provided by the Developer Portal when you register a webhook. Copy it immediately after creation — it is only shown once.
• ALIEN_JWKS_URL — the JWKS endpoint used to verify SSO access tokens. The default targets Alien production SSO (https://sso.alien-api.com/oauth/jwks); override it for other environments.

Start the Database

docker compose up -d

Run Migrations

bun run db:migrate

Start Development Server

bun run dev

Open http://localhost:3000  to see the app.

What’s Included

Database

PostgreSQL with Drizzle ORM. Local setup uses Docker (docker-compose.yml).

Schema

Users (users):

Payment Intents (payment_intents):

Transactions (transactions):

Commands

bun run db:generate   # Generate migration from schema
bun run db:migrate    # Apply pending migrations
bun run db:push       # Push schema directly (dev only)
bun run db:studio     # Open Drizzle Studio GUI

To run migrations automatically on server start, set RUN_MIGRATIONS=true (handled by the instrumentation.ts hook). Disabled by default.

API Endpoints

GET /api/me

Returns the authenticated user. Requires Bearer token.

{
  "id": "uuid",
  "alienId": "user-alien-id",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

POST /api/invoices

Creates a payment intent. Requires Bearer token.

Request body: only productId is accepted (it must match an id in the product catalog). The recipient, amount, token, and network are derived server-side from the catalog entry.

{
  "productId": "usdc-diamonds-10"
}

Response:

{
  "invoice": "inv-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "id": "uuid",
  "recipient": "wallet-or-provider-address",
  "amount": "10000",
  "token": "USDC",
  "network": "solana",
  "item": {
    "title": "10 Diamonds",
    "iconUrl": "https://.../diamond.png",
    "quantity": 10
  }
}

test is present only for test-scenario products.

GET /api/transactions

Returns the authenticated user’s transaction history. Requires Bearer token.

POST /api/webhooks/payment

Receives payment status updates from the Alien platform, implementing the version 3 webhook contract: Ed25519 signature verification against WEBHOOK_PUBLIC_KEY, an X-Webhook-Version check, and payload cross-validation against the stored payment intent. Re-delivered webhooks for settled intents are acknowledged without reprocessing.

Deployment

The boilerplate is designed to deploy on Vercel  — any Next.js-capable host works:

1. Push your code to GitHub and import the repository on Vercel
2. Add a PostgreSQL database (Vercel Postgres, Neon, Supabase, or any external provider) and set DATABASE_URL
3. Register a webhook in the Developer Portal pointing to https://<your-domain>/api/webhooks/payment
4. Set WEBHOOK_PUBLIC_KEY, ALIEN_AUDIENCE, NEXT_PUBLIC_RECIPIENT_ADDRESS, and NEXT_PUBLIC_ALIEN_RECIPIENT_ADDRESS
5. Either run bun run db:migrate manually or set RUN_MIGRATIONS=true to migrate on server start
6. Deploy

Next Steps

• Create Mini App — Register in the Dev Portal
• Testing — Test locally and in the Alien app
• Authentication — Learn how auth works
• Payments — Accept payments