Connect a Trading Account

Connect an exchange account to Cadenza using a verified credential.

Prerequisites

Before connecting a trading account:

1. Create a Credential with your exchange API keys
2. Verify the Credential to get the list of available identities

Connect Trading Account

Use the credential ID and an external trading account ID (from the verification response):

Python

response = trading_account_api.connect_trading_account(
    cadenza_client.ConnectTradingAccountRequest(
        credential_ids=[credential_id],
        external_trading_account_id="spot",
        nickname="My Binance Spot"  # optional
    )
)

account = response.data
trading_account_id = account.trading_account_id
print(f"Connected: {trading_account_id}")
print(f"Venue: {account.venue}")
print(f"Account Type: {account.account_type}")
print(f"Status: {account.status}")

TypeScript

const response = await tradingAccountApi.connectTradingAccount({
  credentialIds: [credentialId],
  externalTradingAccountId: 'spot',
  nickname: 'My Binance Spot',  // optional
})

const account = response.data.data
const tradingAccountId = account.tradingAccountId
console.log('Connected:', tradingAccountId)
console.log('Venue:', account.venue)
console.log('Account Type:', account.accountType)
console.log('Status:', account.status)

Go

response, _, err := apiClient.TradingAccountAPI.ConnectTradingAccount(ctx).
    ConnectTradingAccountRequest(client.ConnectTradingAccountRequest{
        CredentialIds:            []string{credentialId},
        ExternalTradingAccountId: "spot",
        Nickname:                 client.PtrString("My Binance Spot"),
    }).Execute()
if err != nil {
    panic(err)
}

account := response.Data
tradingAccountId := *account.TradingAccountId
fmt.Printf("Connected: %s\n", tradingAccountId)
fmt.Printf("Venue: %s\n", *account.Venue)
fmt.Printf("Account Type: %s\n", *account.AccountType)
fmt.Printf("Status: %s\n", *account.Status)

Request Parameters

Parameter	Type	Required	Description
credentialIds	UUID[]	Yes	List of credential IDs to use
externalTradingAccountId	string	Yes	Account identifier from verification (e.g., "spot", "futures")
nickname	string	No	Display name for the trading account

Response

The response contains the connected TradingAccount object:

{
  "data": {
    "tradingAccountId": "660e8400-e29b-41d4-a716-446655440000",
    "externalTradingAccountId": "spot",
    "venue": "BINANCE",
    "nickname": "My Binance Spot",
    "accountType": "SPOT",
    "externalAccountType": "SPOT",
    "credentials": [
      {
        "credentialId": "550e8400-e29b-41d4-a716-446655440000",
        "venue": "BINANCE",
        "status": "VERIFIED"
      }
    ],
    "status": "CONNECTED",
    "createdAt": 1704067200000,
    "updatedAt": 1704067200000
  },
  "success": true,
  "errno": 0,
  "error": null
}

Common External Trading Account IDs

Binance

ID	Description
spot	Spot trading account
margin	Cross margin account
isolated_margin	Isolated margin accounts
futures	USDT-M Futures
coin_futures	COIN-M Futures

OKX

ID	Description
trading	Unified trading account
funding	Funding account

Bybit

ID	Description
unified	Unified Trading Account
spot	Spot account
contract	Derivatives account

Complete Flow Example

Python

import cadenza_client

# 1. Create credential
create_response = credential_api.create_trading_account_credential(
    cadenza_client.CreateTradingAccountCredentialRequest(
        venue=cadenza_client.Venue.BINANCE,
        credential_type=cadenza_client.CredentialType.EXCHANGE,
        api_key="your-api-key",
        api_secret="your-api-secret"
    )
)
credential_id = create_response.data.credential_id

# 2. Verify credential
verify_response = credential_api.verify_trading_account_credential(
    cadenza_client.VerifyTradingAccountCredentialRequest(
        credential_id=credential_id
    )
)

if verify_response.data.status != cadenza_client.CredentialStatus.VERIFIED:
    raise Exception("Credential verification failed")

available_accounts = verify_response.data.identities
print(f"Available accounts: {available_accounts}")

# 3. Connect spot trading account
connect_response = trading_account_api.connect_trading_account(
    cadenza_client.ConnectTradingAccountRequest(
        credential_ids=[credential_id],
        external_trading_account_id="spot",
        nickname="My Binance Spot"
    )
)

trading_account_id = connect_response.data.trading_account_id
print(f"Connected trading account: {trading_account_id}")

# 4. Now you can trade!

TypeScript

// 1. Create credential
const createResponse = await credentialApi.createTradingAccountCredential({
  venue: 'BINANCE',
  credentialType: 'EXCHANGE',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
})
const credentialId = createResponse.data.data.credentialId

// 2. Verify credential
const verifyResponse = await credentialApi.verifyTradingAccountCredential({
  credentialId: credentialId,
})

if (verifyResponse.data.data.status !== 'VERIFIED') {
  throw new Error('Credential verification failed')
}

