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?
EmbarkAI supports any EVM-compatible chain that has an ERC-4337 bundler endpoint. The SUPPORTED_CHAINS constant in @embarkai/core lists preconfigured chains. You can add custom chains by providing an RPC URL and bundler URL via ChainContext.
How do gasless transactions work?
The SDK uses ERC-4337 paymasters. When a user submits a user operation, a paymaster contract can agree to cover the gas cost. The bundler includes the paymaster’s signature when submitting the operation on-chain, so the user’s account is never debited for gas.
Wallets & Security
Can I use MetaMask or another external wallet?
Yes. The UI Kit supports three wallet modes:
- embedded — MPC-based wallet managed entirely by the SDK.
- external — connects an injected wallet like MetaMask via wagmi.
- hybrid — both modes available; users can bridge funds between them with
useTransferToLinkedWallet.
Set the mode via the walletMode field in ProviderConfig.
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?
Contact the EmbarkAI team or visit the developer dashboard to create a project and generate an API key. The key is required for all SDK packages.
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. Refer to the license field in each package’s package.json for specific terms.
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 smart account must be deployed before it can execute operations. Call deployAccount(chainId) from @embarkai/ui-kit or send an initial operation that triggers deployment through the account factory.
I get a “token expired” error during API calls
Use authenticatedFetch from @embarkai/core or ensure ensureValidToken() is called before each request. Both automatically refresh expired tokens using the stored refresh token.
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.