Quickstart

This guide walks through creating an investment portfolio, adding a holding, recording a trade, checking portfolio performance, and rebalancing using the REST API.

Prerequisites

• A Kora Wealth Management account (sign up)
• Your API key (starts with test_ for sandbox)
• Your Tenant ID (UUID from your dashboard)

Step 1: Create a portfolio

Define the portfolio with a target allocation and investment mandate.

cURL

curl -X POST https://api.korastratum.com/wealth-management/api/v1/portfolios \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "X-Tenant-ID: $WM_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Growth Portfolio",
    "currency": "USD",
    "mandate": "DISCRETIONARY",
    "risk_profile": "MODERATE_AGGRESSIVE",
    "target_allocation": {
      "equities": 60,
      "fixed_income": 25,
      "alternatives": 10,
      "cash": 5
    }
  }'

Node.js

const response = await fetch("https://api.korastratum.com/wealth-management/api/v1/portfolios", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.WM_API_KEY}`,
    "X-Tenant-ID": process.env.WM_TENANT_ID,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_id: "550e8400-e29b-41d4-a716-446655440000",
    name: "Growth Portfolio",
    currency: "USD",
    mandate: "DISCRETIONARY",
    risk_profile: "MODERATE_AGGRESSIVE",
    target_allocation: {
      equities: 60,
      fixed_income: 25,
      alternatives: 10,
      cash: 5,
    },
  }),
});

const portfolio = await response.json();
console.log(portfolio.id); // "a1b2c3d4-..."

Python

import requests
import os

response = requests.post(
    "https://api.korastratum.com/wealth-management/api/v1/portfolios",
    headers={
        "Authorization": f"Bearer {os.environ['WM_API_KEY']}",
        "X-Tenant-ID": os.environ["WM_TENANT_ID"],
    },
    json={
        "customer_id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Growth Portfolio",
        "currency": "USD",
        "mandate": "DISCRETIONARY",
        "risk_profile": "MODERATE_AGGRESSIVE",
        "target_allocation": {
            "equities": 60,
            "fixed_income": 25,
            "alternatives": 10,
            "cash": 5,
        },
    },
)

portfolio = response.json()
print(portfolio["id"])  # "a1b2c3d4-..."

Go

req := wealth.CreatePortfolioRequest{
    CustomerID:  "550e8400-e29b-41d4-a716-446655440000",
    Name:        "Growth Portfolio",
    Currency:    "USD",
    Mandate:     "DISCRETIONARY",
    RiskProfile: "MODERATE_AGGRESSIVE",
    TargetAllocation: map[string]float64{
        "equities":     60,
        "fixed_income": 25,
        "alternatives": 10,
        "cash":         5,
    },
}
portfolio, err := client.CreatePortfolio(ctx, req)
fmt.Println(portfolio.ID) // "a1b2c3d4-..."

Save the returned id — you'll use it for all subsequent operations.

Step 2: Record a trade

Add a holding to the portfolio by recording a buy trade.

cURL

curl -X POST https://api.korastratum.com/wealth-management/api/v1/portfolios/$PORTFOLIO_ID/trades \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "X-Tenant-ID: $WM_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "instrument_id": "AAPL",
    "instrument_type": "EQUITY",
    "side": "BUY",
    "quantity": 100,
    "price": 185.50,
    "currency": "USD",
    "trade_date": "2026-04-07T14:30:00Z",
    "settlement_date": "2026-04-09T00:00:00Z"
  }'

Node.js

const trade = await fetch(
  `https://api.korastratum.com/wealth-management/api/v1/portfolios/${portfolioId}/trades`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.WM_API_KEY}`,
      "X-Tenant-ID": process.env.WM_TENANT_ID,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instrument_id: "AAPL",
      instrument_type: "EQUITY",
      side: "BUY",
      quantity: 100,
      price: 185.50,
      currency: "USD",
      trade_date: "2026-04-07T14:30:00Z",
      settlement_date: "2026-04-09T00:00:00Z",
    }),
  }
);

const result = await trade.json();
console.log(result.trade_id); // "t1a2b3c4-..."

Python

trade = requests.post(
    f"https://api.korastratum.com/wealth-management/api/v1/portfolios/{portfolio_id}/trades",
    headers={
        "Authorization": f"Bearer {os.environ['WM_API_KEY']}",
        "X-Tenant-ID": os.environ["WM_TENANT_ID"],
    },
    json={
        "instrument_id": "AAPL",
        "instrument_type": "EQUITY",
        "side": "BUY",
        "quantity": 100,
        "price": 185.50,
        "currency": "USD",
        "trade_date": "2026-04-07T14:30:00Z",
        "settlement_date": "2026-04-09T00:00:00Z",
    },
)

result = trade.json()
print(result["trade_id"])  # "t1a2b3c4-..."

Go

result, err := client.RecordTrade(ctx, portfolioID, wealth.TradeRequest{
    InstrumentID:   "AAPL",
    InstrumentType: "EQUITY",
    Side:           "BUY",
    Quantity:       100,
    Price:          185.50,
    Currency:       "USD",
    TradeDate:      time.Date(2026, 4, 7, 14, 30, 0, 0, time.UTC),
    SettlementDate: time.Date(2026, 4, 9, 0, 0, 0, 0, time.UTC),
})
fmt.Println(result.TradeID) // "t1a2b3c4-..."

