> For the complete documentation index, see [llms.txt](https://docs.alignedlayer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alignedlayer.com/wallet-as-a-service/quickstart.md).

# Quickstart

{% hint style="warning" %}
Aligned Wallet is still private. Third parties cannot integrate it until Aligned has allowlisted them.
{% endhint %}

Add a wallet to a web app: sign the user in, create their wallet, send a transaction. Everything below runs in the browser, with a passkey as the user's key.

For wagmi apps, [wagmi and viem](https://docs.alignedlayer.com/wallet-as-a-service/framework-guides/wagmi.md) covers the connector and the prebuilt modal, which handle all of these steps.

## 1. Get a publishable key

Create an app in the Aligned dashboard and copy its publishable key (`aligned_pk_test_...`). The key identifies your app. It is not a secret and is meant to ship in your frontend.

Add every origin your app runs on to the key's allowed origins, including your development server's, such as `http://localhost:5173`. Requests from any other origin are rejected with `403 origin_not_allowed`.

## 2. Install the SDK

```sh
npm install @aligned-waas/sdk viem
```

## 3. Create a client

```ts
import { AlignedClient, localStorageAdapter, webPasskeyAdapter } from '@aligned-waas/sdk';

export const aligned = new AlignedClient({
  publishableKey: 'aligned_pk_test_...',
  storage: localStorageAdapter(), // keeps the session across reloads
  passkey: webPasskeyAdapter(),   // browser WebAuthn
});
```

The client connects to the Aligned testnet by default. Pass `baseUrl` to point it at a backend you run yourself.

Construct it once, at module scope. A new client on every render restarts session restoration and discards its caches.

## 4. Sign the user in

Email one-time code, no password:

```ts
await aligned.auth.startEmailOtp({ email });
const user = await aligned.auth.verifyEmailOtp({ email, code });
```

The first successful verification creates the account. Google sign-in is available too, in a popup:

```ts
const user = await aligned.auth.loginWithGooglePopup();
```

## 5. Get the wallet ready

```ts
const result = await aligned.wallets.ensureReady({
  chainIds: [84532], // the chains your app supports, in preference order
});

if (result.status === 'ready') console.log(result.account.address);
```

One call covers every signed-in user:

| `status`             | Meaning                                                                                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ready`              | This device can sign. A new user's wallet was created on the first of `chainIds` the app supports, with a passkey registered under their account.                                            |
| `needs_device`       | The wallet exists but this device has no passkey for it. Add the device from one that does, see [Keys and recovery](https://docs.alignedlayer.com/wallet-as-a-service/keys-and-recovery.md). |
| `no_supported_chain` | The wallet, or the app, is on none of `chainIds`.                                                                                                                                            |
| `cancelled`          | The user dismissed the passkey prompt while creating the wallet.                                                                                                                             |

A returning user whose passkey is synced to this device (iCloud Keychain, Google Password Manager) gets one passkey prompt and then `ready`.

On page load, call `aligned.wallets.restore({ chainIds })` instead. It never prompts and never creates a wallet: it resolves `ready` when this device can already sign, and `not_ready` otherwise, in which case call `ensureReady` from a button. It makes no request when no session is stored.

## 6. Send a transaction

```ts
const { tx_hash } = await aligned.wallets.sendTransaction({
  to: '0x...',
  value: 1_000_000_000n, // wei, defaults to 0
  data: '0x',            // calldata, defaults to '0x'
});
```

The SDK asks the backend for the digest bound to the wallet's current nonce, prompts for the passkey, and submits. Aligned relays the transaction and pays the gas, so your users never need the chain's native token. The call returns once the transaction is mined and succeeded. If it was sent and then reverted, it throws `TransactionRevertedError`; if it was sent but not mined in time, it throws `TransactionTimeoutError`. Both carry `txHash`. A call that would revert is rejected before it is sent; see [Failed transactions](https://docs.alignedlayer.com/wallet-as-a-service/integration-notes.md#failed-transactions).

## Handling errors

A call the backend refuses throws `ApiError`, carrying the HTTP `status`, a stable `code`, and the parsed response `body`. The SDK's own checks throw named errors instead, such as `NotSignedInError` or `BatchTooLargeError`. Codes worth handling explicitly:

| Code                             | What to do                                                                                                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_token`                  | The session expired and could not be refreshed. Send the user back through sign-in. The client also emits a `session` event, `{ type: 'signed_out', reason: 'expired' }`. |
| `unauthenticated`                | No session, or the publishable key is invalid or disabled. Check the key before sending users to sign-in.                                                                 |
| `origin_not_allowed`             | The page origin is not on the publishable key's allowlist. Fix it in the dashboard.                                                                                       |
| `rate_limited`                   | Back off and retry.                                                                                                                                                       |
| `step_up_required`               | The endpoint needs a fresh step-up proof, see [Keys and recovery](https://docs.alignedlayer.com/wallet-as-a-service/keys-and-recovery.md).                                |
| `simulation_reverted`            | The transaction would revert, so it was not sent. `body.error.details.revert_data` has the revert data.                                                                   |
| `tx_reverted`, `receipt_timeout` | The transaction was sent; `body.error.details.tx_hash` names it. A timed-out one may still land.                                                                          |

A cancelled passkey prompt or Google popup throws `UserRejectedError`. Treat it as a normal outcome, not a failure: the user declined.

## Node.js

The SDK is a browser and mobile library. The publishable-key path requires a real `Origin` header, which Node's `fetch` does not send, so calls from Node are rejected. Use it in Node only for tests or for building signing material that a browser will send.

## Next steps

* [How it works](https://docs.alignedlayer.com/wallet-as-a-service/how-it-works.md), what the contracts guarantee and why.
* [Keys and recovery](https://docs.alignedlayer.com/wallet-as-a-service/keys-and-recovery.md), multiple devices and losing them.
* [Integration notes](https://docs.alignedlayer.com/wallet-as-a-service/integration-notes.md), what to decide before launch.
* [wagmi and viem](https://docs.alignedlayer.com/wallet-as-a-service/framework-guides/wagmi.md), [React](https://docs.alignedlayer.com/wallet-as-a-service/framework-guides/react.md) and [React Native](https://docs.alignedlayer.com/wallet-as-a-service/framework-guides/react-native.md) for the framework adapters.
* [Migrating to 2.0](https://docs.alignedlayer.com/wallet-as-a-service/migrating-to-2.md), if you used SDK 1.x.
