Create a Business Account

Create a business account, then list and read back its details.

Business Accounts are in early access. See Business Accounts for the model.

On React Native the same functions and hooks apply. See React Native Business Accounts for the host origin, key share storage, and step-up specifics on device.

Create a business account as an authenticated user. You become the owner, and can then add wallets, signers, and members. Business account functions are exported from @dynamic-labs-sdk/client/waas, and the matching React hooks from @dynamic-labs-sdk/react-hooks.

Prerequisites

• A Dynamic client initialized with your environment ID (see Creating a Dynamic Client)
• An authenticated user, because account operations act on behalf of the signed-in user
• Business Accounts enabled for your environment

Create an account

createBusinessAccount takes an optional name, externalRef, and metadata, and returns the new account. The caller becomes the owner.

JavaScript

import { createBusinessAccount } from '@dynamic-labs-sdk/client/waas';

const account = await createBusinessAccount({
  name: 'Acme Treasury',
  externalRef: 'org_acme_123',
});
// account.id  →  use this to add wallets, signers, and members

React

useCreateBusinessAccount returns a modification hook. Call mutate (or mutateAsync) to create.

import { useCreateBusinessAccount } from '@dynamic-labs-sdk/react-hooks';

const CreateAccount = () => {
  const { mutate, isPending } = useCreateBusinessAccount();

  return (
    <button
      onClick={() => mutate({ name: 'Acme Treasury', externalRef: 'org_acme_123' })}
      disabled={isPending}
    >
      Create account
    </button>
  );
};

name · string

Optional display name for the account.

externalRef · string

A developer-supplied label for mapping your own org/tenant ID onto this account, and the primary B2B2B2C integration key. Not unique; multiple accounts may share a value.

metadata · Record<string, unknown>

Arbitrary key-value metadata to store alongside the account.

List accounts

listBusinessAccounts returns the accounts the current user is a member of, for the active environment. Pass externalRefs to look up accounts by your own org or tenant ID; since externalRef is not unique, each value may match multiple accounts.

JavaScript

import { listBusinessAccounts } from '@dynamic-labs-sdk/client/waas';

const { items } = await listBusinessAccounts();

// Look up accounts by externalRef
const { items: matches } = await listBusinessAccounts({
  externalRefs: ['org_acme_123'],
});

React

import { useListBusinessAccounts } from '@dynamic-labs-sdk/react-hooks';

const AccountList = () => {
  const { data, isLoading } = useListBusinessAccounts({
    externalRefs: ['org_acme_123'],
  });
  if (isLoading) return null;
  return (
    <ul>
      {data?.items.map((a) => <li key={a.id}>{a.name ?? a.id}</li>)}
    </ul>
  );
};

Read one account

getBusinessAccount returns the account plus its members, signers, and wallets.

JavaScript

import { getBusinessAccount } from '@dynamic-labs-sdk/client/waas';

const detail = await getBusinessAccount({ businessAccountId: account.id });
// detail.members  · detail.signers  · detail.wallets

React

import { useGetBusinessAccount } from '@dynamic-labs-sdk/react-hooks';

const AccountDetail = ({ businessAccountId }: { businessAccountId: string }) => {
  const { data: detail } = useGetBusinessAccount({ businessAccountId });
  return <span>{detail?.wallets.length ?? 0} wallets</span>;
};

Only members of an account can read it. A non-member request returns 404 (not 403), so account existence isn’t leaked across tenants.

Next steps

Add wallets

Create a fresh wallet or link an existing one to the account.

Members & roles

Invite admins and viewers, and transfer ownership.