Portfolio

View balances and positions for your connected trading accounts.

Overview

A Portfolio represents the current state of a trading account, including:

• Balances - Available and locked amounts of each asset
• Positions - Open positions for derivatives accounts (futures, margin)

Portfolios are synced in real-time from the exchange.

The Portfolio Object

Field	Type	Description
tradingAccountId	UUID	Trading account identifier
venue	Venue	Exchange venue
balances	BalanceEntry[]	List of asset balances
positions	PositionEntry[]	List of open positions (derivatives only)
updatedAt	timestamp	Last sync time

Balance Entry

Field	Type	Description
asset	string	Asset symbol (e.g., "BTC", "USDT")
free	decimal	Available balance for trading
locked	decimal	Balance locked in open orders
total	decimal	Total balance (free + locked)

Position Entry (Derivatives)

Field	Type	Description
instrumentId	string	Instrument identifier
side	PositionSide	Position side (LONG, SHORT)
quantity	decimal	Position size
entryPrice	decimal	Average entry price
markPrice	decimal	Current mark price
unrealizedPnl	decimal	Unrealized profit/loss
leverage	integer	Position leverage
marginType	MarginMode	Margin type (CROSS, ISOLATED)

List Portfolios

Retrieve portfolios for one or more trading accounts:

Python

response = portfolio_api.list_trading_account_portfolios(
    trading_account_id=trading_account_id
)

for portfolio in response.data:
    print(f"Account: {portfolio.trading_account_id}")
    print(f"Venue: {portfolio.venue}")

    print("Balances:")
    for balance in portfolio.balances:
        if float(balance.total) > 0:
            print(f"  {balance.asset}:")
            print(f"    Free: {balance.free}")
            print(f"    Locked: {balance.locked}")
            print(f"    Total: {balance.total}")

TypeScript

const response = await portfolioApi.listTradingAccountPortfolios(
  tradingAccountId
)

response.data.data.forEach(portfolio => {
  console.log(`Account: ${portfolio.tradingAccountId}`)
  console.log(`Venue: ${portfolio.venue}`)

  console.log('Balances:')
  portfolio.balances?.forEach(balance => {
    if (parseFloat(balance.total || '0') > 0) {
      console.log(`  ${balance.asset}:`)
      console.log(`    Free: ${balance.free}`)
      console.log(`    Locked: ${balance.locked}`)
      console.log(`    Total: ${balance.total}`)
    }
  })
})

Go

response, _, err := apiClient.TradingAccountPortfolioAPI.ListTradingAccountPortfolios(ctx).
    TradingAccountId(tradingAccountId).
    Execute()
if err != nil {
    panic(err)
}

for _, portfolio := range response.Data {
    fmt.Printf("Account: %s\n", *portfolio.TradingAccountId)
    fmt.Printf("Venue: %s\n", *portfolio.Venue)

    fmt.Println("Balances:")
    for _, balance := range portfolio.Balances {
        total, _ := strconv.ParseFloat(*balance.Total, 64)
        if total > 0 {
            fmt.Printf("  %s:\n", *balance.Asset)
            fmt.Printf("    Free: %s\n", *balance.Free)
            fmt.Printf("    Locked: %s\n", *balance.Locked)
            fmt.Printf("    Total: %s\n", *balance.Total)
        }
    }
}

Filter by Currency

Get balance for a specific asset:

Python

response = portfolio_api.list_trading_account_portfolios(
    trading_account_id=trading_account_id,
    currency="USDT"
)

for portfolio in response.data:
    for balance in portfolio.balances:
        print(f"USDT Balance: {balance.total}")

TypeScript

const response = await portfolioApi.listTradingAccountPortfolios(
  tradingAccountId,
  undefined,  // venue
  'USDT'      // currency
)

response.data.data.forEach(portfolio => {
  portfolio.balances?.forEach(balance => {
    console.log(`USDT Balance: ${balance.total}`)
  })
})

Go

currency := "USDT"
response, _, err := apiClient.TradingAccountPortfolioAPI.ListTradingAccountPortfolios(ctx).
    TradingAccountId(tradingAccountId).
    Currency(currency).
    Execute()
if err != nil {
    panic(err)
}

for _, portfolio := range response.Data {
    for _, balance := range portfolio.Balances {
        fmt.Printf("USDT Balance: %s\n", *balance.Total)
    }
}

Filter by Venue

Get portfolios for all accounts on a specific exchange:

Python

response = portfolio_api.list_trading_account_portfolios(
    venue=cadenza_client.Venue.BINANCE
)

for portfolio in response.data:
    print(f"Account: {portfolio.trading_account_id}")

TypeScript

const response = await portfolioApi.listTradingAccountPortfolios(
  undefined,  // tradingAccountId
  'BINANCE'   // venue
)

