Skip to main content
The authenticate function initiates the full onboarding flow between your Mini App and the Lemon Cash app. It presents the user with your Mini App’s Terms & Conditions, Privacy Policy, and any claim or permission requests you specify. Once accepted, it authenticates the user using Sign In With Ethereum (SIWE) and returns the user’s wallet address, granted claims, and a signed message that verifies wallet ownership.

​
Important Guidelines

Your Mini App must follow these rules to be approved for publication.
  • Call authenticate as soon as the user enters your Mini App. It must be invoked before any other function (deposit, withdraw, callSmartContract, etc.). During this step, users are presented with the Terms & Conditions, Privacy Policy, and claim permissions.
  • Use authenticate as your login flow. It is the only supported authentication method. If you need the user’s email or other data, request it as a claim via requirements.claims.
  • Call authenticate on every entry. Invoke it each time a user opens your Mini App to ensure the wallet address is always fresh. If your app supports multiple chains, re-trigger authenticate when the user switches chains.

​
Usage

import { authenticate, ChainId, TransactionResult } from '@lemoncash/mini-app-sdk';

export const MiniApp = () => {
  const [wallet, setWallet] = useState<string | undefined>(undefined);

  const handleAuthentication = async () => {
    const result = await authenticate({
      chainId: ChainId.POLYGON_AMOY,
    });
    
    if (result.result === TransactionResult.SUCCESS) {
      setWallet(result.data.wallet);
    }
  };

  useEffect(() => {
    handleAuthentication();
  }, []);
};

​
Parameters

type AuthenticateData = {
  nonce?: string;
  chainId: ChainId;
  requirements?: {
    claims?: ClaimKey[];
  };
}
​
nonce
string
If present, it must be at least 8 alphanumeric characters in length. A unique nonce for the authentication request. This should be generated in your backend and be different for each authentication attempt.
await authenticate({
  nonce: 'l3m0nc45h',
  chainId: ChainId.POLYGON_AMOY,
});
​
chainId
ChainId
required
The chain id to use for the authentication request. This parameter is required.
import { ChainId } from '@lemoncash/mini-app-sdk';

await authenticate({
  chainId: ChainId.POLYGON_AMOY,
});
​
requirements
object
Optional requirements for the authentication request.
​
requirements.claims
ClaimKey[]
An array of claim keys that you want to request from the user. The available claim keys are defined in the ClaimKey enum. See the Types documentation for the complete list of available claim keys.
import { authenticate, ChainId, ClaimKey } from '@lemoncash/mini-app-sdk';

await authenticate({
  chainId: ChainId.POLYGON_AMOY,
  requirements: {
    claims: [ClaimKey.NAME, ClaimKey.EMAIL, ClaimKey.LEMONTAG],
  },
});

​
Returns

type AuthenticateResponse = {
  result: TransactionResult.SUCCESS;
  data: {
    wallet: string;
    grantedClaims: MiniAppGrantedClaim[];
    signature: string;
    message: string;
  };
} | {
  result: TransactionResult.FAILED;
  error: {
    message: string;
    code: string;
  };
} | {
  result: TransactionResult.CANCELLED;
};
​
result
TransactionResult
The result of the authentication attempt.
  • SUCCESS: The authentication was successful.
  • FAILED: The authentication failed.
  • CANCELLED: The authentication was cancelled by the user.
​
data
object
Contains the wallet address, granted claims, signature and message. Only present when the result is SUCCESS.
  • wallet: The wallet address of the authenticated user.
  • grantedClaims: An array of MiniAppGrantedClaim objects containing the claims granted by the user. Each object has a key (the ClaimKey) and a value (the claim’s value). This will contain the claims that were requested in the requirements.claims parameter, if provided.
  • signature: The cryptographic signature proving the user’s authentication.
  • message: The message that was signed by the user’s wallet.
​
error
object
Contains the error details when the authentication fails. Only present when the result is FAILED.
  • message: A human-readable error message describing what went wrong.
  • code: A machine-readable error code for programmatic error handling.

​
Complete Authentication Flow

Backend endpoints The backend is responsible for generating a nonce and verifying the signature. 
import crypto from 'crypto';

// Generate a cryptographically secure nonce
async function generateNonce(): Promise<string> {
  // Generate 32 random bytes and convert to hex
  const nonce = crypto.randomBytes(32).toString('hex');
  
  // TODO: Store the nonce in your database with:
  // - timestamp for expiration
  // - used flag to prevent replay attacks
  // - user identifier
  
  return nonce;
}

app.post('/api/auth/nonce', async (req, res) => {
    const nonce = await generateNonce();
    res.json({ nonce });
});
Frontend React component: 
import React, { useState, useEffect } from 'react';
import { authenticate, ChainId, TransactionResult } from '@lemoncash/mini-app-sdk';
import { getNonceFromBackend, verifySignatureOnBackend } from './api';

export const MiniApp: React.FC = () => {
  const [wallet, setWallet] = useState<string | undefined>(undefined);

  const handleAuthenticate = async () => {    
    // 1. Get a unique nonce from your backend
    const nonce = await getNonceFromBackend();
    
    // 2. Request the signature using the nonce
    const result = await authenticate({ 
      nonce, 
      chainId: ChainId.POLYGON_AMOY 
    });
    
    if (result.result === TransactionResult.FAILED) {
      throw new Error(`Authentication failed: ${result.error.message} (${result.error.code})`);
    }
    
    if (result.result === TransactionResult.CANCELLED) {
      throw new Error('Authentication was cancelled by the user');
    }
    
    const { wallet, signature, message } = result.data;
    
    // 3. Verify the signature on your backend
    const verificationResult = await verifySignatureOnBackend({
      wallet,
      signature,
      message,
      nonce,
    });
    
    if (verificationResult.verified) {
      setWallet(wallet);
    }
  };

  // Trigger authentication on component mount
  useEffect(() => {
    handleAuthenticate();
  }, []);

  return (
    <div>
      <h2>Wallet</h2>
      <p>
        Connected: {wallet ? '✅ Connected' : '❌ Not connected'}
      </p>
      
      {wallet && (
        <p>
          {wallet}
        </p>
      )}
    </div>
  );
};

​
ERC-6492 Support

The smart contract wallet is deployed on the first user’s transaction. The authenticate method supports ERC-6492 for contract wallets that are not yet deployed. This means users can authenticate even before their wallet contract is deployed.

deposit

Deposit funds to your Mini App Wallet.

Call Smart Contract

Interact with smart contracts on the blockchain.