Positions

Retrieves the current positions for a portfolio across all vaults. This endpoint supports cursor-based pagination for efficient handling of large position datasets.

Request URL

GET https://ddp.definitive.fi/v2/portfolio/positions

Example

// First page
const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/positions",
  method: "GET",
  queryParams: { limit: "50" },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
// Subsequent pages using cursor
const nextPageJson = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/positions",
  method: "GET",
  queryParams: {
    limit: "50",
    cursor: "1192.33975361998977876"
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

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)	-

Response

{
  positions: [
    {
      vaultId: string, // e.g. "a1859005-cd44-4bda-83f7-c6253a39c805"
      asset: {
        id: string, // e.g. "bcf2f301-1db9-4e12-b3fd-da79e91d3940"
        name: string, // e.g. "USD Coin"
        ticker: string, // e.g. "USDC"
        address: string, // e.g. "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        chain: {
          id: string, // e.g. "8453"
          name: string, // e.g. "Base"
          namespace: string // e.g. "eip155"
        }
      },
      balance: number, // e.g. 1000.50
      notional: number // e.g. 1000.50 (in USD)
    }
    // ... additional positions
  ],
  nextCursor: string | null, // e.g. "1192.33975361998977876" or null if no more pages
  hasMore: boolean, // true if more positions are available
  limit: number // e.g. 50
}

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/portfolio/positions",
    method: "GET",
    queryParams,
    apiKey: process.env.API_KEY,
    apiSecret: process.env.API_SECRET,
  });
 
  allPositions.push(...response.positions);
  cursor = response.nextCursor;
} while (response.hasMore);