Wealth2B API

Wealth2B API Introduction

Wealth2B offers an API platform that enables fintechs and neobanks to launch investment products in the U.S. Our infrastructure abstracts operational and regulatory complexity from the broker, offering interest-bearing accounts, real-time trading, and automated portfolio allocation.

🤖

Need Help?

Ask our AI Assistant about the documentation

💬Chat with AI↗
📋View Swagger↗
🌐

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.

🌍 Documented Environment

🖥️

Base URL (staging)

https://api.staging.wealth2b.com

Swagger URL (staging)

https://swagger.staging.wealth2b.com

🔐 Authentication

Login Process

POST /auth/login

Requires apiKey and apiSecret. Returns a JWT (access_token).

GET /auth/profile

Returns user information if the token is valid.

Important

All endpoints require Bearer Token (JWT) in the Authorization header.

Functional Workflows

CategoryWorkflowDescription
👤 OnboardingPeople registrationCreate people (/people), open investment account (/accounts), upload KYC documents, store KYC information.
Identity verificationUse /people/{peopleId}/kyc or /people/{peopleId}/kyc-raw for external verification data.
💸 FundingACH / WIRE fundingAdd bank account (/bank-accounts), then create transfer (/money-movements).
Instant fundingCreate simulated funding via POST /money-movements.
Internal transfersMove funds between accounts via /internal-transfers.
📈 TradingMarket data lookupList 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 streamingGenerate WebSocket token (/market-data/generate-websocket-token) and connect to wss://api.staging.wealth2b.com/market-data.
Place orderSubmit orders (/trading/orders).
Manage ordersGet order details (/trading/orders/orders/{id}), cancel active order (/trading/orders/accounts/{accountId}/orders/{id}/cancel).
PositionsGet 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 AdvisorFundsRetrieve all available funds with details and weights (/robo-advisor/funds). Retrieve a single fund by ID (/robo-advisor/funds/{id}).
PortfoliosRetrieve 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 / PlanLink 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).
🛠 AccountsOpen/close accountCreate (/accounts), close (/accounts/{id}/close).
📄 ReportsTransactionsSearch movements (/money-movements/search), list settlements (/settlements/search).
Settlement managementConfirm settlement (/settlements/{id}/confirm).
DocumentsUpload person documents (/people/documents), download (/people/documents/{id}/download).

🗺 Functional Relationships Map

peoplemany accounts(accounts reference peopleId)
peoplemany bank accounts(bank accounts reference peopleId)
accountmany money movements(reference accountId)
accountmany orders and positions
peoplemany documents→ use /file/{documentId}/download to retrieve files

👤 Account Opening - People and Investment Accounts

The account opening flow follows this sequence:

1

Create Person

Submit initial data using /people.

POST /people
2

Upload KYC Data

Provide supporting documentation. Optionally use /people/{peopleId}/kyc or /people/{peopleId}/kyc-raw to store verification data.

POST /people/documentsPOST /people/{peopleId}/kycPOST /people/{peopleId}/kyc-raw
3

Approval Process

Person is reviewed and approved for account opening.

Automatic
4

Create Accounts

Create one or multiple accounts for the approved person.

POST /accounts

1. Create Person

POST /people

2. Upload Document

POST /people/documents (multipart/form-data)

3. Create Investment Account

POST /accounts

💸 Funding - ACH or WIRE Transfer

1

Create Bank Account

Add bank account information for the user.

POST /bank-accounts
2

Create Money Movement (Deposit)

Initiate the transfer from the bank account to the investment account.

POST /money-movements

💰 Settlements - Instant Funding Batches

View Settlement Detail

Get detailed information about a specific settlement.

GET /settlements/{settlementId}

Confirm Settlement

Confirm and finalize a settlement batch.

POST /settlements/{settlementId}/confirm

🛒 Trading - Market Orders

1

Place Market Order

Submit a new trading order.

POST /trading/orders
2

View Order Details

Get detailed information about an order.

GET /trading/orders/orders/{id}
3

Cancel Pending Order

Cancel an active order.

POST /trading/orders/accounts/{accountId}/orders/{id}/cancel

🤖 Robo Advisor - Automated Portfolio Management

The Robo Advisor module provides endpoints to define, query, and link automated investment portfolios to customer accounts.

1. Funds

Retrieve all funds with details and weights.

GET /robo-advisor/fundsGET /robo-advisor/funds/{id}

2. Portfolios

List, retrieve and flatten portfolios; generate growth projections.

GET /robo-advisor/portfoliosGET /robo-advisor/portfolios/{id}GET /robo-advisor/portfolios/{id}/flattenPOST /robo-advisor/projections

