Skip to content

Portfolio vs. Organization API

Definitive offers two API modes that share the same trading, portfolio, and bridge endpoints. The difference is scope and authentication.

When to Use Each

Portfolio APIOrganization API
Use caseYou manage a single portfolio (your own account or one end-user)You manage many portfolios on behalf of users (app, bot, trading terminal)
API key scopeBound to one portfolioBound to your organization — operates on any portfolio via {portfolioId}
Base path/v2/portfolio/.../v2/organization/portfolios/{portfolioId}/...
AuthAPI key is bound to your portfolioAPI key is bound to your organization

Which should I pick?

  • Building for yourself (one portfolio) → Portfolio API
  • Building for others (multi-user app, Telegram bot, trading terminal) → Organization API

See Overview for a full integration walkthrough using the Organization API.

Authentication

Both APIs use the same HMAC signature scheme (x-definitive-api-key, x-definitive-signature, x-definitive-timestamp). Your API key determines whether you are using the Portfolio or Organization API.

See Making Your First Request for a full authentication walkthrough covering both modes.

Path Convention

Every shared endpoint page shows the Portfolio API path. To use the Organization API, replace the /v2/portfolio/ prefix with /v2/organization/portfolios/{portfolioId}/:

Portfolio APIOrganization API
/v2/portfolio/trade/quote/v2/organization/portfolios/{portfolioId}/trade/quote
/v2/portfolio/orders/v2/organization/portfolios/{portfolioId}/orders

portfolioId is the UUID of the target portfolio (string, required).

Organization API Example

const json = await AuthHelpers.signAndSend({
  path: `/v2/organization/portfolios/${portfolioId}/trade/quote`,
  method: "POST",
  body: { /* same body as Portfolio API */ },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

Shared Endpoints

All of the following endpoints are available in both APIs — identical request/response shapes, just different base paths:

Portfolio Information

Orders

Trading

  • Get Quote — Get a quote for market, limit, TWAP, stop, stop-loss, or take-profit orders
  • Submit Order — Submit an order using a quote
  • Cancel Order — Cancel an active order

QuickTrade

Bridge

Perps

  • Perps Overview — Market data, account state, orders, fills, funding, fees, order preview, and transfers in both directions

Organization-Only Endpoints

These endpoints are exclusive to the Organization API: