Preview Perps Order

Validates a proposed order against your live account state and returns a cost/margin preview. Nothing is placed — this is a read against the venue and your account.

Endpoint

Portfolio API: POST https://ddp.definitive.fi/v2/portfolio/perps/orders/preview

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

Requires a WRITE-scoped API key (all POST endpoints do). Returns 503 on deployments where perps account reads are not yet enabled — see Availability.

Request Body

Field	Type	Required	Description
symbol	string	Yes	Market symbol, e.g. `"native:BTC"` — see Market Symbols
side	string	Yes	`"buy"` or `"sell"`
orderType	string	Yes	`"market"`, `"limit"`, `"stop_market"`, `"stop_limit"`, `"take_profit_market"`, `"take_profit_limit"`, `"twap"`
size	string	Yes	Order size in the base asset
price	string	No	Limit price (limit-priced order types)
triggerPrice	string	No	Trigger price (stop/take-profit types)
reduceOnly	boolean	No	Restrict the order to reducing the current position
leverage	number	No	1–100; defaults to the account's active leverage
takeProfit	string	No	Attached take-profit price
stopLoss	string	No	Attached stop-loss price
twapDurationMinutes	number	No	5–1440; required for `"twap"`

Examples

const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/perps/orders/preview",
  method: "POST",
  body: {
    symbol: "native:BTC",
    side: "buy",
    orderType: "limit",
    size: "0.01",
    price: "64000",
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

Response

{
  validation: {
    canSubmit: true,
    reason: "ok"            // otherwise e.g. "insufficient-balance", "below-min-notional",
                            // "exceeds-max-size", with matching detail fields
  },
  preview: {
    fillPrice: 64000,
    notional: 640,
    estimatedFee: 0.096,
    appliedFeeRate: 0.00015,   // maker for limit-priced types, taker otherwise
    feeRates: { takerRate: 0.00045, makerRate: 0.00015 },
    marginRequired: 16,
    totalCost: 16.1,
    effectiveAvailable: 9837.76,
    releasedMargin: 0,
    offsetNotional: 0
  },
  feeRates: { takerRate: 0.00045, makerRate: 0.00015 }
}

validation.canSubmit: false comes with a reason and human-readable detail fields (e.g. minNotionalDisplay); the preview is still returned where computable.