3. Associations

Create and end account-portfolio associations.

POST /robo-advisor/associationsPATCH /robo-advisor/associations/{id}/end

4. Account Plans

Retrieve active investment plan and full history.

GET /robo-advisor/accounts/{accountId}/planGET /robo-advisor/accounts/{accountId}/plan/history

🧩 Services and Endpoints (by domain)

🔒

Auth

POST/auth/login
GET/auth/profile
👥

People

POST/people
GET/people/search
GET/people/{id}
DELETE/people/{id}
POST/people/{peopleId}/kyc
POST/people/{peopleId}/kyc-raw
GET/people/{id}/documents
GET/people/{id}/accounts
GET/people/{id}/bank-accounts
POST/people/documents
GET/people/documents/{id}/download
🏦

Accounts

POST/accounts
GET/accounts/{id}
PATCH/accounts/{id}
POST/accounts/{id}/close
💰

Bank Accounts

POST/bank-accounts
GET/bank-accounts/{id}
DELETE/bank-accounts/{id}

Supported paymentType: ACH, WIRE (BIC/ABA), TRAVEL_RULE.

➡️

Money Movements

POST/money-movements
GET/money-movements/search
GET/money-movements/{id}
DELETE/money-movements/{id}
🔄

Internal Transfers

POST/internal-transfers
GET/internal-transfers/search
GET/internal-transfers/{id}
DELETE/internal-transfers/{id}
📈

Market Data

GET/market-data/assets
GET/market-data/assets/{symbol}
GET/market-data/latest-prices
GET/market-data/historical
POST/market-data/generate-websocket-token
📈

Trading

POST/trading/orders
GET/trading/orders/orders/{id}
POST/trading/orders/accounts/{accountId}/orders/{id}/cancel
GET/trading/positions
GET/trading/positions/{id}
GET/trading/positions/accounts/{accountId}
GET/trading/positions/accounts/{accountId}/{symbol}
POST/trading/positions/accounts/{accountId}/positions/{symbol}/close
🤖

Robo Advisor

GET/robo-advisor/funds
GET/robo-advisor/funds/{id}
GET/robo-advisor/portfolios
GET/robo-advisor/portfolios/{id}
GET/robo-advisor/portfolios/{id}/flatten
POST/robo-advisor/projections
POST/robo-advisor/associations
PATCH/robo-advisor/associations/{id}/end
GET/robo-advisor/accounts/{accountId}/plan
GET/robo-advisor/accounts/{accountId}/plan/history
⏳

Settlements

GET/settlements/search
GET/settlements/{id}
POST/settlements/{id}/confirm
📄

File

GET/file/{documentId}/download

📦 API Response Behavior

Wealth2B follows standard REST conventions.

✅ Successful Responses

200 OKRequest was successful, response contains requested data.
201 CreatedResource successfully created.
204 No ContentRequest was successful, no content returned (e.g., after delete).

❌ Error Responses

400Bad Request - Invalid input, missing fields
401Unauthorized - Missing/invalid token
403Forbidden - Insufficient permissions
404Not Found - Resource missing
422Unprocessable Entity - Business logic failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Unexpected backend failure

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-token

Connect to WebSocket

Connect to the real-time data stream.

wss://api.staging.wealth2b.com/market-data

Subscribe

emit "subscribe" with a list of symbols

Unsubscribe

emit "unsubscribe"

Events Received

marketDataprice update for a symbol
connectedacknowledgment of connection
pongheartbeat response

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"
}
timestamp: UTC datetime ISO8601
data: Event data
id: Unique UUID for idempotency
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"
}
timestamp: UTC date/time in ISO8601 format.
data: Main event object.
id: Unique UUID for idempotency.
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:

accountId: Unique account ID.
amount: Amount.
status: executed, pending, failed.
entryType: Movement type code (e.g. MEM).

💹 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:

symbol: Asset symbol.
orderId: Order ID.
status: filled, partially_filled, canceled, rejected.
filledQty: Executed quantity.
filledPrice: Average price.
side: buy or sell.

👤 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:

statusFrom: Previous status.
statusTo: New status.

🧑‍💼 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:

peopleId: Unique person ID.
statusFrom: Previous status.
statusTo: New status.

🏦 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:

moneyMovementId: Unique ID of the money movement.
statusFrom: Previous status.
statusTo: New status.

🏦 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"
}

Fields:

settlementId: Unique ID of the settlement.
statusFrom: Previous status.
statusTo: New status.
amount: Total netting amount that must be "Confirmed".