Skip to content

Perps Account

Account state for the portfolio bound to your API key — no address or account parameters; the portfolio is resolved from the key itself.

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

Account endpoints return 503 on deployments where perps account reads are not yet enabled, and 422 with errorType: "PERPS_ACCOUNT_NOT_CONFIGURED" when the portfolio has no perps account — see Availability.

Account State

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

const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/perps/account",
  method: "GET",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
{
  accountValue: "10250.31",          // total account equity (USDC)
  totalMarginUsed: "412.55",
  totalNotionalPosition: "2062.75",
  withdrawable: "9837.76",
  availableCollateral: "9837.76",
  time: 1787164843804,
  positions: [
    {
      symbol: "BTC",
      size: "-0.03",                 // negative = short
      entryPrice: "67102",
      markPrice: "68262",
      liquidationPrice: "81120",
      unrealizedPnl: "-34.8",
      returnOnEquity: "-0.0846",
      positionValue: "2047.86",
      marginUsed: "412.55",
      marginType: "cross",
      maxLeverage: 40
    }
  ]
}

Account Status

Portfolio API: GET https://ddp.definitive.fi/v2/portfolio/perps/account/status

Onboarding pre-flight: whether the portfolio has a perps account and whether it can trade. States arrive as data, not errors.

{
  status: "READY",              // NO_ACCOUNT | ON_OTHER_PORTFOLIO | REQUIRES_APPROVAL | READY | REQUIRES_DEPOSIT
  canTrade: true,
  requiresSetup: false,
  requiresDeposit: false,
  accountOwnerAddress: null,    // set when the org's perps account lives on a sibling portfolio
  requiredApprovals: []         // e.g. ["AGENT", "BUILDER_FEE"] when status is REQUIRES_APPROVAL
}

Call this before the other account endpoints: NO_ACCOUNT means account reads will return 422 with errorType: "PERPS_ACCOUNT_NOT_CONFIGURED".