Step 3: View portfolio holdings

cURL

curl https://api.korastratum.com/wealth-management/api/v1/portfolios/$PORTFOLIO_ID/holdings \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "X-Tenant-ID: $WM_TENANT_ID"

Node.js

const holdings = await fetch(
  `https://api.korastratum.com/wealth-management/api/v1/portfolios/${portfolioId}/holdings`,
  {
    headers: {
      "Authorization": `Bearer ${process.env.WM_API_KEY}`,
      "X-Tenant-ID": process.env.WM_TENANT_ID,
    },
  }
);

const data = await holdings.json();
console.log(data.data.length);                // 1
console.log(data.data[0].instrument_id);      // "AAPL"
console.log(data.data[0].market_value);       // 18550.00

Python

holdings = requests.get(
    f"https://api.korastratum.com/wealth-management/api/v1/portfolios/{portfolio_id}/holdings",
    headers={
        "Authorization": f"Bearer {os.environ['WM_API_KEY']}",
        "X-Tenant-ID": os.environ["WM_TENANT_ID"],
    },
)

data = holdings.json()
print(len(data["data"]))                # 1
print(data["data"][0]["instrument_id"])  # "AAPL"
print(data["data"][0]["market_value"])   # 18550.00

Go

holdings, err := client.GetHoldings(ctx, portfolioID)
fmt.Println(len(holdings))              // 1
fmt.Println(holdings[0].InstrumentID)   // "AAPL"
fmt.Println(holdings[0].MarketValue)    // 18550.00

Step 4: Check portfolio performance

cURL

curl "https://api.korastratum.com/wealth-management/api/v1/portfolios/$PORTFOLIO_ID/performance?period=MTD" \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "X-Tenant-ID: $WM_TENANT_ID"

Node.js

const perf = await fetch(
  `https://api.korastratum.com/wealth-management/api/v1/portfolios/${portfolioId}/performance?period=MTD`,
  {
    headers: {
      "Authorization": `Bearer ${process.env.WM_API_KEY}`,
      "X-Tenant-ID": process.env.WM_TENANT_ID,
    },
  }
);

const data = await perf.json();
console.log(data.twr_return);      // 0.0234 (2.34%)
console.log(data.mwr_return);      // 0.0228
console.log(data.total_value);     // 19025.00

Python

perf = requests.get(
    f"https://api.korastratum.com/wealth-management/api/v1/portfolios/{portfolio_id}/performance",
    headers={
        "Authorization": f"Bearer {os.environ['WM_API_KEY']}",
        "X-Tenant-ID": os.environ["WM_TENANT_ID"],
    },
    params={"period": "MTD"},
)

data = perf.json()
print(data["twr_return"])      # 0.0234 (2.34%)
print(data["mwr_return"])      # 0.0228
print(data["total_value"])     # 19025.00

Go

perf, err := client.GetPerformance(ctx, portfolioID, wealth.PerformanceFilter{
    Period: "MTD",
})
fmt.Println(perf.TWRReturn)   // 0.0234
fmt.Println(perf.MWRReturn)   // 0.0228
fmt.Println(perf.TotalValue)  // 19025.00

Step 5: Generate rebalancing proposal

cURL

curl -X POST https://api.korastratum.com/wealth-management/api/v1/portfolios/$PORTFOLIO_ID/rebalance \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "X-Tenant-ID: $WM_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "PROPOSAL",
    "tolerance_pct": 5.0
  }'

Node.js

const rebalance = await fetch(
  `https://api.korastratum.com/wealth-management/api/v1/portfolios/${portfolioId}/rebalance`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.WM_API_KEY}`,
      "X-Tenant-ID": process.env.WM_TENANT_ID,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      mode: "PROPOSAL",
      tolerance_pct: 5.0,
    }),
  }
);

const data = await rebalance.json();
console.log(data.proposed_trades.length); // 3
console.log(data.drift_pct);             // 8.2

Python

rebalance = requests.post(
    f"https://api.korastratum.com/wealth-management/api/v1/portfolios/{portfolio_id}/rebalance",
    headers={
        "Authorization": f"Bearer {os.environ['WM_API_KEY']}",
        "X-Tenant-ID": os.environ["WM_TENANT_ID"],
    },
    json={
        "mode": "PROPOSAL",
        "tolerance_pct": 5.0,
    },
)

data = rebalance.json()
print(len(data["proposed_trades"]))  # 3
print(data["drift_pct"])            # 8.2

Go

proposal, err := client.Rebalance(ctx, portfolioID, wealth.RebalanceRequest{
    Mode:         "PROPOSAL",
    TolerancePct: 5.0,
})
fmt.Println(len(proposal.ProposedTrades)) // 3
fmt.Println(proposal.DriftPct)            // 8.2

What's next

• Authentication — API key formats, environments, and rate limits
• API Reference — Explore every endpoint across all wealth management services