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

# Quickstart

Install the SDK, configure your project, and sign in your first user.

Install the SDK, connect your BaaS project, and sign in a user with a passkey.

{% hint style="info" %}
The SDK runs in the **browser** and needs **HTTPS** (`localhost` is exempt). See the [Introduction](/baas-sdk/sdk.md) for the full prerequisites.
{% endhint %}

{% stepper %}
{% step %}

### Install the SDK

{% tabs %}
{% tab title="npm" %}

```bash
npm install @baas.sh/sdk
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm add @baas.sh/sdk
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn add @baas.sh/sdk
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Get your API URL

You need one value to connect the SDK to your project: `url`, your project's API URL. Copy it from the Console’s **Dashboard → Project Endpoints** or from the project detail in the BaaS Dashboard.

{% hint style="info" %}
The URL is public and ships in your client bundle. You can store it in an environment variable; never put a project secret key in frontend code.
{% endhint %}
{% endstep %}

{% step %}

### Initialize the client

Create the client once in browser code. In React or Next.js, use the [React guide](/baas-sdk/integrations/react.md) to defer initialization to browser execution.

{% code title="baas.ts" %}

```ts
import { createBaasClient } from '@baas.sh/sdk';

export const baas = createBaasClient('https://my-project-api.baas.sh');
```

{% endcode %}
{% endstep %}

{% step %}

### Set the passkey domain

Allow your app’s exact origin in [API Settings → Allowed Domains](/baas-console/api-settings/domain-protection.md), including the port for localhost. Enable the Smart Wallet mode and any networks you will use.

Before the first sign-up, open **Wallet Settings** in the Console and set the passkey domain: the domain your app runs on (`example.com` covers its subdomains), or `localhost` for local development. See [Wallet Settings](/baas-console/wallet-settings.md#the-passkey-domain).
{% endstep %}

{% step %}

### Create the user's account

For a brand-new user, create a passkey. Sign up creates the account and stops there — no session yet:

```ts
const { address } = await baas.auth.signUpWithSmartWallet({ email: 'alice@example.com' });
//  → { address: '0x…' }
```

Then send the user to your sign-in step. New and returning users open their session with their passkey:

```ts
const session = await baas.auth.signInWithSmartWallet({ email: 'alice@example.com' });
console.log(session.address);
```

Both take the account email. See [Authentication](/baas-sdk/authentication.md) for wallet sign-in and the difference between sign up and sign in.
{% endstep %}

{% step %}

### React to auth state

Keep your UI in sync with the session. The callback fires `INITIAL_SESSION` once initial restoration has settled, then on every change.

```ts
const unsubscribe = baas.auth.onAuthStateChange((event, session) => {
  if (session) console.log('Signed in as', session.address);
  else         console.log('Signed out');
});
```

{% endstep %}
{% endstepper %}

<details>

<summary>Going to production</summary>

Two things to check before you ship, both configured outside the SDK:

* **Origins** — add your app's origin to your project's allowed origins. With domain protection on, requests from any other origin are refused on every route, sign-in included. Wildcards are not accepted. Add it under [API Settings → Allowed Domains](/baas-console/api-settings/domain-protection.md).
* **HTTPS** — required on any domain other than `localhost` (passkeys and WebAuthn need a secure origin).

</details>

## Read a balance

After sign-in, read the user’s balance on a network enabled in your project:

```ts
await baas.chains.switch(11155111);
const balance = await baas.wallet.getBalance(session.address);
console.log(balance.formatted); // native amount on Sepolia, e.g. '1.5'
// balance.raw is the exact wei string; balance.metadata.decimals is '18'.
```

## First transaction

After passkey sign-in, activate the smart wallet on an enabled network before sending. For Sepolia, enable chain `11155111` in the project and fund the wallet with test ETH for the transfer and any network fees.

```ts
import { SmartUnits } from '@baas.sh/sdk';

await baas.chains.switch(11155111);
await baas.smartWallet.activate();

const tx = await baas.wallet.sendTransaction({
  to: recipientAddress, // the user-selected 0x address
  value: SmartUnits('0.001'), // 0.001 ETH, converted to wei for you
});
await tx.wait();
```

External wallets do not use smart-wallet activation. Pass their EIP-1193 provider as `signer` when switching networks and sending transactions.

See [Smart units](/baas-sdk/blockchain/smart-units.md) for token amounts and formatted balances.

## Sign out

Connect this call to your sign-out action. If the request fails, show the error and let the user retry; the SDK keeps the session until the API confirms signout.

```ts
await baas.auth.signOut();
```

Call `unsubscribe()` when your UI no longer needs auth updates.

## Runnable example

The npm package includes `examples/browser`. Copy it from `node_modules/@baas.sh/sdk/examples/browser` to a new directory, then run `npm install`, copy `.env.example` to `.env.local`, set `VITE_BAAS_URL` to your Project API URL, and run `npm run dev`. Configure `http://localhost:5173` as an allowed project origin and `localhost` as the passkey RP ID. Use a test project and test funds.

## Next steps

Using React or Next.js? The [Use with React](/baas-sdk/integrations/react.md) guide covers the session hook and the SSR setup required for Next.js; the [complete example](/baas-sdk/integrations/react-app-example.md) adds a provider and a route guard.

Running into an issue? Check the [Troubleshooting](/baas-sdk/troubleshooting.md) guide.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Authentication</strong></td><td>Passkeys, wallets, and the sign up vs sign in model.</td><td><a href="/baas-sdk/authentication.md">Authentication</a></td></tr><tr><td><strong>Integration guides</strong></td><td>Framework guides, supported bundlers, and TypeScript setup.</td><td><a href="/baas-sdk/integrations.md">Integration guides</a></td></tr><tr><td><strong>Blockchain interactions</strong></td><td>Call your smart contracts, send transactions, and switch networks.</td><td><a href="/baas-sdk/blockchain.md">Blockchain interactions</a></td></tr></tbody></table>