API Introduction
Wealth2B provides an institutional investment API that enables fintechs and neobanks to launch regulated products in the U.S.
Our infrastructure unifies advisory, custody, and execution, simplifying access to interest-bearing accounts, real-time trading, and automated portfolios.
Documented Environment
Complete staging environment with Swagger documentation for testing and integration.
Secure Authentication
JWT-based authentication with API key and secret for secure access to all endpoints.
Real-time Data
WebSocket connections for live market data and webhook events for system updates.
Overview: How Integration Works
This overview walks you through the main steps to integrate the Wealth2B API and offer investments from your own app. It explains how onboarding, account setup, funding, and product activation connect into one seamless flow.
Register and verify identity (KYC)
Every integration begins by creating a client profile and completing KYC. There are two possible paths for this step.
Create the person record, then upload supporting documents.
If your platform already collects user identity data, simply pass it through our API.
If all requirements are met, approval is typically instant · Monitor KYC/approval updates via webhooks (People status events).
Open investment account
Once the user is verified, create a dedicated investment account. This step also defines which product type the account will support.
- Savings (FDIC Yield Account) – Earns daily interest from the moment funds arrive, with full liquidity.
- Robo-advisor (Managed Portfolio) – Wealth2B automatically allocates and rebalances according to the user’s profile.
- Trading (Self-Directed) – The user operates directly, but under real-time supervision and compliance rules.
Accounts are created with POST /accounts. Accounts can also be closed when needed via POST /accounts/{id}/close.
Fund the account
Before any investment activity, users must deposit funds. First, link a same-name bank account with POST /bank-accounts. Then initiate deposits or withdrawals using POST /money-movements.
Supported transfer methods depend on your configuration (INSTANT, ACH, Wire, SWIFT). In some cases, internal transfers can be used via POST /internal-transfers. → Read more about funding options
Supported paymentType values include ACH, WIRE (BIC/ABA), and TRAVEL_RULE. For instant funding scenarios, you can create simulated funding via POST /money-movements.
Product activation logic
Depending on the product assigned to each account, different activation actions can be performed. Review the corresponding logic below for each product type.
Savings (FDIC Yield Account)
Once funds are settled, the account automatically starts generating daily yield. No further action is required.
Robo Advisor - Automated Portfolio Management
The Robo Advisor automates investment management by matching each client with an appropriate portfolio based on risk preferences. Once assigned, Wealth2B handles rebalancing, monitoring, and reporting automatically.
1. Define the client’s risk level — Determine the level of risk each client is willing to take (consult our team about available risk profiling options).
2. Retrieve available portfolios — List all available portfolios and review their characteristics using:
3. Inspect underlying funds (optional) — Check the list of individual funds or ETFs that can appear in portfolios:
4. Assign a portfolio to the client’s account — Create a new association between a client’s Robo Advisor account and a chosen portfolio:
Once a portfolio is assigned, the Robo Advisor automatically executes periodic rebalancing according to target weights and market data.
5. Review plan and historical associations — Retrieve the client’s current and past portfolio assignments:
Trading - Market Orders
The Trading API enables real-time execution and monitoring of market operations while ensuring full regulatory supervision. The process follows four sequential steps:
1. Access market data — Retrieve detailed and historical information about available assets before placing trades.
2. Place and manage orders — Allow users to open, cancel, or review trading orders directly through your app’s interface.
3. Monitor positions — Access open or closed positions to display live portfolio data and unrealized P&L.
Reporting and documents
Your app can retrieve both operational and client-facing information through the Reporting API. These endpoints allow you to query transactions, settlements, and documents — or enable users to download investment statements directly from your UI.
Operational data
Use these endpoints to retrieve transactional and system-level records for reporting or reconciliation.
Client-facing documents
Use this endpoint to let users download official investment statements and reports directly from your interface.
All reports and documents are available in real time and can be filtered by client, account, or date range.
Documented Environment
Base URL (staging)
Swagger URL (staging)
Authentication
Login Process
Requires apiKey and apiSecret. Returns a JWT (access_token).
Returns user information if the token is valid.
Important
All endpoints require Bearer Token (JWT) in the Authorization header.
Functional Relationships Map
| Category | Workflow | Description |
|---|---|---|
| Onboarding | People registration | Create people (/people), open investment account (/accounts), upload KYC documents, store KYC information. |
| Identity verification | Use /people/{peopleId}/kyc or /people/{peopleId}/kyc-raw for external verification data. | |
| Funding | ACH / WIRE funding | Add bank account (/bank-accounts), then create transfer (/money-movements). |
| Instant funding | Create simulated funding via POST /money-movements. | |
| Internal transfers | Move funds between accounts via /internal-transfers. | |
| Trading | Market data lookup | List assets (/market-data/assets), get details (/market-data/assets/{symbol}), fetch latest prices (/market-data/latest-prices), fetch historical data (/market-data/historical). |
| Real-time streaming | Generate WebSocket token (/market-data/generate-websocket-token) and connect to wss://api.staging.wealth2b.com/market-data. | |
| Place order | Submit orders (/trading/orders). | |
| Manage orders | Get order details (/trading/orders/orders/{id}), cancel active order (/trading/orders/accounts/{accountId}/orders/{id}/cancel). | |
| Positions | Get all positions (/trading/positions), by ID (/trading/positions/{id}), by account (/trading/positions/accounts/{accountId}), by symbol (/trading/positions/accounts/{accountId}/{symbol}), close position (/trading/positions/accounts/{accountId}/positions/{symbol}/close). | |
| Robo Advisor | Funds | Retrieve all available funds with details and weights (/robo-advisor/funds). Retrieve a single fund by ID (/robo-advisor/funds/{id}). |
| Portfolios | Retrieve all portfolios (/robo-advisor/portfolios), get by ID (/robo-advisor/portfolios/{id}), flatten portfolio (/robo-advisor/portfolios/{id}/flatten), generate projections (/robo-advisor/projections). | |
| Association / Plan | Link account to portfolio (/robo-advisor/associations), end association (/robo-advisor/associations/{id}/end), get active plan (/robo-advisor/accounts/{accountId}/plan), get plan history (/robo-advisor/accounts/{accountId}/plan/history). | |
| Accounts | Open/close account | Create (/accounts), close (/accounts/{id}/close). |
| Reports | Transactions | Search movements (/money-movements/search), list settlements (/settlements/search). |
| Settlement management | Confirm settlement (/settlements/{id}/confirm). | |
| Documents | Upload person documents (/people/documents), download (/people/documents/{id}/download). |
Functional Workflows
Services and Endpoints (by domain)
Auth
People
Accounts
Bank Accounts
Supported paymentType: ACH, WIRE (BIC/ABA), TRAVEL_RULE.
Money Movements
Internal Transfers
Market Data
Trading
Robo Advisor
Settlements
File
API Response Behavior
Wealth2B follows standard REST conventions.
Successful Responses
❌ Error Responses
All services return a consistent ErrorResponseDto structure with status, payload, and meta.
📡 Real-Time Market Data
Wealth2B provides real-time price updates via WebSocket.
Generate Token
Generate a WebSocket token for authentication.
POST /market-data/generate-websocket-tokenConnect to WebSocket
Connect to the real-time data stream.
Subscribe
emit "subscribe" with a list of symbols
Unsubscribe
emit "unsubscribe"
Events Received
Webhook Events
Webhook payloads have the following structure:
{
"timestamp": "2025-01-01T00:00:00.000Z",
"data": { /* Event-specific data */ },
"id": "event-uuid",
"type": "event_type"
}Event categories include:
NTA Events (Net Trading Asset)
fund movements such as instant funding or deposits.
Trading Events
order lifecycle updates.
Settlement Events
confirmations, reconciliations.
Account Status Events
changes in investment account states.
People Status Events
KYC/approval status updates.
Money Movement Status Events
deposit/withdrawal lifecycle.
Webhook Events & Payloads Specification
This document describes all the event types that your webhook endpoint may receive. Each event contains only the essential information for processing.
🏷️ Common Structure
{
"timestamp": "2025-01-01T00:00:00.000Z",
"data": { /* Event-specific data */ },
"id": "event-uuid",
"type": "event_type"
}1️⃣ NTA Events (Net Trading Asset)
Fund movements such as instant funding or deposits.
Example: Instant Funding
{
"timestamp": "2025-06-27T05:06:15.552Z",
"data": {
"accountId": "7a5cc3d6-f831-46b9-88bc-7512386217a6",
"amount": 11.25,
"status": "executed",
"entryType": "MEM"
},
"id": "08aab21a-4c38-49f6-80f6-2f4a0dc1d966",
"type": "nta"
}Fields:
💹 2️⃣ Trading Order Events
Related to full or partial order execution.
Example: Order Filled
{
"timestamp": "2025-01-01T00:00:00.000Z",
"data": {
"accountId": "account-uuid",
"symbol": "AAPL",
"orderId": "order-uuid",
"status": "filled",
"filledQty": "100",
"filledPrice": "150.75",
"side": "buy"
},
"id": "event-uuid",
"type": "trade"
}Fields:
3️⃣ Account Status Events
Changes in the status of an account.
Example: Account Approved
{
"timestamp": "2025-01-01T00:00:00.000Z",
"data": {
"accountId": "account-uuid",
"statusFrom": "PENDING",
"statusTo": "OPEN"
},
"id": "event-uuid",
"type": "account_status"
}Fields:
🧑💼 4️⃣ People Status Events
Changes in the status of a person.
Example: Person Approved
{
"timestamp": "2025-01-01T00:00:00.000Z",
"data": {
"peopleId": "people-uuid",
"statusFrom": "PENDING",
"statusTo": "APPROVED"
},
"id": "event-uuid",
"type": "people_status"
}Fields:
🏦 5️⃣ Money Movement Status Events
Represent changes in the status of money movements.
Example: Money Movement Completed
{
"timestamp": "2025-01-01T00:00:00.000Z",
"data": {
"accountId": "account-uuid",
"moneyMovementId": "money-movement-uuid",
"statusFrom": "APPROVED",
"statusTo": "SUCCESSFUL"
},
"id": "event-uuid",
"type": "money_movement_status"
}Fields:
🏦 6️⃣ Settlement Status Change Events
Represent changes in the status of settlements.
Example: Pending confirmation Settlement event (sent every business day at 6:00 PM GMT-3)
{
"timestamp": "2025-07-30T05:51:00.041Z",
"data": {
"settlementId": "9e2f6117-51d3-48b9-945d-419f9c733c3c",
"statusFrom": "open",
"statusTo": "pending_confirmation",
"amount": 3596.5
},
"id": "363e1709-4f2f-49bf-bb1f-2ed28f08d4e0",
"type": "settlement_status_changed"
}