> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flutter SDK API

> Complete API reference for the Para Flutter SDK, including authentication, wallet management, and blockchain operations.

## Para Class

The `Para` class is the main entry point for the Para Flutter SDK, providing wallet operations, authentication, and blockchain interactions. The latest version includes passkey authentication, comprehensive multi-chain support, and deep linking capabilities.

### Constructor

<ResponseField name="Para.fromConfig()" type="Constructor">
  Creates a new Para SDK instance using the configuration factory constructor.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="config" type="ParaConfig" required>
      Configuration object containing environment and API key.
    </ResponseField>

    <ResponseField name="appScheme" type="String" required>
      Your app's deep link scheme (e.g., "yourapp").
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final para = Para.fromConfig(
    config: ParaConfig(
      environment: Environment.beta,
      apiKey: 'YOUR_API_KEY',
      jsBridgeUri: Uri.parse('custom-bridge-url'), // Optional
      relyingPartyId: 'custom.domain.com',         // Optional
    ),
    appScheme: 'yourapp',
  );
  ```
</ResponseField>

### Authentication Methods

<ResponseField name="initiateAuthFlow()" type="Future<AuthState>">
  Initiates authentication flow for email or phone. Returns an `AuthState` indicating next steps.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="auth" type="Auth" required>
      Authentication object using `Auth.email()` or `Auth.phone()` helper methods.
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  // Email authentication
  final authState = await para.initiateAuthFlow(
    auth: Auth.email('user@example.com')
  );

  // Phone authentication
  final authState = await para.initiateAuthFlow(
    auth: Auth.phone('+1234567890')
  );
  ```
</ResponseField>

<ResponseField name="verifyOtp()" type="Future<AuthState>">
  Verifies the OTP code sent to email/phone during authentication.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="otp" type="String" required>
      The 6-digit OTP verification code.
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final verifiedState = await para.verifyOtp(
    otp: '123456'
  );
  ```
</ResponseField>

<ResponseField name="handleLogin()" type="Future<Wallet>">
  Handles login for existing users with passkey authentication.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="authState" type="AuthState" required>
      The auth state returned from `initiateAuthFlow()` for existing users.
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final wallet = await para.handleLogin(
    authState: authState,
  );
  ```
</ResponseField>

<ResponseField name="handleSignup()" type="Future<Wallet>">
  Handles the complete signup flow for new users, including passkey creation and wallet setup.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="authState" type="AuthState" required>
      The auth state returned from `verifyOtp()` for new users.
    </ResponseField>

    <ResponseField name="method" type="SignupMethod" required>
      The signup method to use: `SignupMethod.passkey`.
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final wallet = await para.handleSignup(
    authState: authState,
    method: SignupMethod.passkey,
  );
  ```
</ResponseField>

<ResponseField name="verifyOAuth()" type="Future<AuthState>">
  Handles complete OAuth authentication flow using an external browser.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="provider" type="OAuthMethod" required>
      OAuth provider: `OAuthMethod.google`, `.twitter`, `.apple`, `.discord`, or `.facebook`.
    </ResponseField>

    <ResponseField name="appScheme" type="String" required>
      Your app's deep link scheme for OAuth callback (e.g., 'yourapp').
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final authState = await para.verifyOAuth(
    provider: OAuthMethod.google,
    appScheme: 'yourapp',
  );
  ```
</ResponseField>

### Wallet Management

