List Orders

Retrieves the order history for a portfolio, including all order types and their current status.

Endpoint

Portfolio API: GET https://ddp.definitive.fi/v2/portfolio/orders

Organization API: Replace /v2/portfolio/ with /v2/organization/portfolios/{portfolioId}/. See Portfolio vs. Organization API.

Query Parameters

Parameter	Type	Required	Description	Default
limit	number	No	Maximum number of orders to return	100
cursor	string	No	ISO 8601 timestamp for pagination (order `closedAt`)	-
filters	string	No	JSON string of filters (see below)	-

Filters

The filters parameter accepts a JSON string with the following optional fields:

Field	Type	Description	Valid Values
status	string	Filter orders by status	`ORDER_STATUS_PENDING`, `ORDER_STATUS_ACCEPTED`, `ORDER_STATUS_PARTIALLY_FILLED`, `ORDER_STATUS_FILLED`, `ORDER_STATUS_CANCELLED`
chain	string	Chain of `asset`. Required when `asset` is given	Same chain names as the trade endpoints, e.g. `ethereum`, `base`, `solana`
asset	string	Token contract address. Matches orders where it is the target or the contra asset. Requires `chain`	A contract address on `chain`

Filters combine with AND. A token that Definitive does not track returns an empty list; a malformed asset returns 400.

Filter Examples

Filter by status:

const queryParams = {
  filters: JSON.stringify({ status: "ORDER_STATUS_FILLED" }),
};

Filter by token:

const queryParams = {
  filters: JSON.stringify({
    chain: "base",
    asset: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // USDC
  }),
};

Combine token and status:

const queryParams = {
  filters: JSON.stringify({
    status: "ORDER_STATUS_FILLED",
    chain: "base",
    asset: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  }),
};

Combine filters with pagination:

const queryParams = {
  limit: "50",
  cursor: "2025-06-05T01:26:30.560Z",
  filters: JSON.stringify({ status: "ORDER_STATUS_CANCELLED" }),
};

Examples

const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/orders",
  method: "GET",
  queryParams: {
    limit: "20",
    filters: JSON.stringify({ status: "ORDER_STATUS_FILLED" }),
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

Response

{
  orders: [
    {
      orderId: "00000000-0000-0000-0000-000000000005",
      type: "ORDER_TYPE_TWAP",
      status: "ORDER_STATUS_FILLED",
      orderSide: "ORDER_SIDE_SELL",
      contraAsset: {
        id: "00000000-0000-0000-0000-000000000001",
        name: "Hyperliquid",
        address: "1000003",
        ticker: "HYPE",
        chain: { name: "Hyperevm", id: "999", namespace: "eip155" }
      },
      targetAsset: {
        id: "00000000-0000-0000-0000-000000000002",
        name: "SUPERMILK",
        address: "0xfe69bc93b936b34d371defa873686c116c8488c2",
        ticker: "MILK",
        chain: { name: "Hyperevm", id: "999", namespace: "eip155" }
      },
      filled: {
        targetAssetAmount: "2678483.226019",
        contraAssetAmount: "27.54374",
        averagePrice: "35.43",
        averageNotionalPrice: "975.8747082"
      },
      size: {
        amount: "27.54374",
        filled: "27.54374",
        asset: "target"
      },
      maxPriceImpact: "0.05",
      limit: { isNotional: false, price: "" },
      trigger: { isNotional: false, price: "" },
      placedAt: "2025-06-05T07:36:49.045Z",
      acceptedAt: "2025-06-05T07:36:49.403Z",
      closedAt: "2025-06-06T07:34:43.048Z",
      closeReason: "REASON_FULLY_FILLED",
      organizationName: "Example Organization",
      portfolioId: "00000000-0000-0000-0000-000000000004",
      vaultId: "00000000-0000-0000-0000-000000000003",
      // TWAP orders include:
      twap: { buckets: 6, durationSeconds: 3600 }
      // ORDER_TYPE_TRAILING_STOP / ORDER_TYPE_TRAILING_STOP_LIMIT orders include
      // a `trailing` object — see Order Details for its fields
    }
    // ... additional orders
  ],
  limit: 100,
  nextCursor: "2024-08-05T20:48:11.584Z", // ISO timestamp for next page
  hasNextPage: true
}

Pagination

This endpoint uses cursor-based pagination based on the closedAt timestamp:

First Request: Omit the cursor parameter
Subsequent Requests: Use the nextCursor value from the previous response
End of Data: When hasNextPage is false, there are no more orders to fetch
Cursor Format: The cursor is an ISO 8601 timestamp string (e.g., "2024-08-05T20:48:11.584Z")

Pagination Example

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

Size Object

The size property is an object containing:

Field	Type	Description
amount	string	The total order size
filled	string	The amount that has been filled
asset	string	Which asset the size refers to ("target" or "contra")

References

Order Statuses