Aptos Wallet Integration Guide

·

Integrating your decentralized application (dApp) with the Aptos blockchain requires seamless interaction between your front-end and a compatible wallet provider. This guide walks you through the essential methods, interfaces, and best practices for connecting to and interacting with Aptos-enabled wallets—focusing on core functionality such as account management, network detection, signing transactions, and message verification.

Whether you're building on testnet or preparing for mainnet deployment, understanding these standard wallet operations ensures a smooth user experience and robust dApp performance.

Core Wallet Methods Overview

To interact securely with an Aptos wallet like Bitget Wallet (via window.bitkeep.aptos), developers can use a standardized set of methods. These enable critical actions including connection, signing, and real-time event listening.

Below is a structured overview of commonly supported wallet functions:

connect()

Returns: Promise<{ publicKey: string; address: string }>
Establishes a secure connection between your dApp and the user’s wallet. Upon success, returns the user's public key and blockchain address.

👉 Learn how to securely connect users in seconds

account()

Returns: Promise<{ publicKey: string; address: string }>
Retrieves the currently active wallet account information without re-initiating connection.

isConnected()

Returns: Promise<boolean>
Checks whether the wallet is currently linked to your dApp.

network()

Returns: Promise<string>
Returns the current network identifier (e.g., "Mainnet", "Testnet") the wallet is connected to.

Event Listeners

Signing Operations

Connecting to the Aptos Wallet

The first step in any dApp integration is establishing a connection with the user’s wallet. Most Aptos-compatible wallets inject a global provider object into the browser environment.

const provider = window.bitkeep?.aptos;

Ensure the provider exists before attempting to connect:

if (!provider) {
  alert("Aptos wallet not found. Please install Bitget Wallet.");
}

Once detected, initiate connection:

try {
  const response = await provider.connect();
  console.log("Connected:", response.address);
} catch (error) {
  console.error("Connection rejected:", error);
}

The returned response contains both publicKey and address, which are essential for identifying and verifying user identity.

Retrieving User Account Information

After connecting, retrieve the active account details at any time using the account() method:

const account = await provider.account();

This returns an interface matching:

interface AccountResult {
  publicKey: string; // Public key in hex format
  address: string;   // Aptos account address
}

Use this data to personalize UI elements, initialize balances, or populate transaction forms.

Monitoring Network and Account Changes

User behavior is dynamic—wallet users may switch accounts or networks during a session. Your dApp must respond accordingly.

Listen for Account Changes

provider.onAccountChange((newAccount) => {
  console.log("Account changed:", newAccount.address);
  // Update UI or refresh user data
});

This callback helps maintain state accuracy across multi-account setups.

Detect Network Switching

let currentNetwork = await provider.network();

provider.onNetworkChange((newNetwork) => {
  currentNetwork = newNetwork;
  console.log("Network switched to:", newNetwork);
  // Validate if your dApp supports the new network
});

👉 See how top dApps handle cross-network compatibility seamlessly

This pattern is crucial for preventing errors due to mismatched chain configurations.

Signing Messages with signMessage

Signing messages allows your dApp to authenticate users without gas costs. It's ideal for login flows or proving wallet ownership.

Payload Structure

interface SignMessagePayload {
  message: string;     // Required: message to sign
  nonce: string;       // Required: unique value to prevent replay attacks
  address?: boolean;   // Include wallet address in message
  application?: boolean; // Include dApp origin
  chainId?: boolean;   // Include current chain ID
}

Example Usage

const payload = {
  message: "Welcome to my Aptos dApp!",
  nonce: "49182736",
  address: true,
  application: true,
  chainId: true,
};

try {
  const result = await provider.signMessage(payload);
  console.log("Signature:", result.signature);
} catch (error) {
  console.error("User rejected signing");
}

The output conforms to:

interface AptosSignatureOutput {
  chainId: number;
  application: string;
  address: string;
  publicKey: string;
  message: string;
  nonce: string;
  prefix: string;
  fullMessage: string;
  signature: string;
}

This structured format enhances security and interoperability across services.

Signing and Submitting Transactions

Transactions allow users to interact with smart contracts—transferring tokens, minting NFTs, or participating in DeFi protocols.

Transaction Input Format

interface TransactionInput {
  function: string;           // Target function (e.g., '0x1::coin::transfer')
  type_arguments: string[];   // Generic types (e.g., ['0x1::aptos_coin::AptosCoin'])
  arguments: (string | number)[]; // Function arguments
  type: 'entry_function_payload'; // Fixed type
}

Sign Only (Advanced Use)

For full control over broadcast timing:

const transaction = {
  type: "entry_function_payload",
  function: "0x1::coin::transfer",
  type_arguments: ["0x1::aptos_coin::AptosCoin"],
  arguments: ["0xabc...", "1000000"],
};

const signedTxn = await provider.signTransaction(transaction);

Then submit via an AptosClient:

import { AptosClient } from "aptos";

const client = new AptosClient("https://fullnode.mainnet.aptoslabs.com");
const pendingTxn = await client.submitSignedTransaction(signedTxn);
await client.waitForTransaction(pendingTxn.hash);

Sign and Submit Directly (Convenience Method)

Alternatively, let the wallet handle both steps:

const pendingTxn = await provider.signAndSubmitTransaction(transaction);
console.log("Transaction hash:", pendingTxn.hash);

This approach simplifies UX but gives less control over error handling.

Frequently Asked Questions (FAQ)

How do I detect if an Aptos wallet is installed?

Check for the presence of window.bitkeep.aptos or similar providers. If undefined, prompt users to install a compatible wallet extension or mobile app.

Can I support multiple wallets in one dApp?

Yes. Use libraries like Petra, Pontem, or Wallet Standard to abstract provider differences and support multiple wallets uniformly.

What should I do when a user disconnects?

Clear cached account data, disable transaction buttons, and optionally show a reconnection prompt. Use onDisconnect() to automate this cleanup.

Is signAndSubmitTransaction safe?

It is safe when used with trusted transaction payloads. Always validate inputs and display clear transaction details before requesting user approval.

How do I handle wrong network errors?

Use network() to check the current chain and compare it against your dApp’s required network. Display warnings and guide users to switch if needed.

What happens if a user rejects a signature request?

The promise will reject. Handle this gracefully by informing the user and allowing retry without crashing the app flow.

Final Integration Tips

Ensure your dApp provides clear feedback during all interactions:

👉 Discover tools that accelerate your Aptos dApp development

By adhering to these patterns, you build trust, reduce friction, and align with community standards—key factors in driving adoption on the Aptos ecosystem.

Last updated on June 30, 2025