Get Order Details

Retrieves detailed information about a specific order, including execution details, fill events, and current status.

Endpoint

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

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

Path Parameters

Parameter	Type	Required	Description
orderId	string	Yes	UUID of the order

Examples

const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/orders/00000000-0000-0000-0000-000000000001",
  method: "GET",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
console.log(json);

Response

{
  order: {
    orderId: "00000000-0000-0000-0000-000000000005",
    type: "ORDER_TYPE_LIMIT",
    status: "ORDER_STATUS_PARTIALLY_FILLED",
    orderSide: "ORDER_SIDE_BUY",
    targetAsset: {
      id: "00000000-0000-0000-0000-000000000010",
      name: "USD Coin",
      address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      ticker: "USDC",
      chain: { name: "Ethereum", id: "1", namespace: "eip155" }
    },
    contraAsset: {
      id: "00000000-0000-0000-0000-000000000011",
      name: "Wrapped Ether",
      address: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      ticker: "WETH",
      chain: { name: "Ethereum", id: "1", namespace: "eip155" }
    },
    filled: {
      targetAssetAmount: "899625.000000",
      contraAssetAmount: "500.000000",
      averagePrice: "1799.25",
      averageNotionalPrice: "1799.50"
    },
    size: {
      amount: "1000.000000",
      filled: "750.000000",
      asset: "contra"
    },
    maxPriceImpact: "0.01",
    limit: { isNotional: false, price: "1800.00" },
    trigger: { isNotional: false, price: "" },
    placedAt: "2024-08-05T20:48:11.584Z",
    acceptedAt: "2024-08-05T20:48:12.584Z",
    closedAt: null,
    closeReason: null,
    organizationName: "Example Organization",
    portfolioId: "00000000-0000-0000-0000-000000000004",
    vaultId: "00000000-0000-0000-0000-000000000003"
  },
  fills: [
    {
      status: "CHAIN_STATUS_FINALIZED",
      notional: "1799625.000000",
      venues: ["Uniswap V3"],
      filledAt: "2024-08-05T20:48:30.584Z",
      rootOrderId: "00000000-0000-0000-0000-000000000005",
      orderId: "00000000-0000-0000-0000-000000000006",
      parentOrderId: "00000000-0000-0000-0000-000000000005",
      transactionId: "0x1234567890abcdef...",
      fillPrice: "1799.25",
      feeAmount: "0.5",
      feeTicker: "WETH",
      tradeFeeAmount: "0.45",
      networkFeeAmount: "0.05",
      feeNotional: "900.00",
      tradeFeeNotional: "810.00",
      networkFeeNotional: "90.00",
      contraAmount: "500.000000",
      targetAmount: "899625.000000"
    }
  ]
}

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

TWAP Orders

For TWAP orders, the response includes additional TWAP-specific fields:

{
  order: {
    orderId: "00000000-0000-0000-0000-000000000008",
    type: "ORDER_TYPE_TWAP",
    status: "ORDER_STATUS_FILLED",
    orderSide: "ORDER_SIDE_BUY",
    targetAsset: {
      id: "...", name: "USD Coin", address: "0xa0b...", ticker: "USDC",
      chain: { name: "Ethereum", id: "1", namespace: "eip155" }
    },
    contraAsset: {
      id: "...", name: "Wrapped Ether", address: "0xc02...", ticker: "WETH",
      chain: { name: "Ethereum", id: "1", namespace: "eip155" }
    },
    filled: {
      targetAssetAmount: "...",
      contraAssetAmount: "...",
      averagePrice: "...",
      averageNotionalPrice: "..."
    },
    size: { amount: "1000.000000", filled: "1000.000000", asset: "contra" },
    maxPriceImpact: "0.01",
    limit: { isNotional: false, price: "" },
    trigger: { isNotional: false, price: "" },
    twap: { buckets: 6, durationSeconds: 3600 },
    placedAt: "2024-08-05T20:48:11.584Z",
    acceptedAt: "2024-08-05T20:48:12.584Z",
    closedAt: "2024-08-05T21:48:11.584Z",
    closeReason: "REASON_FULLY_FILLED",
    organizationName: "...",
    portfolioId: "...",
    vaultId: "..."
  },
  fills: [...]
}

TWAP Fields

Field	Type	Description
buckets	number	Number of execution buckets for the TWAP order
durationSeconds	number	Duration of the TWAP order in seconds

Trailing Stop Orders

For ORDER_TYPE_TRAILING_STOP and ORDER_TYPE_TRAILING_STOP_LIMIT orders the response carries a trailing object with the trail configuration and the watermark state the server has recorded so far. trigger.price is empty for these orders: the trigger moves with the market and is reported as trailing.effectiveTriggerPrice.

{
  order: {
    orderId: "00000000-0000-0000-0000-000000000009",
    type: "ORDER_TYPE_TRAILING_STOP_LIMIT",
    status: "ORDER_STATUS_ACCEPTED",
    orderSide: "ORDER_SIDE_SELL",
    // ...standard order fields...
    limit: { isNotional: false, price: "" },
    trigger: { isNotional: false, price: "" },
    trailing: {
      trailPercent: "0.05",
      activationPrice: "200.00",
      watermarkPrice: "212.40",
      effectiveTriggerPrice: "201.78",
      activated: true,
      watermarkUpdatedAt: "2026-10-22T10:00:00Z"
    },
    placedAt: "2026-10-22T09:48:11.584Z",
    acceptedAt: "2026-10-22T09:48:12.584Z",
    closedAt: null,
    closeReason: null
  },
  fills: []
}

Trailing Fields

Field	Type	Description
trailing.trailPercent	string	Trail distance as a fraction of the watermark (`"0.05"` = 5%)
trailing.activationPrice	string	USD price that arms the trail; absent when the order armed immediately
trailing.activated	boolean	Whether the trail has armed. Before activation the watermark is not tracked
trailing.watermarkPrice	string	Best USD price seen since arming: the high-water mark for a sell, the low-water mark for a buy
trailing.effectiveTriggerPrice	string	Current trigger price: the watermark less the trail for a sell, plus the trail for a buy
trailing.watermarkUpdatedAt	string	ISO 8601 time the watermark was last recorded

watermarkPrice, effectiveTriggerPrice and watermarkUpdatedAt are absent until the trail arms and the first watermark is recorded. The watermark is persisted on a throttle, so the live trigger can sit slightly beyond the value reported here.

Fills

The fills array shows on-chain executions for the order. Each fill includes:

Field	Type	Description
status	string	Chain confirmation status (e.g., `CHAIN_STATUS_FINALIZED`)
notional	string	Total USD value of the fill
venues	string[]	DEX venues used (e.g., `["Uniswap V3"]`)
filledAt	string	ISO 8601 timestamp of execution
fillPrice	string	Execution price (contraAmount / targetAmount)
contraAmount	string	Amount of contra asset filled
targetAmount	string	Amount of target asset filled
transactionId	string	Transaction hash
feeAmount	string	Total fee amount (tradeFee + networkFee)
feeTicker	string	Asset ticker for fee payment
tradeFeeAmount	string	Platform/trade fee amount
networkFeeAmount	string	Network/gas fee amount
feeNotional	string	Total fee in USD
tradeFeeNotional	string	Platform/trade fee in USD
networkFeeNotional	string	Network/gas fee in USD

Error Responses

If the order is not found or does not belong to the portfolio, a 404 will be returned:

{
  error: "Order not found";
}

Notes

Order detail includes both metadata (order) and executions (fills)
This endpoint is read-only and safe to call as often as needed for tracking order progress

References

Order Statuses