Starknet Wallet Integration: Connect to App or Mini Wallet with DEX API

Installation and Initialization

To begin integrating OKX Connect into your decentralized application (DApp), ensure you have the OKX App updated to version 6.98.0 or later. You can install the necessary package via npm:

npm install okx-connect

Initializing the Wallet Interface

Before connecting to a wallet, create an object that provides a UI interface for wallet operations like connecting and sending transactions.

Request Parameters:

• dappMetaData (object):

  • name (string): Application name (not used as a unique identifier).
  • icon (string): URL of a PNG/ICO icon (180x180px recommended; SVG not supported).

• actionsConfiguration (object):

  • modals (array or 'all'): Alert display modes during transactions ('before', 'success', 'error').
  • returnStrategy (string): Deep link return strategy for app wallet (e.g., tg://resolve for Telegram).
  • tmaReturnUrl (string): Telegram Mini Wallet return policy ('back', 'none', or custom deeplink).

• uiPreferences (object):

  • theme: THEME.DARK, THEME.LIGHT, or 'SYSTEM'.
• language (string): Supported locales (e.g., en_US, zh_CN).

Return Value:

• OKXUniversalConnectUI object.

Example:

const connectUI = new OKXUniversalConnectUI({
  dappMetaData: {
    name: "My DApp",
    icon: "https://example.com/icon.png"
  },
  actionsConfiguration: {
    modals: ['before', 'error'],
    returnStrategy: 'tg://resolve'
  },
  theme: THEME.DARK
});

Connecting to a Wallet

Establish a connection to fetch wallet addresses and transaction signing parameters.

Request Parameters:

• connectParams (object):

  • namespaces (object): Supported chains (e.g., starknet:mainnet).
  • chains (array): Chain IDs.
  • defaultChain (string, optional): Default chain.

  • sessionConfig (object):

    • redirect (string): Post-connection deeplink (e.g., tg://resolve).

Return Value:

• Promise with session details:

  • topic: Session identifier.
  • accounts: Connected wallet addresses.
  • methods: Supported wallet methods.

Example:

const session = await connectUI.connect({
  namespaces: { starknet: { chains: ['starknet:mainnet'] } },
  sessionConfig: { redirect: 'tg://resolve' }
});

Transaction Preparation

Create an OKXStarknetProvider instance using OKXUniversalProvider:

const provider = new OKXStarknetProvider(OKXUniversalProvider);

Account Information

Fetch wallet details for a specific chain.

Request Parameters:

• chainId (string): e.g., starknet:mainnet.

Return Value:

• Object:

  • address: Wallet address.
  • pubKey: Public key.

Example:

const account = await provider.getAccount('starknet:mainnet');

Message Signing

Sign a message with structured data.

Request Parameters:

• signerAddress (string): Wallet address.
• typedData (object): Message in a fixed format.
• chain (string, optional): Target chain.

Return Value:

• Promise<[string, string]>: Signature components (r, v).

Example:

const signature = await provider.signMessage(
  '0x123...',
  { domain: {...}, types: {...}, message: {...} }
);

Sending Transactions

Submit a transaction to the network.

Request Parameters:

• signerAddress (string): Wallet address.
• transaction (object): Transaction details.
• chainId (string, optional): Target chain.

Return Value:

• Promise<string>: Transaction hash.

Example:

const txHash = await provider.sendTransaction(
  '0x123...',
  { calldata: [...], contractAddress: '0x...' }
);

Disconnecting a Wallet

Terminate the current session to switch wallets.

await connectUI.disconnect();

Event Handling

Listen for wallet events (e.g., connection changes).

provider.on('accountsChanged', (accounts) => {
  console.log('Accounts updated:', accounts);
});

Error Codes

Common exceptions during wallet operations:

👉 Explore advanced wallet integrations for more features.

FAQ

How do I handle unsupported chains?

Verify the chain ID matches starknet:mainnet. Use optionalNamespaces for fallback chains.

Can I customize the wallet UI theme?

Yes! Set uiPreferences.theme to THEME.DARK, THEME.LIGHT, or 'SYSTEM'.

What if the user rejects a transaction?

Catch USER_REJECTS_ERROR and prompt a retry or alternative action.

👉 Learn more about secure transactions in our developer docs.