Perps Market Data

Four read endpoints keyed by market symbol. Symbols follow the subvenue:SYMBOL convention (e.g. native:BTC) — see Market Symbols.

Organization API: For every endpoint on this page, replace /v2/portfolio/ with /v2/organization/portfolios/{portfolioId}/. See Portfolio vs. Organization API.

Orderbook

Portfolio API: GET https://ddp.definitive.fi/v2/portfolio/perps/markets/{symbol}/orderbook

L2 snapshot: price levels with aggregate size and order count per level.

const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/perps/markets/native:BTC/orderbook",
  method: "GET",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

{
  symbol: "BTC",
  time: 1787164843804,
  midPrice: "68293.5",
  bids: [{ price: "68293", size: "0.20995", numOrders: 7 }, /* ... */],
  asks: [{ price: "68294", size: "0.11621", numOrders: 4 }, /* ... */]
}

Candles

Portfolio API: GET https://ddp.definitive.fi/v2/portfolio/perps/markets/{symbol}/candles

Parameter	Type	Required	Description
interval	string	Yes	`"1m"`, `"5m"`, `"15m"`, `"1h"`, `"4h"`, `"1d"`
startTime	number	Yes	Range start, epoch milliseconds (13-digit; seconds are rejected)
endTime	number	Yes	Range end, epoch milliseconds (must be > `startTime`)

const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/perps/markets/native:BTC/candles",
  method: "GET",
  queryParams: {
    interval: "1h",
    startTime: String(Date.now() - 24 * 60 * 60 * 1000),
    endTime: String(Date.now()),
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

{
  candles: [
    {
      openTime: 1787076000000,
      closeTime: 1787079599999,
      open: "64633",
      high: "64795",
      low: "64617",
      close: "64733",
      volume: "1119.8",
      numTrades: 5321,
    },
    // ...
  ];
}

Execution Quote

Portfolio API: GET https://ddp.definitive.fi/v2/portfolio/perps/markets/{symbol}/quote

Size-aware execution estimate against the live book. Anonymous market estimate — it does not account for your positions or margin.

Parameter	Type	Required	Description
side	string	Yes	`"buy"` or `"sell"`
size	string	Yes	Order size in the base asset

const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/perps/markets/native:BTC/quote",
  method: "GET",
  queryParams: { side: "buy", size: "0.001" },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

{
  symbol: "BTC",
  side: "buy",
  requestedSize: "0.001",
  filledSize: "0.001",
  bestBid: "68293",
  bestAsk: "68294",
  midPrice: "68293.5",
  avgExecutionPrice: "68294",
  worstExecutionPrice: "68294",
  estimatedNotional: "68.294",
  estimatedSlippageBps: "0.07",
  insufficientDepth: false,
  estimatedLiquidationPrice: null
}

insufficientDepth: true means the book could not absorb the full size; filledSize shows how much would execute.

Funding

Portfolio API: GET https://ddp.definitive.fi/v2/portfolio/perps/markets/{symbol}/funding

Historical funding entries plus the venue's predicted next funding.

Parameter	Type	Required	Description
startTime	number	No	History range start, epoch milliseconds (13-digit)

{
  history: [
    { time: 1787130000000, fundingRate: "0.0000125", premium: "0.0000031" },
    // ...
  ],
  predicted: [
    { venue: "HlPerp", fundingRate: "0.0000125", nextFundingTime: 1787167200000 }
  ]
}