const availableAccounts = verifyResponse.data.data.identities
console.log('Available accounts:', availableAccounts)

// 3. Connect spot trading account
const connectResponse = await tradingAccountApi.connectTradingAccount({
  credentialIds: [credentialId],
  externalTradingAccountId: 'spot',
  nickname: 'My Binance Spot',
})

const tradingAccountId = connectResponse.data.data.tradingAccountId
console.log('Connected trading account:', tradingAccountId)

// 4. Now you can trade!

Go

// 1. Create credential
createResponse, _, _ := apiClient.TradingAccountCredentialAPI.CreateTradingAccountCredential(ctx).
    CreateTradingAccountCredentialRequest(client.CreateTradingAccountCredentialRequest{
        Venue:          client.VENUE_BINANCE,
        CredentialType: client.CREDENTIALTYPE_EXCHANGE,
        ApiKey:         client.PtrString("your-api-key"),
        ApiSecret:      client.PtrString("your-api-secret"),
    }).Execute()
credentialId := *createResponse.Data.CredentialId

// 2. Verify credential
verifyResponse, _, _ := apiClient.TradingAccountCredentialAPI.VerifyTradingAccountCredential(ctx).
    VerifyTradingAccountCredentialRequest(client.VerifyTradingAccountCredentialRequest{
        CredentialId: credentialId,
    }).Execute()

if *verifyResponse.Data.Status != client.CREDENTIALSTATUS_VERIFIED {
    panic("Credential verification failed")
}

availableAccounts := verifyResponse.Data.Identities
fmt.Printf("Available accounts: %v\n", availableAccounts)

// 3. Connect spot trading account
connectResponse, _, _ := apiClient.TradingAccountAPI.ConnectTradingAccount(ctx).
    ConnectTradingAccountRequest(client.ConnectTradingAccountRequest{
        CredentialIds:            []string{credentialId},
        ExternalTradingAccountId: "spot",
        Nickname:                 client.PtrString("My Binance Spot"),
    }).Execute()

tradingAccountId := *connectResponse.Data.TradingAccountId
fmt.Printf("Connected trading account: %s\n", tradingAccountId)

// 4. Now you can trade!

Connecting Multiple Account Types

You can connect multiple account types using the same credential:

Python

# Connect spot account
spot_response = trading_account_api.connect_trading_account(
    cadenza_client.ConnectTradingAccountRequest(
        credential_ids=[credential_id],
        external_trading_account_id="spot",
        nickname="Binance Spot"
    )
)
spot_account_id = spot_response.data.trading_account_id

# Connect futures account
futures_response = trading_account_api.connect_trading_account(
    cadenza_client.ConnectTradingAccountRequest(
        credential_ids=[credential_id],
        external_trading_account_id="futures",
        nickname="Binance Futures"
    )
)
futures_account_id = futures_response.data.trading_account_id

print(f"Spot Account: {spot_account_id}")
print(f"Futures Account: {futures_account_id}")

TypeScript

// Connect spot account
const spotResponse = await tradingAccountApi.connectTradingAccount({
  credentialIds: [credentialId],
  externalTradingAccountId: 'spot',
  nickname: 'Binance Spot',
})
const spotAccountId = spotResponse.data.data.tradingAccountId

// Connect futures account
const futuresResponse = await tradingAccountApi.connectTradingAccount({
  credentialIds: [credentialId],
  externalTradingAccountId: 'futures',
  nickname: 'Binance Futures',
})
const futuresAccountId = futuresResponse.data.data.tradingAccountId

console.log('Spot Account:', spotAccountId)
console.log('Futures Account:', futuresAccountId)

Go

// Connect spot account
spotResponse, _, _ := apiClient.TradingAccountAPI.ConnectTradingAccount(ctx).
    ConnectTradingAccountRequest(client.ConnectTradingAccountRequest{
        CredentialIds:            []string{credentialId},
        ExternalTradingAccountId: "spot",
        Nickname:                 client.PtrString("Binance Spot"),
    }).Execute()
spotAccountId := *spotResponse.Data.TradingAccountId

// Connect futures account
futuresResponse, _, _ := apiClient.TradingAccountAPI.ConnectTradingAccount(ctx).
    ConnectTradingAccountRequest(client.ConnectTradingAccountRequest{
        CredentialIds:            []string{credentialId},
        ExternalTradingAccountId: "futures",
        Nickname:                 client.PtrString("Binance Futures"),
    }).Execute()
futuresAccountId := *futuresResponse.Data.TradingAccountId

fmt.Printf("Spot Account: %s\n", spotAccountId)
fmt.Printf("Futures Account: %s\n", futuresAccountId)

Error Handling

Error Code	Description
400	Invalid request parameters
401	Authentication required
404	Credential not found
409	Trading account already connected
422	Invalid external trading account ID

Next Steps

After connecting a trading account:

• View Portfolio - Check balances and positions
• Submit Orders - Start trading
• Quick Start - WebSocket setup for real-time notifications