Embedded Wallets

@0xgasless/core gives your users a real on-chain wallet without asking them to install MetaMask, write down a seed phrase, or understand what a private key is. They log in with email and password; the signing key lives in AWS KMS, locked inside a sandboxed iframe. Your app never sees it.

npm install @0xgasless/core

When to use it

Use case	Fit
Browser dApp where users authenticate and sign their own transactions	★★★★★
Onboarding flow that needs a wallet but not MetaMask	★★★★★
Mobile web app — works on any modern browser without extensions	★★★★★
Bot, cron job, or AI agent that signs autonomously	Use Server Wallets instead
Native iOS/Android app	Embedded Wallets is browser-only — use the platform’s secure enclave

Why an iframe?

Security. The iframe runs on a separate origin from your app. Browsers enforce strict rules: your JavaScript cannot read anything inside the iframe, and the iframe cannot read your page. The only communication channel is postMessage, and the SDK validates every message.

Even if an attacker injects code into your page, they cannot extract the user’s private key — it never leaves the iframe, and even there it’s only ever a KMS-backed handle, not raw bytes.

What you get

• A non-custodial wallet backed by AWS KMS. The user controls their key; 0xGasless cannot sign without them.
• Email + password login. No seed phrases, no recovery questions, no browser extension.
• Optional ERC-4337 smart account. The companion OxGasClient wires the embedded wallet into a smart account so transactions can be sponsored by the 0xGasless paymaster — users transact without holding any native token.
• Event-driven API. Subscribe to connected, disconnected, signatureComplete, stateChange, error.
• TypeScript-first. Every config option, event payload, and error class is typed.

Two classes, two levels

Class	What it does	Use when
OxGasAuth	Auth + raw signing (message + transaction).	You manage the smart account yourself, or you don’t need one.
OxGasClient	Wraps OxGasAuth + manages an ERC-4337 smart account, gasless transactions, and token helpers.	You want auth + gasless tx in one object.

Most apps should start with OxGasClient. Drop down to OxGasAuth if you only need raw signing or you’re wiring the embedded wallet into your own smart-account stack.

Mental model

Your app                Widget iframe              KMS                 Smart Account
────────                ─────────────              ───                 ─────────────
                              │                     │                        │
client.login() ──────────►   user enters creds      │                        │
              ◄──── walletInfo (address, email)     │                        │
                              │                     │                        │
client.setupSmartAccount() ─────────────────────────────────► counterfactual addr
              ◄────────────────────────────────────────────────  return addr  │
                              │                     │                        │
client.sendTransaction(tx) ►  user approves         │                        │
                              │  hash to sign  ────► KMS sign                │
                              │  ◄────────── signature                       │
                              │                     │                        │
                              UserOp ──────────────────────► bundler ───────►  EntryPoint
                                                                              executes tx

The user approves once per transaction. The KMS key never leaves the platform. The 0xGasless paymaster covers gas if you’ve configured sponsorship in the dashboard.

Next steps

• Quickstart — install, log in, send a gasless transaction in 5 minutes.
• Configuration — every option, with defaults.
• Authentication — what happens during login.
• Smart Account Integration — ERC-4337 + gasless transactions.
• Events — every event the SDK emits.
• Errors — every typed error and how to recover.