<ResponseField name="createWallet()" type="ParaFuture<Wallet>">
  Creates a new wallet with enhanced multi-chain support. Returns a `ParaFuture` that can be cancelled.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="type" type="WalletType" optional>
      The type of wallet to create: `WalletType.evm`, `.solana`, or `.cosmos` (default: `WalletType.evm`).
    </ResponseField>

    <ResponseField name="skipDistribute" type="bool" required>
      Whether to skip the distributed backup process.
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final walletFuture = para.createWallet(
    type: WalletType.evm,
    skipDistribute: false,
  );

  final wallet = await walletFuture.future;
  // Or cancel: await para.cancelOperationById(walletFuture.requestId);
  ```
</ResponseField>

<ResponseField name="fetchWallets()" type="ParaFuture<List<Wallet>>">
  Retrieves all wallets for the current user.

  ```dart theme={null}
  final walletsFuture = para.fetchWallets();
  final wallets = await walletsFuture.future;
  ```
</ResponseField>

### Signing Operations

<ResponseField name="signMessage()" type="ParaFuture<SignatureResult>">
  Signs a message with the specified wallet. Returns a cancellable `ParaFuture`.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="walletId" type="String" required>
      The wallet ID to use for signing.
    </ResponseField>

    <ResponseField name="messageBase64" type="String" required>
      The message to sign, base64-encoded.
    </ResponseField>

    <ResponseField name="timeoutMs" type="int?" optional>
      Optional timeout in milliseconds (default: 30000).
    </ResponseField>

    <ResponseField name="cosmosSignDocBase64" type="String?" optional>
      For Cosmos signing: The SignDoc as base64-encoded JSON. When provided, this method signs a Cosmos transaction instead of a generic message.
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  // Generic message signing
  final signatureFuture = para.signMessage(
    walletId: wallet.id,
    messageBase64: base64Encode(utf8.encode('Hello, Para!')),
  );

  final signature = await signatureFuture.future;

  // Cosmos transaction signing
  final cosmosSignature = await para.signMessage(
    walletId: cosmosWallet.id,
    messageBase64: '', // Not used for Cosmos
    cosmosSignDocBase64: base64Encode(utf8.encode(jsonEncode(signDoc))),
  ).future;
  ```
</ResponseField>

<ResponseField name="signTransaction()" type="ParaFuture<SignatureResult>">
  Signs an EVM transaction. Returns a cancellable `ParaFuture`.

  <Note>
    This method is for EVM transactions only. For Solana, use `signMessage()` with the serialized transaction as `messageBase64`. For Cosmos, use `signMessage()` with `cosmosSignDocBase64`.

    **EVM Transaction Return Value**: The `SuccessfulSignatureResult` contains the complete RLP-encoded transaction ready for broadcasting via the `signedTransaction` property.

    **Solana/Cosmos Return Value**: For pre-serialized transactions, returns just the signature in `signedTransaction`. For constructed transactions, returns the complete signed transaction.
  </Note>

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="walletId" type="String" required>
      The wallet ID to use for signing.
    </ResponseField>

    <ResponseField name="rlpEncodedTxBase64" type="String" required>
      RLP-encoded EVM transaction (base64).
    </ResponseField>

    <ResponseField name="chainId" type="String" required>
      Chain ID of the EVM network.
    </ResponseField>

    <ResponseField name="timeoutMs" type="int?" optional>
      Optional timeout in milliseconds (default: 30000).
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  // EVM transaction signing
  final signatureFuture = para.signTransaction(
    walletId: evmWallet.id,
    rlpEncodedTxBase64: base64Encode(rlpEncodedTx),
    chainId: '1', // Ethereum mainnet
  );

  final signature = await signatureFuture.future;
  ```
</ResponseField>

<ResponseField name="cancelOperationById()" type="Future<void>">
  Cancels an ongoing operation by its request ID.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="requestId" type="String" required>
      The request ID from a `ParaFuture`.
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final signatureFuture = para.signMessage(...);
  // Cancel the operation
  await para.cancelOperationById(signatureFuture.requestId);
  ```
</ResponseField>

### Session Management

<ResponseField name="isSessionActive()" type="ParaFuture<bool>">
  Checks if there's an active user session.

  ```dart theme={null}
  final isActive = await para.isSessionActive();
  ```
</ResponseField>

<ResponseField name="exportSession()" type="ParaFuture<String>">
  Exports the current session as an encrypted string.

  ```dart theme={null}
  final sessionData = await para.exportSession();
  // Save sessionData securely
  ```
</ResponseField>

<ResponseField name="logout()" type="ParaFuture<void>">
  Logs out the current user and clears session data.

  ```dart theme={null}
  await para.logout();
  ```
</ResponseField>

### Utility Methods

<ResponseField name="currentUser()" type="ParaFuture<ParaUser>">
  Gets the current user's basic profile and session status.

  ```dart theme={null}
  final user = await para.currentUser();
  if (user.isLoggedIn) {
    debugPrint('Logged in as ${user.userId}');
  }
  ```
</ResponseField>

