Install Boilerplate

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

Prerequisites

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

Clone the Repository


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

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
├── 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
│   └── navigation/
│       └── components/
│           └── tab-bar.tsx
├── lib/
│   ├── db/
│   │   ├── index.ts
│   │   └── schema.ts
│   └── env.ts
├── drizzle/
├── scripts/
│   └── migrate.ts
├── docker-compose.yml
├── .env.example
└── package.json

Environment Variables

Copy the template and fill in your values:


cp .env.example .env

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`WEBHOOK_PUBLIC_KEY`	Ed25519 public key (hex) for webhooks
`NEXT_PUBLIC_RECIPIENT_ADDRESS`	Solana wallet for USDC payments
`NEXT_PUBLIC_ALIEN_RECIPIENT_ADDRESS`	Alien provider address

Default .env for local development:


DATABASE_URL=postgresql://postgres:postgres@localhost:5432/miniapp
WEBHOOK_PUBLIC_KEY=<your-webhook-public-key>
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 payments will be sent.
NEXT_PUBLIC_ALIEN_RECIPIENT_ADDRESS — your provider address from the Alien Dev Portal . Found on the Webhooks or Mini Apps pages.
WEBHOOK_PUBLIC_KEY — the Ed25519 public key (hex-encoded) provided by the Dev Portal when you register a webhook. Copy it immediately after creation — it is only shown once.

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

Package	Purpose
`@alien_org/react`	React hooks and context provider
`@alien_org/auth-client`	JWT verification for backend
`drizzle-orm`	Type-safe database ORM
`next`	React framework (v16)
`@tanstack/react-query`	Data fetching and caching
`zod`	Schema validation for API payloads
`tailwindcss`	Utility-first CSS

Database

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

Schema

Users (users):

Column	Type	Description
`id`	UUID	Auto-generated primary key
`alienId`	TEXT (unique)	User’s Alien ID from JWT `sub`
`createdAt`	TIMESTAMP	Set on first auth
`updatedAt`	TIMESTAMP	Updated on each auth

Payment Intents (payment_intents):

Column	Type	Description
`id`	UUID	Auto-generated primary key
`invoice`	TEXT (unique)	Invoice identifier
`senderAlienId`	TEXT	Payer’s Alien ID
`recipientAddress`	TEXT	Recipient wallet address
`amount`	TEXT	Amount in smallest units
`token`	TEXT	Token type (`USDC` / `ALIEN`)
`network`	TEXT	Network (`solana` / `alien`)
`productId`	TEXT	Product identifier
`status`	TEXT	`pending` / `completed` / `failed`
`createdAt`	TIMESTAMP	Set on creation

Transactions (transactions):

Column	Type	Description
`id`	UUID	Auto-generated primary key
`senderAlienId`	TEXT	Payer’s Alien ID
`recipientAddress`	TEXT	Recipient wallet address
`txHash`	TEXT	On-chain transaction hash
`status`	TEXT	`paid` / `failed`
`amount`	TEXT	Payment amount
`token`	TEXT	Token type
`network`	TEXT	Network
`invoice`	TEXT	Associated invoice
`test`	TEXT	`"true"` if test transaction
`payload`	JSONB	Full webhook payload for audit
`createdAt`	TIMESTAMP	Set on creation

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.

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:


{
  "recipientAddress": "wallet-or-provider-address",
  "amount": "10000",
  "token": "USDC",
  "network": "solana",
  "productId": "usdc-diamonds-10"
}

Response:


{
  "invoice": "inv-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "id": "uuid"
}

`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. Verifies the x-webhook-signature header using Ed25519 against WEBHOOK_PUBLIC_KEY. See Payments — Webhook Setup for details.

Deployment

Set up a PostgreSQL database and configure DATABASE_URL
Register a webhook in the Alien Dev Portal pointing to https://<your-domain>/api/webhooks/payment
Set WEBHOOK_PUBLIC_KEY, NEXT_PUBLIC_RECIPIENT_ADDRESS, and NEXT_PUBLIC_ALIEN_RECIPIENT_ADDRESS
Either run bun run db:migrate manually or set RUN_MIGRATIONS=true for auto-migration on start
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