Skip to content

Overview

The Definitive API allows you to programmatically access your trading portfolio data and execute trades via a REST API.

API Keys

The Definitive API uses keys scoped to either an individual portfolio or your entire organization. Follow one of the sections below to create a new key.

Portfolio-Level API Keys

  1. Log into Definitive.
  2. Navigate to your organization page.
  3. In the Access Type dropdown, select Portfolio.
  4. In the Scope dropdown, choose Read-Only or Read-Write.
  5. Click Generate New Key.
  6. A new key and secret will be generated.
    • The secret is only shown once; please store it securely.
    • If you lose the secret, you will need to generate a new key and secret.

generate key

Organization-Level API Keys

  1. Log into Definitive.
  2. Navigate to your organization page.
  3. In the Access Type dropdown, select Organization.
  4. In the Scope dropdown, choose Read-Only or Read-Write.
  5. Click Generate New Key.
  6. A new key and secret will be generated.
    • The secret is only shown once; please store it securely.
    • If you lose the secret, you will need to generate a new key and secret.

generate key

Authenticating Requests

To maintain security, all requests must be signed and submitted within 2 minutes of signing. The signature must be included in the request headers.

Request Headers

Your authenticated request must include the following headers:

  • x-definitive-api-key: Your API key
  • x-definitive-signature: The request payload signed with your secret
  • x-definitive-timestamp: The current timestamp

as well as content type and accept headers, here's an example of a fully formed CURL request:

curl -X GET "https://ddp.definitive.fi/v2/portfolio/positions?limit=10&offset=0" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "User-Agent: Mozilla/5.0" \
     -H "x-definitive-api-key: <key>" \
     -H "x-definitive-signature: <sig>" \
     -H "x-definitive-timestamp: 1741979832595"

Next Steps

In the next section, we'll walk through a sample request.