<ResponseField name="getLoginUrl()" type="ParaFuture<String>">
  Returns a browser URL for One-Click (BASIC\_LOGIN) authentication.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="authMethod" type="String" required>
      Login method identifier (e.g., `BASIC_LOGIN`).
    </ResponseField>

    <ResponseField name="shorten" type="bool?" optional>
      Request a shortened URL.
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final loginUrl = await para.getLoginUrl(authMethod: 'BASIC_LOGIN');
  ```
</ResponseField>

<ResponseField name="presentAuthUrl()" type="Future<Uri?>">
  Presents an auth URL in a secure system web view and returns the callback URI (if any).

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="url" type="String" required>
      The authentication URL to open.
    </ResponseField>

    <ResponseField name="webAuthenticationSession" type="ParaWebAuthenticationSession" required>
      Platform-specific web authentication session.
    </ResponseField>

    <ResponseField name="context" type="String" optional>
      Descriptive label for logging (default: `authentication`).
    </ResponseField>

    <ResponseField name="loadTransmissionKeyshares" type="bool" optional>
      Whether to preload signing keyshares after completion.
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final callback = await para.presentAuthUrl(
    url: loginUrl,
    webAuthenticationSession: webAuthSession,
    context: 'One-Click login',
    loadTransmissionKeyshares: true,
  );
  ```
</ResponseField>

<ResponseField name="waitForLogin()" type="ParaFuture<Map<String, dynamic>>">
  Waits for an ongoing login operation to complete.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="isCanceled" type="Function()?" optional>
      Optional function to check if operation is canceled.
    </ResponseField>

    <ResponseField name="pollingIntervalMs" type="int" optional>
      Polling interval in milliseconds (default: 2000).
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final result = await para.waitForLogin(pollingIntervalMs: 1000);
  ```
</ResponseField>

<ResponseField name="waitForSignup()" type="ParaFuture<bool>">
  Polls for completion of a pending One-Click signup.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="timeoutMs" type="int?" optional>
      Optional timeout in milliseconds (default: no timeout).
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final completed = await para.waitForSignup(timeoutMs: 300000);
  ```
</ResponseField>

<ResponseField name="waitForWalletCreation()" type="ParaFuture<Map<String, dynamic>>">
  Waits for wallet creation to complete after signup.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="isCanceled" type="Function()?" optional>
      Optional function to check if operation is canceled.
    </ResponseField>

    <ResponseField name="pollingIntervalMs" type="int" optional>
      Polling interval in milliseconds (default: 2000).
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final result = await para.waitForWalletCreation(pollingIntervalMs: 1000);
  ```
</ResponseField>

<ResponseField name="touchSession()" type="ParaFuture<Map<String, dynamic>?>">
  Refreshes the current session metadata and returns the latest snapshot (or `null` if nothing changed).

  ```dart theme={null}
  final snapshot = await para.touchSession();
  if (snapshot != null) {
    debugPrint('Session touched at ${snapshot['updatedAt']}');
  }
  ```
</ResponseField>

<ResponseField name="formatPhoneNumber()" type="String?">
  Formats a phone number for authentication.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="phoneNumber" type="String" required>
      The phone number to format.
    </ResponseField>

    <ResponseField name="countryCode" type="String" required>
      The country code (e.g., '1' for US, '44' for UK).
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  final formatted = para.formatPhoneNumber('1234567890', '1');
  // Returns: '+11234567890' (exact format depends on implementation)
  ```
</ResponseField>

<ResponseField name="isUsingExternalWallet()" type="ParaFuture<bool>">
  Checks if the current user is using an external wallet.

  ```dart theme={null}
  final isExternal = await para.isUsingExternalWallet();
  ```
</ResponseField>

