BaaS SDK

Call your smart contracts by name, express amounts in the token's unit, and sign users in with a passkey. No ABI files, no unit math, no wallet plumbing.

Documentation · Quickstart · API reference

Install the SDK

npm install @baas.sh/sdk

Initialize the client

Create one client with your project's Project API URL. You find it in your BaaS project settings. The URL is public, so it belongs in frontend code; no project secret key does.

import { createBaasClient, SmartUnits, type UnitFormattedValue } from '@baas.sh/sdk';

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

Before the first call, enable the wallet mode and the networks you need, and allow your app's origin in the project CORS settings. The quickstart walks through this setup.

Sign in a user

Sign in with a passkey, then select the network your app works on. A passkey wallet needs one activation per network before its first write.

const session = await baas.auth.signInWithSmartWallet({
  email: '[email protected]',
});

await baas.chains.switch(11155111); // Sepolia, enabled in your project
await baas.smartWallet.activate();

Creating the account is a separate action, signUpWithSmartWallet(), covered in the quickstart. switch() selects the network for every new operation. activate() prepares the smart wallet on that network; it is idempotent.

Using an external wallet instead? Sign in with the EIP-1193 provider, hand it to switch() so the wallet changes network too, and pass it again when you send.

const session = await baas.auth.signInWithWallet(provider, {
  email: '[email protected]',
});

await baas.chains.switch(11155111, { signer: provider });
// Sends take the same option: .sendTransaction({ signer: provider })

Send an amount in the token's unit

Register your ERC-20 in BaaS under a name, MyToken here, then call it by that name. BaaS resolves the ABI and the token's decimals for you.

const myToken = baas.contract('MyToken').address(contractAddress);

const tx = await myToken
  .function('transfer')
  .params(recipient, SmartUnits('12.5'))
  .sendTransaction();

await tx.wait();

• SmartUnits('12.5') is converted with the decimals bound to that argument. For an ERC-20, BaaS detects them from the standard. For a custom function such as mint, declare the unit in BaaS once.
• The transaction goes to the active network. There is no chainId to pass.
• tx.wait() confirms the transaction on its original network, even if the user switches network in the meantime.

Read a formatted value

The same contract returns amounts ready to display.

const [balance] = await myToken
  .function('balanceOf')
  .params(session.address)
  .read<[UnitFormattedValue]>();

console.log(balance.formatted); // '12.5'

For a token with six decimals, balance looks like this:

{
  "raw": "12500000",
  "formatted": "12.5",
  "metadata": { "encoding": "units", "decimals": "6" }
}

Show balance.formatted; keep balance.raw for exact integer arithmetic. Every amount whose unit BaaS knows, detected or declared, comes back in this shape: in reads, simulations and events.

Search event history

History is available on your project's own network; select it before querying.

Search a contract's events

Find transfers of 100 to 1,000 tokens, since September 1, either sent by Alice or received by your treasury:

import { and, or, eq, gte, lte, SmartUnits } from '@baas.sh/sdk';

const alice = '0x1111111111111111111111111111111111111111';
const treasury = '0x2222222222222222222222222222222222222222';

const transfers = await myToken.events({
  event: 'Transfer',
  where: and(
    gte('args.value', SmartUnits('100')),
    lte('args.value', SmartUnits('1000')),
    gte('occurredAt', '2026-09-01T00:00:00Z'),
    or(
      eq('args.from', alice),
      eq('args.to', treasury),
    ),
  ),
  limit: 50,
});

console.log(transfers.nextCursor); // pass as cursor to load the next page
console.log(transfers.data);  // this page, newest first, with decoded arguments

and requires every condition; or accepts either. Smart Units let you write amounts in tokens, without converting decimals yourself.

Search the signed-in user's events

Find transfers of at least 10 tokens received by the signed-in user on the same token contract:

const received = await baas.user.events({
  address: contractAddress,
  event: 'Transfer',
  where: and(
    eq('direction', 'in'),
    gte('args.value', SmartUnits('10')),
  ),
  limit: 20,
});

console.log(received.nextCursor); // null on the last page
console.log(received.data);  // decoded events, each with the user's directions

The SDK uses the signed-in user's address automatically. direction selects incoming (in), outgoing (out) or related events (related), as defined by your contract's event mappings in BaaS.

For either search, keep the same filter and pass nextCursor as cursor to load more results. See the event history guide.

Next steps

The SDK also simulates calls, estimates gas, sends native transfers and signs messages.

• Quickstart and project setup
• Smart units
• Smart contracts and event history
• API reference
• Use with React
• A runnable example and setup instructions are included in node_modules/@baas.sh/sdk/examples/browser.

Sessions, cookies, user profiles, push notifications, error handling and recovery are covered in the guides at docs.baas.sh.

Requirements

Use a modern browser with fetch, Web Crypto, and BigInt. Passkeys also require WebAuthn in a secure context. Imports are SSR-safe; client operations run in the browser. The package supports Node.js 20.19 or newer, ESM, CommonJS, and TypeScript.

License

Copyright 2026 BaaS.sh. Licensed under Apache-2.0. See LICENSE in this package.