Skip to main content
Bastion uses a two-tier hierarchy to manage customers and their financial operations: Identities at the top level and Accounts beneath them. This separation provides flexibility for compliance, multi-wallet scenarios, and organizational structures.

Identity

An Identity represents a verified individual or business entity in the Bastion system. It serves as the compliance and regulatory anchor for all financial activity. Key properties of an Identity: Each identity must have a unique email address. Bastion does not allow the same email address to be used across multiple identities for stablecoin conversions.

identity.status values

identity.sub_status values

Every sub-status except RFI_REQUIRED only appears while status is PENDING_ONBOARDING. RFI_REQUIRED can also be set on an ACTIVE or SUSPENDED identity when Compliance requests additional information after onboarding. An ACTIVE identity keeps transacting while the RFI is open, and sub_status clears once it is fulfilled.

How an RFI interacts with other changes

  • During onboarding, Bastion can raise an RFI at any step. When it is fulfilled, sub_status returns to the step the identity was at, or to the step it has reached since, for example IDV_REQUIRED.
  • Bastion rejects resubmitted KYC/KYB data, whether or not an RFI is open. Once an identity has KYC or KYB data, POST /v2/identities/{identity_id}/compliance returns 409 ALREADY_EXISTS, and sub_status doesn’t change.
  • A change of status can open or close an RFI. Read sub_status on every identity_status_update webhook, including ones where status doesn’t change. Treat any value other than RFI_REQUIRED as no open RFI.

What to expect when Bastion raises an RFI

  1. You receive an identity_status_update webhook with sub_status RFI_REQUIRED. GET /v2/identities/{identity_id} shows the same value if you miss the webhook.
  2. Bastion Compliance asks for the information it needs. You and Bastion decide at the program level who it contacts:
    • Your compliance team. Bastion Compliance tells your compliance team what it needs. You collect the information from your user and send it to Bastion Compliance through the channel agreed for your program.
    • Your user. Bastion Compliance emails your user directly, and your user responds to Bastion Compliance.
  3. Show your user a notification that Bastion needs more information. If Bastion Compliance contacts your user directly, ask them to watch for an email from Bastion Compliance. If the identity is ACTIVE, keep the notification non-blocking, because the identity can still transact. If it is PENDING_ONBOARDING, keep the user in the pending state.
    • Don’t block your user on RFI_REQUIRED alone. Money movement depends on status, so when Compliance needs to stop an identity from transacting, it suspends the identity.
  4. When the RFI has been adequately completed, you receive another identity_status_update that clears RFI_REQUIRED. If the RFI isn’t resolved, Bastion can suspend the identity.

Account

An Account belongs to an Identity and is the operational unit for financial activity. This is where balances live, transactions originate, and wallet addresses are managed. Key properties of an Account:

account.status values

How identities and accounts relate

An Identity owns one or more Accounts. Each Account has its own balances, wallet addresses, and transaction history, isolated from other Accounts under the same Identity.
An identity record owns one or more accounts, each with its own balances, wallets, and transactions

Account types

Every account is one of two types. SEGREGATED accounts hold their own on-chain wallet addresses with chain-specific balances. OMNIBUS accounts pool funds in a custody vault, and Bastion tracks each account’s balance on an internal ledger. Both are fully custodial under Bastion’s US regulated licensing, and your platform uses the same APIs either way. See Custody for how each model holds assets and how balances are returned.

Common patterns for multiple accounts

Compliance

An Identity must pass compliance verification (KYC for individuals, KYB for businesses) before accounts can be created or financial operations can begin.
Identity lifecycle: create identity, submit compliance, await approval, create accounts, transact
  • Identity status must be ACTIVE before creating an account.
  • allowed_to_transact_fungibles must be true before submitting crypto transfers.
  • fiat_operations_enabled must be true before initiating on/off-ramp conversions.
  • Compliance requirements vary by jurisdiction and identity type. Business identities typically require more documentation (articles of incorporation, beneficial owner information).
  • Some operations may require additional verification even after initial approval.
For step-by-step onboarding instructions, see Onboard an individual customer or Onboard a business customer.