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
- In the console, open Advanced > Embedded wallets, turn on wallet creation and pick chains.
- Add your site to Allowed origins in project settings. Wallets only work on allowed origins.
- Enable wallet.autoCreate in the SDK.
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
| When | Prompt | What happens |
|---|---|---|
| Sign-up or sign-in | Nothing shown | The wallet is created alongside the account. No address or seed phrase is shown. |
| Before the first deposit | One confirm card + Face ID or fingerprint | The 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 site | Once per device | Confirming with the same passkey brings back the same wallet. Passkeys sync through iCloud Keychain and Google Password Manager. |
// 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 device | Encrypted in browser storage with a non-extractable key |
| Authon server | Sealed with a server-only key |
| Passkey backup | Opens 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.
- 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.
- On iOS add webcredentials:wallet.authon.dev to Associated Domains. On Android the Credential Manager dependency is enough.
- Once Authon reviews and approves the signing details, passkey backup and restore work in the app. Creating wallets and signing work before approval.
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 reinstallval 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 reinstallA 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.
// 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),
},
});