response.data.data.forEach(portfolio => {
  console.log(`Account: ${portfolio.tradingAccountId}`)
})

Go

venue := client.VENUE_BINANCE
response, _, err := apiClient.TradingAccountPortfolioAPI.ListTradingAccountPortfolios(ctx).
    Venue(venue).
    Execute()
if err != nil {
    panic(err)
}

for _, portfolio := range response.Data {
    fmt.Printf("Account: %s\n", *portfolio.TradingAccountId)
}

Positions (Derivatives)

For futures and margin accounts, the portfolio includes position information:

Python

response = portfolio_api.list_trading_account_portfolios(
    trading_account_id=futures_account_id
)

for portfolio in response.data:
    print("Positions:")
    for position in portfolio.positions or []:
        print(f"  {position.instrument_id}:")
        print(f"    Side: {position.side}")
        print(f"    Size: {position.quantity}")
        print(f"    Entry Price: {position.entry_price}")
        print(f"    Mark Price: {position.mark_price}")
        print(f"    Unrealized PnL: {position.unrealized_pnl}")
        print(f"    Leverage: {position.leverage}x")

TypeScript

const response = await portfolioApi.listTradingAccountPortfolios(
  futuresAccountId
)

response.data.data.forEach(portfolio => {
  console.log('Positions:')
  portfolio.positions?.forEach(position => {
    console.log(`  ${position.instrumentId}:`)
    console.log(`    Side: ${position.side}`)
    console.log(`    Size: ${position.quantity}`)
    console.log(`    Entry Price: ${position.entryPrice}`)
    console.log(`    Mark Price: ${position.markPrice}`)
    console.log(`    Unrealized PnL: ${position.unrealizedPnl}`)
    console.log(`    Leverage: ${position.leverage}x`)
  })
})

Go

response, _, err := apiClient.TradingAccountPortfolioAPI.ListTradingAccountPortfolios(ctx).
    TradingAccountId(futuresAccountId).
    Execute()
if err != nil {
    panic(err)
}

for _, portfolio := range response.Data {
    fmt.Println("Positions:")
    for _, position := range portfolio.Positions {
        fmt.Printf("  %s:\n", *position.InstrumentId)
        fmt.Printf("    Side: %s\n", *position.Side)
        fmt.Printf("    Size: %s\n", *position.Quantity)
        fmt.Printf("    Entry Price: %s\n", *position.EntryPrice)
        fmt.Printf("    Mark Price: %s\n", *position.MarkPrice)
        fmt.Printf("    Unrealized PnL: %s\n", *position.UnrealizedPnl)
        fmt.Printf("    Leverage: %dx\n", *position.Leverage)
    }
}

Response Example

{
  "data": [
    {
      "tradingAccountId": "660e8400-e29b-41d4-a716-446655440000",
      "venue": "BINANCE",
      "balances": [
        {
          "asset": "BTC",
          "free": "0.50000000",
          "locked": "0.10000000",
          "total": "0.60000000"
        },
        {
          "asset": "USDT",
          "free": "10000.00000000",
          "locked": "500.00000000",
          "total": "10500.00000000"
        }
      ],
      "positions": [],
      "updatedAt": 1704153600000
    }
  ],
  "success": true,
  "errno": 0,
  "error": null
}

Real-time Updates

For real-time portfolio updates, subscribe to the trading account WebSocket channel:

Python

from cadenza_client.ws import Client

client = Client(WS_URL, token=access_token)
await client.connect()

sub = client.new_subscription(f"tradingAccount:{trading_account_id}")

def on_publication(ctx):
    data = ctx.data
    if data.get("type") == "portfolioUpdatedEvent":
        portfolio = data["data"]
        print(f"Portfolio updated: {portfolio}")

sub.on_publication(on_publication)
await sub.subscribe()

TypeScript

const sub = client.newSubscription(`tradingAccount:${tradingAccountId}`)

sub.on('publication', (ctx) => {
  const data = ctx.data
  if (data.type === 'portfolioUpdatedEvent') {
    const portfolio = data.data
    console.log('Portfolio updated:', portfolio)
  }
})

sub.subscribe()

Go

sub, _ := client.NewSubscription(fmt.Sprintf("tradingAccount:%s", tradingAccountId))

sub.OnPublication(func(e centrifuge.PublicationEvent) {
    var data map[string]interface{}
    json.Unmarshal(e.Data, &data)

    if data["type"] == "portfolioUpdatedEvent" {
        portfolio := data["data"]
        fmt.Printf("Portfolio updated: %v\n", portfolio)
    }
})

sub.Subscribe()

See the Quick Start for WebSocket setup and real-time subscriptions.

Related

• Connect a Trading Account
• Manage Trading Accounts
• Trading