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_statusreturns to the step the identity was at, or to the step it has reached since, for exampleIDV_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}/compliancereturns409ALREADY_EXISTS, andsub_statusdoesn’t change. - A change of
statuscan open or close an RFI. Readsub_statuson everyidentity_status_updatewebhook, including ones wherestatusdoesn’t change. Treat any value other thanRFI_REQUIREDas no open RFI.
What to expect when Bastion raises an RFI
- You receive an
identity_status_updatewebhook withsub_statusRFI_REQUIRED.GET /v2/identities/{identity_id}shows the same value if you miss the webhook. - 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.
- 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 isPENDING_ONBOARDING, keep the user in the pending state.- Don’t block your user on
RFI_REQUIREDalone. Money movement depends onstatus, so when Compliance needs to stop an identity from transacting, it suspends the identity.
- Don’t block your user on
- When the RFI has been adequately completed, you receive another
identity_status_updatethat clearsRFI_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.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
statusmust beACTIVEbefore creating an account. allowed_to_transact_fungiblesmust betruebefore submitting crypto transfers.fiat_operations_enabledmust betruebefore 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.
Related documentation
- Concepts
- Getting started
- API reference