List Positions

Retrieves all current positions held in a portfolio, including token balances and their USD values. This endpoint is accessed through the organization API and supports cursor-based pagination for efficient handling of large position datasets.

Request URL

GET https://ddp.definitive.fi/v2/organization/portfolios/{portfolioId}/positions

Path Parameters

Parameter	Type	Required	Description
portfolioId	string	Yes	UUID of the portfolio

Query Parameters

Parameter	Type	Required	Description	Default
limit	number	No	Maximum number of positions to return (1-1000)	50
cursor	string	No	Cursor for pagination (notional value from previous response)	-

Example

// First page
const json = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/positions",
  method: "GET",
  organizationId: "00000000-0000-0000-0000-000000000000",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  queryParams: {
    limit: 20
  }
});
 
// Subsequent pages using cursor
const nextPageJson = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/positions",
  method: "GET",
  organizationId: "00000000-0000-0000-0000-000000000000",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  queryParams: {
    limit: 20,
    cursor: "1192.33975361998977876"
  }
});

Response

{
  positions: [
    {
      asset: {
        id: "bcf2f301-1db9-4e12-b3fd-da79e91d3940",
        name: "USD Coin",
        ticker: "USDC",
        address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        chain: {
          id: "1",
          name: "Ethereum",
          namespace: "eip155"
        }
      },
      balance: 1000.0,
      notional: 1000.0,
      vaultId: "00000000-0000-0000-0000-000000000003"
    }
    // ... additional positions
  ],
  nextCursor: "1192.33975361998977876", // null if no more pages
  hasMore: true,
  limit: 20
}

Pagination

This endpoint uses cursor-based pagination for optimal performance:

First Request: Make a request without a cursor parameter
Subsequent Requests: Use the nextCursor value from the previous response
End of Data: When hasMore is false, there are no more positions to fetch
Cursor Value: The cursor represents the notional USD value of the last position in the current page

Pagination Example

let cursor = null;
let allPositions = [];
 
do {
  const queryParams = { limit: 50 };
  if (cursor) queryParams.cursor = cursor;
 
  const response = await AuthHelpers.signAndSend({
    path: `/v2/organization/portfolios/${portfolioId}/positions`,
    method: "GET",
    organizationId: organizationId,
    apiKey: process.env.API_KEY,
    apiSecret: process.env.API_SECRET,
    queryParams
  });
 
  allPositions.push(...response.positions);
  cursor = response.nextCursor;
} while (response.hasMore);