Embedded wallets

Authon creates an EVM wallet for every signed-in user. Users need no wallet app or seed phrase; your app reads the address and requests signatures through the SDK.

Setup

  1. In the console, open Advanced > Embedded wallets, turn on wallet creation and pick chains.
  2. Add your site to Allowed origins in project settings. Wallets only work on allowed origins.
  3. Enable wallet.autoCreate in the SDK.
app.ts
import { Authon } from '@authon/js';

const authon = new Authon('pk_live_...', {
  wallet: { autoCreate: true },
});

// After sign-in the wallet already exists.
const wallet = await authon.wallet.ensure();
// { address, protected, needsRestore, devices }

const signature = await authon.wallet.signTypedData(order);

What the user sees

WhenPromptWhat happens
Sign-up or sign-inNothing shownThe wallet is created alongside the account. No address or seed phrase is shown.
Before the first depositOne confirm card + Face ID or fingerprintThe user protects the wallet with a passkey. An unprotected wallet is lost with the device, so block deposits until it is protected.
First use on a new device or another siteOnce per deviceConfirming with the same passkey brings back the same wallet. Passkeys sync through iCloud Keychain and Google Password Manager.
wallet.ts
// Call from a button click: the browser only shows the passkey prompt after a user gesture.
await authon.wallet.protect();

// On a new device or another site (wallet.needsRestore === true):
await authon.wallet.restore();

Key storage

The wallet key is split into three shares and any two can sign. Authon holds only the server share, so neither Authon nor your team can move a user's funds alone.

User's deviceEncrypted in browser storage with a non-extractable key
Authon serverSealed with a server-only key
Passkey backupOpens only with the user's passkey (PRF)

Apps (iOS, Android, React Native)

Apps use the same wallet as the web: the same user gets the same address, and the app appears as one more device. The device stores only its share (iOS Keychain with the Secure Enclave, Android Keystore) and combines it with the server share for each signature, then discards the key.

  1. In the console, Embedded wallets → Apps: add the iOS Team ID and bundle ID, and the Android package name with its release signing certificate SHA-256.
  2. On iOS add webcredentials:wallet.authon.dev to Associated Domains. On Android the Credential Manager dependency is enough.
  3. Once Authon reviews and approves the signing details, passkey backup and restore work in the app. Creating wallets and signing work before approval.
Wallet.swift
import Authon
import AuthonWalletAuthon

let authon = Authon(publishableKey: "pk_live_...")
let wallet = AuthonWallet(authon: authon)

let w = try await wallet.create()          // same address as on the web for this user
let signature = try await wallet.signTypedData(order)
try await wallet.protect()                 // passkey backup (iOS 18+)
try await wallet.restore()                 // new phone or reinstall
Wallet.kt
val wallet = AuthonWallet(authon, activityProvider = { currentActivity })

val w = wallet.create()
val signature = wallet.signTypedData(orderJson)
wallet.protect()                           // passkey backup (Credential Manager PRF)
wallet.restore(RestoreMode.ADD)            // new phone or reinstall

A backup passkey made on the web (iCloud Keychain, Google Password Manager) restores the wallet in the app and the other way round. The app SDK handles shares inside your app: Authon alone still cannot use a wallet, but your app code can reach the key while the user signs.

Server-held sessions (BFF)

When the browser has no Authon session, issue a five-minute wallet token on your server. It is accepted only by the wallet API.

wallet-token.ts
// Server (Next.js route handler)
import { createAuthonWalletToken } from '@authon/nextjs/server';

export async function GET() {
  const userId = await getSignedInUserId(); // from your own session
  return Response.json(await createAuthonWalletToken({ userId, secretKey: process.env.AUTHON_SECRET_KEY! }));
}

// Browser
const authon = new Authon('pk_live_...', {
  sessionMode: 'bff',
  wallet: {
    autoCreate: true,
    getToken: () => fetch('/api/wallet-token').then((r) => r.json()).then((b) => b.token),
  },
});
Authon — Plataforma universal de autenticação