User ID: {auth.tokenInfo?.sub}
Expires: {new Date(auth.tokenInfo.exp * 1000).toLocaleString()}
Scan with Alien App
User ID: {auth.tokenInfo?.sub}
Issuer: {auth.tokenInfo?.iss}
Expires: {new Date(auth.tokenInfo!.exp * 1000).toLocaleString()}
Welcome, {session.user?.name}
User ID: {session.user?.id}
Welcome! User ID: {auth.tokenInfo?.sub}
Wallet: {wallet.publicKey?.toBase58()}
Session: {auth.sessionAddress}
Session: {auth.sessionAddress}
Session: {auth.sessionAddress}
Payments not supported in this environment
; } return ( ); } ``` ## Hook Options | Option | Type | Default | Description | | --- | --- | --- | --- | | `timeout` | `number` | `120000` | Payment timeout in ms (2 min) | | `onPaid` | `(txHash: string) => void` | - | Called on success | | `onCancelled` | `() => void` | - | Called on user cancel | | `onFailed` | `(code, error?) => void` | - | Called on failure | | `onStatusChange` | `(status) => void` | - | Called on any change | ## Hook Return Values | Value | Type | Description | | --- | --- | --- | | `pay` | `(params) => PromiseTransaction: {txHash}
Error: {errorCode}
Status: {status}
; } ``` ## Complete Example A full purchase flow with invoice creation, payment, and webhook handling. ### Frontend (React) ```tsx function BuyButton({ product }) { const { authToken } = useAlien(); const payment = usePayment({ onPaid: (txHash) => console.log('Paid!', txHash), onCancelled: () => console.log('Cancelled'), onFailed: (code) => console.log('Failed:', code), }); const handlePurchase = useCallback(async () => { if (!authToken) return; // 1. Create invoice on your backend const res = await fetch('/api/invoices', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${authToken}`, }, body: JSON.stringify({ recipientAddress: product.recipientAddress, amount: product.amount, token: product.token, network: product.network, productId: product.id, }), }); const { invoice } = await res.json(); // 2. Open payment UI await payment.pay({ recipient: product.recipientAddress, amount: product.amount, token: product.token, network: product.network, invoice, item: { title: product.name, iconUrl: product.iconUrl, quantity: product.quantity, }, }); }, [authToken, payment, product]); if (!payment.supported) { returnPayments not available
; } return ( ); } ``` ### Backend Invoice Route Example using Next.js App Router (adapt to your framework). This route authenticates the user, validates the request body, verifies the product parameters match your catalog, and creates a payment intent: ```typescript const authClient = createAuthClient(); function extractBearerToken( header: string | null, ): string | null { return header?.startsWith('Bearer ') ? header.slice(7) : null; } try { const token = extractBearerToken( request.headers.get('Authorization'), ); if (!token) { return NextResponse.json( { error: 'Missing authorization token' }, { status: 401 }, ); } // Verify JWT — `sub` is the user's Alien ID const { sub } = await authClient.verifyToken(token); const body = await request.json(); const { recipientAddress, amount, token: paymentToken, network, productId, } = body; // Validate that the product parameters match your catalog // to prevent clients from sending arbitrary amounts const product = PRODUCTS.find((p) => p.id === productId); if ( !product || product.amount !== amount || product.token !== paymentToken || product.network !== network || product.recipientAddress !== recipientAddress ) { return NextResponse.json( { error: 'Invalid product parameters' }, { status: 400 }, ); } // Any unique string under 64 bytes const invoice = randomUUID(); // Save payment intent to your database await db.paymentIntents.create({ invoice, senderAlienId: sub, recipientAddress, amount, token: paymentToken, network, productId, status: 'pending', }); return NextResponse.json({ invoice }); } catch (error) { if (error instanceof JwtErrors.JWTExpired) { return NextResponse.json( { error: 'Token expired' }, { status: 401 }, ); } if (error instanceof JwtErrors.JOSEError) { return NextResponse.json( { error: 'Invalid token' }, { status: 401 }, ); } console.error('Failed to create invoice:', error); return NextResponse.json( { error: 'Failed to create invoice' }, { status: 500 }, ); } } ``` > **Important:** Always validate that the product parameters (amount, > token, network, recipient) match your server-side product catalog. > Never trust client-submitted amounts directly. ## Next Steps - [Install Boilerplate](/quickstart/install-boilerplate) — Pre-configured template - [Authentication](/react-sdk/auth) — Authenticate users before checkout - [Developer Portal](https://dev.alien.org/) — Configure webhooks --- # Authentication Authenticate users in your Alien mini app. The host app provides a JWT token that identifies the user, which you can verify on your backend. ## How It Works ```mermaid sequenceDiagram participant Host as Alien App (Host) participant Mini as Your Mini App participant Backend as Your Backend Host->>Mini: 1. Injects JWT via window globals Note over Mini: 2. useAlien() reads token Mini->>Backend: 3. Authorization: BearerOpen this app inside Alien to authenticate.
; } if (!authToken) { returnLoading...
; } returnAuthenticated
; } ``` **Available context values:** | Property | Type | Description | | --- | --- | --- | | `authToken` | `string \| undefined` | JWT token from the host app | | `isBridgeAvailable` | `boolean` | `true` if running inside Alien app | | `contractVersion` | `Version \| undefined` | SDK protocol version | | `ready` | `() => void` | Signal the host app that the miniapp is ready | The `ready` function is only needed when `autoReady` is `false`. ### Using Launch Parameters For additional context about the launch environment, use `useLaunchParams`: ```tsx function App() { const launchParams = useLaunchParams(); if (!launchParams) { returnPlease open this app inside Alien.
; } if (error) { returnError: {error}
; } if (!user) { returnLoading...
; } returnAlien ID: {user.alienId}
; } function App() { return (