Data Model: Wallet

Purpose: The Wallet entity stores an Investor's fiat ledger and links it to a Profile and the configured payment provider. It records funds available for Investments and related transfers.

Fields/Attributes

Name	Type	Description	Validation Rules
id	Unique Identifier	The primary internal system ID for the wallet.	• Required • System-generated
profile_id	Foreign Key	A reference to the Profile that owns this wallet.	• Required, Unique
status	Choice	The current verification and operational status of the wallet with the provider.	• Required • See Wallet Status Lifecycle for values.
balance	Currency	The current settled amount held in the wallet's persisted balance field.	• Required • Defaults to 0.00
inc_balance	Currency	The persisted pending-incoming amount for funds that have not yet settled into balance.	• Read-only • System-managed • Defaults to 0.00
out_balance	Currency	The persisted pending-outgoing reservation for funds committed to a withdrawal or wallet-funded investment.	• Read-only • System-managed • Defaults to 0.00
provider_customer_id	Text	The unique Customer ID for the user in the provider's system.	• Required, Unique
provider_source_id	Text	The unique ID for this wallet from the third-party provider's system (e.g., Dwolla's funding source ID).	• Required, Unique
created_at	Timestamp	The date and time the wallet record was created.	• Read-only
updated_at	Timestamp	The date and time the wallet was last modified.	• Read-only

Persistence and response names: The persisted wallet fields are balance, inc_balance, and out_balance. The wallet DTO exposes virtual_balance, pending_incoming_balance, and pending_outcoming_balance; pending_outcoming_balance is the DTO spelling and is not a persisted field.

Calculation or projection	Exact rule
Withdrawal availability	balance - out_balance
Wallet-funded investment capacity	balance + inc_balance - out_balance
DTO virtual_balance	balance + inc_balance - out_balance
DTO pending_incoming_balance	Projection of persisted inc_balance
DTO pending_outcoming_balance	Projection of persisted out_balance

Key Relationships

• Profile: A Wallet belongs to exactly one Profile (a one-to-one relationship).

• Transactions: A Wallet is the source or destination for many Transaction records, creating a full ledger history (a one-to-many relationship).

• Funding Sources: A Wallet can have multiple FundingSource records linked to it (a one-to-many relationship).

Global Business Rules

• A Wallet must only be created for a Profile after its kyc_status is approved.

• SDIRA profiles cannot have a Wallet.

• A Wallet cannot be used to send or receive funds until its status is verified.

• Each eligible Profile can have only one Wallet.

• A withdrawal uses the persisted withdrawal availability rule balance - out_balance.

• A wallet-funded investment uses the wallet API's investment capacity rule balance + inc_balance - out_balance.

• Funding Source Limit: A Wallet can have a maximum of 6 active FundingSource records linked at any given time.

Auditing & Event History

The system records significant actions or changes involving a Wallet as immutable entries in the system-wide EventLog.