<ResponseField name="clearStorage()" type="ParaFuture<void>">
  Clears local storage data.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="keepSecretKey" type="bool" required>
      Whether to keep the Paillier secret key (default: false).
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  await para.clearStorage(false);
  ```
</ResponseField>

<ResponseField name="dispose()" type="void">
  Disposes of SDK resources. Call when the SDK is no longer needed.

  ```dart theme={null}
  para.dispose();
  ```
</ResponseField>

## Extension Methods

Para provides extension methods for cleaner authentication flows (requires importing extensions):

```dart theme={null}
import 'package:para/src/auth_extensions.dart';
```

### ParaAuthExtensions

<ResponseField name="initiateAuthFlow()" type="Future<AuthState>">
  Initiates authentication and returns the current state using `Auth` helper class.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="auth" type="Auth" required>
      Authentication method: `Auth.email()` or `Auth.phone()`.
    </ResponseField>
  </Expandable>

  ```dart theme={null}
  // Must import extensions
  import 'package:para/src/auth_extensions.dart';

  final authState = await para.initiateAuthFlow(
    auth: Auth.email('user@example.com')
  );
  ```
</ResponseField>

<ResponseField name="presentPasswordUrl()" type="Future<Uri?>">
  Presents a password authentication URL in a secure web view.

  <Expandable title="Parameters" defaultOpen="true">
    <ResponseField name="url" type="String" required>
      The password authentication URL.
    </ResponseField>

    <ResponseField name="webAuthenticationSession" type="WebAuthenticationSession" required>
      Web authentication session for handling the flow.
    </ResponseField>
  </Expandable>
</ResponseField>

## Types and Enums

### Environment

```dart theme={null}
enum Environment {
  dev,      // Development environment
  beta,     // Beta environment
  prod      // Production environment
}
```

### Auth

```dart theme={null}
class Auth {
  static AuthEmail email(String email);
  static AuthPhone phone(String phoneNumber);
}
```

### AuthState

```dart theme={null}
class AuthState {
  final AuthStage stage;           // Current authentication stage
  final String? userId;            // User's unique identifier
  final AuthIdentity auth;         // Authentication identity details
  final String? displayName;       // User's display name
  final String? pfpUrl;           // Profile picture URL
  final String? username;         // Username
  final Map<String, dynamic>? externalWallet; // External wallet info
  final String? loginUrl;         // One-Click URL, when provided
  final List<String>? loginAuthMethods;   // Advertised login methods (e.g., BASIC_LOGIN)
  final List<String>? signupAuthMethods;  // Advertised signup methods
  final String? passkeyUrl;       // URL for passkey authentication
  final String? passkeyId;        // Passkey identifier
  final String? passwordUrl;      // URL for password authentication
  final AuthStage? nextStage;     // Optional next stage hint

  // Helper getters exposed by the SDK:
  bool get hasSloUrl;             // loginUrl is non-empty
  List<String> get loginMethods;  // loginAuthMethods ?? []
  List<String> get signupMethods; // signupAuthMethods ?? []
  AuthStage get effectiveNextStage; // nextStage ?? stage
}

class AuthIdentity {
  final String? email;
  final String? phoneNumber;
  final String? fid;              // Farcaster ID
  final String? telegramUserId;
  // Other identity types
}

enum AuthStage {
  verify,  // Need to verify email/phone
  login,   // Existing user, proceed to login
  signup   // New user, proceed to signup
}
```

### SignupMethod

```dart theme={null}
enum SignupMethod {
  passkey,  // Hardware-backed passkey
  password  // Password-based authentication
}
```

### OAuthMethod

```dart theme={null}
enum OAuthMethod {
  google,
  twitter,
  apple,
  discord,
  facebook
}
```

### WalletType

```dart theme={null}
enum WalletType {
  evm,     // Ethereum and EVM-compatible chains
  solana,  // Solana blockchain
  cosmos   // Cosmos-based chains
}
```

### ParaFuture

```dart theme={null}
class ParaFuture<T> {
  final Future<T> future;    // The actual future
  final String requestId;    // ID for cancellation
}
```

### Wallet

```dart theme={null}
class Wallet {
  final String id;
  final String address;
  final WalletType type;
  final WalletScheme scheme;
  final String? userId;         // Associated user ID
  final DateTime? createdAt;    // Creation timestamp
  final String? publicKey;      // Wallet public key
  final bool? isPregen;         // Whether this is a pregenerated wallet
  // Additional optional fields available
}
```

### SignatureResult

```dart theme={null}
// Abstract base class
abstract class SignatureResult {}

// Successful signature
class SuccessfulSignatureResult extends SignatureResult {
  final String signedTransaction;  // For transactions: complete signed transaction ready for broadcasting
                                   // For messages: just the signature

  SuccessfulSignatureResult(this.signedTransaction);

  /// Gets the transaction data ready for broadcasting.
  String get transactionData => signedTransaction;
}

// Denied signature
class DeniedSignatureResult extends SignatureResult {
  final String? pendingTransactionId;
  DeniedSignatureResult(this.pendingTransactionId);
}

// Denied with URL
class DeniedSignatureResultWithUrl extends SignatureResult {
  final String? pendingTransactionId;
  final String url;
  DeniedSignatureResultWithUrl({this.pendingTransactionId, required this.url});
}
```