Accounts

Retrieve account balances, orders, and positions with the JavaScript SDK

Overview

The Accounts API provides access to account-level data including balances, buying power, positions, and order history for specific trading accounts.

Class Reference

import { AriesClient } from '@aries-exchange/sdk';

const client = new AriesClient({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret'
});

// Access accounts methods
const accounts = client.accounts;

Methods

getBalances(accountId)

Retrieve account balances and buying power.

const balances = await client.accounts.getBalances('acc_123456');

console.log(`Cash: $${balances.cash}`);
console.log(`Buying Power: $${balances.buyingPower}`);
console.log(`Portfolio Value: $${balances.portfolioValue}`);

Parameters:

• accountId (string): Account ID

Returns: Promise<Balances>

getOrders(accountId, filters)

Retrieve all orders for an account.

// Get all orders
const orders = await client.accounts.getOrders('acc_123456');

// Get only open orders
const openOrders = await client.accounts.getOrders('acc_123456', {
  status: 'open'
});

Parameters:

• accountId (string): Account ID
• filters (object, optional): Filter options including status (“open”, “filled”, “cancelled”)

Returns: Promise<Order[]>

getPositions(accountId)

Retrieve all positions for an account.

const positions = await client.accounts.getPositions('acc_123456');

positions.forEach(position => {
  console.log(`${position.symbol}: ${position.quantity} shares`);
  console.log(`  P/L: $${position.unrealizedPl}`);
});

Parameters:

• accountId (string): Account ID

Returns: Promise<Position[]>

TypeScript Types

interface Balances {
  cash: number;
  buyingPower: number;
  portfolioValue: number;
  equity: number;
  longMarketValue: number;
  shortMarketValue: number;
  dayTradingBuyingPower: number;
  overnightBuyingPower: number;
}

interface Position {
  symbol: string;
  quantity: number;
  averageCost: number;
  currentPrice: number;
  marketValue: number;
  unrealizedPl: number;
  unrealizedPlPercent: number;
  side: string;
}

Examples

Check Account Balance Before Trading

// Get account balances
const balances = await client.accounts.getBalances('acc_123456');

console.log(`Available cash: $${balances.cash.toLocaleString()}`);
console.log(`Buying power: $${balances.buyingPower.toLocaleString()}`);

// Check if sufficient funds for trade
const orderCost = 1500.00;
if (balances.buyingPower >= orderCost) {
  console.log('Sufficient funds to place order');
  const order = await client.orders.placeOrder({
    symbol: 'AAPL',
    quantity: 10,
    side: 'buy',
    orderType: 'market'
  });
  console.log(`Order placed: ${order.id}`);
} else {
  console.log(`Insufficient funds. Need $${(orderCost - balances.buyingPower).toFixed(2)} more`);
}

Monitor Account Positions

// Get all positions
const positions = await client.accounts.getPositions('acc_123456');

console.log(`Total positions: ${positions.length}\n`);

let totalPl = 0;
for (const position of positions) {
  console.log(`${position.symbol}:`);
  console.log(`  Quantity: ${position.quantity}`);
  console.log(`  Avg Cost: $${position.averageCost.toFixed(2)}`);
  console.log(`  Current: $${position.currentPrice.toFixed(2)}`);
  console.log(`  Value: $${position.marketValue.toLocaleString()}`);
  console.log(`  P/L: $${position.unrealizedPl.toLocaleString()} (${position.unrealizedPlPercent >= 0 ? '+' : ''}${position.unrealizedPlPercent.toFixed(2)}%)`);
  console.log();

  totalPl += position.unrealizedPl;
}

console.log(`Total Unrealized P/L: $${totalPl.toLocaleString()}`);

Review Order History

// Get all orders for the account
const orders = await client.accounts.getOrders('acc_123456');

console.log(`Total orders: ${orders.length}\n`);

// Group by status
const ordersByStatus = orders.reduce((acc, order) => {
  acc[order.status] = acc[order.status] || [];
  acc[order.status].push(order);
  return acc;
}, {});

Object.entries(ordersByStatus).forEach(([status, orderList]) => {
  console.log(`${status.toUpperCase()}: ${orderList.length} orders`);
});

// Show recent filled orders
const filledOrders = orders
  .filter(o => o.status === 'filled')
  .sort((a, b) => new Date(b.filledAt) - new Date(a.filledAt))
  .slice(0, 5);

console.log('\nRecent Fills:');
filledOrders.forEach(order => {
  console.log(`${order.symbol} - ${order.side.toUpperCase()} ${order.quantity} @ $${order.averageFillPrice.toFixed(2)}`);
});

Calculate Account Performance

// Get balances and positions
const balances = await client.accounts.getBalances('acc_123456');
const positions = await client.accounts.getPositions('acc_123456');

// Calculate metrics
const totalInvestment = positions.reduce((sum, p) => sum + (p.quantity * p.averageCost), 0);
const totalValue = positions.reduce((sum, p) => sum + p.marketValue, 0);
const unrealizedPl = totalValue - totalInvestment;

// Account summary
console.log('Account Performance Summary:');
console.log(`Cash: $${balances.cash.toLocaleString()}`);
console.log(`Investment: $${totalInvestment.toLocaleString()}`);
console.log(`Current Value: $${totalValue.toLocaleString()}`);
console.log(`Unrealized P/L: $${unrealizedPl.toLocaleString()}`);
console.log(`Return: ${unrealizedPl >= 0 ? '+' : ''}${((unrealizedPl / totalInvestment) * 100).toFixed(2)}%`);
console.log(`Total Equity: $${balances.equity.toLocaleString()}`);

Find Winning and Losing Positions

const positions = await client.accounts.getPositions('acc_123456');

// Sort by P/L
const sortedPositions = [...positions].sort((a, b) => b.unrealizedPl - a.unrealizedPl);

console.log('Top Winners:');
sortedPositions.slice(0, 3).forEach(position => {
  if (position.unrealizedPl > 0) {
    console.log(`${position.symbol}: $${position.unrealizedPl.toLocaleString()} (+${position.unrealizedPlPercent.toFixed(2)}%)`);
  }
});

console.log('\nTop Losers:');
sortedPositions.slice(-3).reverse().forEach(position => {
  if (position.unrealizedPl < 0) {
    console.log(`${position.symbol}: $${position.unrealizedPl.toLocaleString()} (${position.unrealizedPlPercent.toFixed(2)}%)`);
  }
});

Error Handling

import { AriesAPIError } from '@aries-exchange/sdk';

try {
  const balances = await client.accounts.getBalances('acc_123456');
} catch (error) {
  if (error instanceof AriesAPIError) {
    if (error.statusCode === 403) {
      console.error("Access denied: You don't have permission for this account");
    } else if (error.statusCode === 404) {
      console.error('Account not found');
    } else {
      console.error(`Error: ${error.message}`);
    }
  }
}

Best Practices

1. Check balances before trading to avoid insufficient funds errors
2. Monitor positions regularly to stay informed about P/L
3. Use filters when querying orders to reduce data transfer
4. Store account data appropriately to minimize API calls
5. Handle errors gracefully especially for permission issues

Related APIs

• Orders - Place and manage orders
• Users - Get list of user accounts
• Market Data - Get current prices for positions

API Endpoints

This SDK wraps the following REST API endpoints:

• GET /v1/accounts/{id}/balances - Get account balances
• GET /v2/accounts/{id}/orders - Get account orders
• GET /v1/accounts/{id}/positions - Get account positions