Trading Accounts

A Trading Account represents a connected exchange account that you can use to trade, view portfolios, and receive real-time updates.

Overview

A Trading Account is the link between your Cadenza account and a specific account on an exchange. Each trading account:

• Uses a Credential - Authenticates with the exchange using stored API keys
• Has a Type - Corresponds to an account type on the exchange (spot, margin, futures)
• Tracks Portfolio - Monitors balances and positions in real-time
• Executes Orders - Submits and manages trade orders

Trading Account Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Credential │────▶│   Connect   │────▶│   Active    │
│  (verified) │     │ (CONNECTED) │     │ (trading)   │
└─────────────┘     └─────────────┘     └─────────────┘
                                              │
                          ┌───────────────────┼───────────────────┐
                          ▼                   ▼                   ▼
                    ┌───────────┐       ┌───────────┐       ┌───────────┐
                    │  Disable  │       │  Enable   │       │Disconnect │
                    │ (DISABLED)│◀─────▶│ (ENABLED) │       │(REMOVED)  │
                    └───────────┘       └───────────┘       └───────────┘

The Trading Account Object

Field	Type	Description
tradingAccountId	UUID	Unique identifier for the trading account
externalTradingAccountId	string	Account identifier on the exchange (e.g., "spot", "futures")
venue	Venue	Exchange venue (BINANCE, OKX, BYBIT)
nickname	string	Display name for the account
accountType	AccountType	Type of account (SPOT, MARGIN, FUTURES)
externalAccountType	string	Account type as reported by the exchange
credentials	Credential[]	Associated credentials
status	TradingAccountStatus	Current status
positionMode	PositionMode	Position mode for derivatives (ONE_WAY, HEDGE)
marginMode	MarginMode	Margin mode (CROSS, ISOLATED)
createdAt	timestamp	When the account was connected
updatedAt	timestamp	When the account was last updated

Trading Account Status

Status	Description
CONNECTED	Account is connected and ready
ENABLED	Account is enabled for trading
DISABLED	Account is temporarily disabled
DISCONNECTED	Account has been disconnected
ERROR	Account encountered an error

Account Types

Type	Description	Venues
SPOT	Spot trading account	All
MARGIN	Margin trading account	BINANCE, OKX
FUTURES	USDT-margined futures	BINANCE, OKX, BYBIT
COIN_FUTURES	Coin-margined futures	BINANCE
UNIFIED	Unified trading account	OKX, BYBIT

Relationship Diagram

┌─────────────────────────────────────────────────────────────┐
│                         User                                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ owns
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Credentials                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Binance    │  │    OKX      │  │   Bybit     │         │
│  │  API Keys   │  │  API Keys   │  │  API Keys   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ authenticates
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Trading Accounts                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Binance    │  │  Binance    │  │    OKX      │         │
│  │   Spot      │  │  Futures    │  │  Unified    │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ contains
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        Portfolio                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Balances   │  │  Positions  │  │   Orders    │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

Next Steps

• Connect a Trading Account - Link your exchange account
• Manage Trading Accounts - Enable, disable, and disconnect
• View Portfolio - Check balances and positions

Prerequisites

Before connecting a trading account, you must:

1. Create a Credential with your exchange API keys
2. Verify the Credential to discover available accounts