FAQ
Frequently asked questions about embarkAI.
General
What is embarkAI?
embarkAI is a smart wallet SDK that lets developers add self-custodial, gasless wallets to web and server applications. It combines MPC (Multi-Party Computation) key management with ERC-4337 account abstraction so users never need to handle seed phrases, install browser extensions, or pay gas directly.
How does MPC keep my keys safe?
Your private key is never created or stored in a single location. During key generation, the key is split into multiple cryptographic shares via a Distributed Key Generation (DKG) protocol. Signing requires a threshold of shares to cooperate without ever reconstructing the full key. Even if one share is compromised, an attacker cannot produce a valid signature alone.
What is ERC-4337 (Account Abstraction)?
ERC-4337 introduces smart contract accounts that replace traditional externally-owned accounts (EOAs). Instead of broadcasting transactions directly, users submit “user operations” that a bundler packages and submits on-chain. This enables gasless transactions, batched calls, and programmable validation logic — all without modifying the Ethereum protocol.
How do smart accounts differ from EOAs?
| EOA | Smart Account | |
|---|---|---|
| Controlled by | Single private key | Contract logic |
| Gas payment | Must hold native token | Sponsorable via paymasters |
| Batching | One call per transaction | Multiple calls in one operation |
| Recovery | Seed phrase only | Social recovery, vault backup |
| Upgradability | None | Contract can be upgraded |
Chains & Tokens
What chains are supported?
The chains listed on Supported Chains. SUPPORTED_CHAINS in @embarkai/core/read holds their configs, and an unsupported chain ID is rejected. For a supported chain you can override rpcUrl, bundlerUrl, factoryAddress, entryPointAddress and paymasterAddress in ServerWalletManagerConfig.
How do gasless transactions work?
The SDK uses ERC-4337 paymasters. Every supported chain has a paymaster configured by default; the SDK sets the paymaster and paymasterData fields of the UserOperation (ERC-4337 v0.7) and the EntryPoint charges the paymaster’s deposit, so the user’s account is never debited for gas. See Paymaster & Gasless Transactions.
Wallets & Security
Can I use MetaMask or another external wallet?
Yes. Enable external wallets with initialConfig.wallet.enabled and pick a mode via initialConfig.wallet.mode:
- linked — the external wallet (MetaMask, WalletConnect) owns an embarkAI smart account; transactions go through the bundler. Default.
- direct — the external wallet signs transactions itself, without account abstraction.
- both — the user chooses between the two.
useTransferToLinkedWalletmoves funds from the smart account to the linked external wallet.
See External Wallet for the hooks.
What happens if I lose my keyshare?
If you have backed up your keyshare to the embarkAI vault (using backupToVault or the KeyshareBackup component), you can restore it on any device by providing your backup password. Without a vault backup, the keyshare cannot be recovered and a new wallet must be created.
Is my keyshare password stored on your servers?
No. The password is used client-side to derive an encryption key. Only the encrypted keyshare blob is sent to the vault. embarkAI servers never see or store your plaintext password.
Development
How do I get an API key?
In dashboard.embarkai.io open your project, go to Server Wallets and click Create API Key. The key is shown once; store it as EMBARK_API_KEY. It is required by @embarkai/core server wallets and by @embarkai/mcp; the UI Kit uses the project ID instead.
What frameworks are supported?
- @embarkai/core — runs in any JavaScript environment (Node.js 18+, modern browsers, edge runtimes).
- @embarkai/ui-kit — requires React 18 or later. Compatible with Next.js, Vite, and other React-based frameworks.
- @embarkai/mcp — runs on Node.js 18+ and communicates over stdio or custom transports.
Is embarkAI open source?
The SDK packages are distributed via npm under the MIT license (@embarkai/core and @embarkai/mcp declare it in package.json). Sources are on GitHub: embark-ai/core , embark-ai/ui-kit , embark-ai/mcp .
Can I use the SDK on the server side?
Yes. @embarkai/core exports createServerWalletManager which provides full wallet functionality without a browser. The @embarkai/mcp package is designed specifically for server-side and AI-agent use cases.
Troubleshooting
My user operation fails with “AA21 — account not deployed”
The first UserOperation sent from a wallet deploys the smart account automatically through the account factory, so this error usually means the operation was built for a different chain or account. To deploy explicitly from the UI Kit, call deployAccount(session) with the session from useAccountSession().
I get a “token expired” error during API calls
Use authenticatedFetch from @embarkai/core or call ensureValidToken() before each request. Both automatically refresh expired tokens using the stored refresh token; ensureValidToken() resolves to false when the session cannot be refreshed and the user has to sign in again.
How do I enable debug logging?
In @embarkai/mcp, set the EMBARK_DEBUG=true environment variable or pass debug: true in McpConfig. For @embarkai/core, check your bundler and RPC logs for operation-level diagnostics.