Portfolio Endpoints

The Portfolio APIs provide access to account holdings, balance information, and detailed portfolio metadata. These endpoints work for both Trading and Signal Accounts.

Get Portfolio Holdings

Endpoint: GET /portfolio

Description: Retrieve all current holdings in the portfolio

cURL Example

curl -X GET {{BASE_URL}}/portfolio \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Node.js Example

const axios = require("axios");

async function getPortfolio(token) {
  try {
    const response = await axios.get(
      "{{BASE_URL}}/portfolio",
      {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error fetching portfolio:", error.response?.data);
    throw error;
  }
}

const portfolio = await getPortfolio(token);
console.log("Portfolio:", portfolio);

Response

Success Response (200 OK):

[
  {
    "ticker": "AAPL",
    "quantity": 10,
    "averagePurchasePrice": 145.00
  },
  {
    "ticker": "GOOGL",
    "quantity": 5,
    "averagePurchasePrice": 135.00
  },
  {
    "ticker": "MSFT",
    "quantity": 8,
    "averagePurchasePrice": 320.50
  }
]

Response Fields:

FieldTypeDescription
tickerstringStock ticker symbol
quantitynumberNumber of shares held
averagePurchasePricenumberAverage purchase price per share

Get Portfolio Properties

Endpoint: GET /portfolio-properties

Description: Retrieve portfolio properties including available balance and portfolio metadata

cURL Example

curl -X GET {{BASE_URL}}/portfolio-properties \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Node.js Example

const axios = require("axios");

async function getPortfolioProperties(token) {
  try {
    const response = await axios.get(
      "{{BASE_URL}}/portfolio-properties",
      {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error fetching portfolio properties:", error.response?.data);
    throw error;
  }
}

const properties = await getPortfolioProperties(token);
console.log("Portfolio Properties:", properties);

Response

Success Response (200 OK):

{
  "availableAmount": 35000,
  "availableAmountToTrade": 33980.58,
  "name": "Default Portfolio",
  "description": "My trading portfolio",
  "visibility": "PRIVATE",
  "type": "TRADING",
  "currentValue": 50000
}

Response Fields:

FieldTypeDescription
availableAmountnumberCash available for trading in USD
availableAmountToTradenumberAvailable amount adjusted for margin (÷ 1.03)
namestringPortfolio name
descriptionstringPortfolio description
visibilitystringPortfolio visibility (PRIVATE/PUBLIC)
typestringPortfolio type (TRADING/SIGNAL)
currentValuenumberTotal current portfolio value in USD

Common Errors

User Not Found

{
  "success": false,
  "error": "User not found",
  "code": "USER_NOT_FOUND"
}

Solution: Verify the authentication token is valid and the user exists.

Unauthorized Access

{
  "success": false,
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

Solution: Check that your JWT token is valid and not expired.

No Holdings

{
  "success": true,
  "holdings": [],
  "totalBalance": 5000,
  "availableBalance": 5000,
  "investedBalance": 0
}

Solution: This is normal for new accounts. Start by placing trades.

Best Practices

  1. Cache Data - Cache portfolio data to reduce API calls
  2. Refresh Intervals - Update portfolio data every 5-10 minutes
  3. Error Handling - Handle network errors gracefully
  4. Performance - Use portfolio data for analytics and reporting
  5. Monitoring - Track portfolio changes over time

Next Steps

Was this page helpful?