Overview

We'll walk through our orders endpoint /v1/orders which allows you to pull details about historical orders including notional price, status, size, and more.

Authentication

Before making a request, you need to generate an API key and secret. Refer to the api keys section of the overview for details on how to obtain your API credentials.

To authenticate your request, you must generate a signature using your API key and secret. The request headers should include:

x-definitive-api-key: Your API key
x-definitive-signature: A signature generated using your API secret
x-definitive-timestamp: The current timestamp

Making Your First Request

Here we'll dive into an example request, pulling all of our orders from /v1/orders. Please note that we've included a helper class AuthHelpers in the previous section to make this easier but we will be walking through the process manually here to help you understand how this works.

Step 1: Define API Key, Secret, and Timestamp

You'll need to access these values in the next few steps.

const apiKey = process.env.API_KEY;
const apiSecret = process.env.API_SECRET;
const timestamp = Date.now().toString();

Step 2: Prepare the Prehash

For maximum security we require that you use your api secret to sign the request that you're sending and that this signed request is submitted within 2 minutes of creation. To achieve this you must first create a "prehash" of the request. It should look like this:

${method}:${path}?${queryParamsString}:${timestamp}:${sortedHeaders}${bodyString};

type PrehashParams = {
  method: "GET" | "POST";
  path: string; // eg. /v1/orders
  timestamp: string; // stringified timestamp in ms
  headers: Record<string, string | number>;
  queryParams?: Record<string, string>;
  body?: string;
};
 
// if you're using typescript we recommend copying this method directly
function preparePrehash({
  method,
  timestamp,
  path,
  queryParams,
  headers,
  body,
}: PrehashParams) {
  const filtered = Object.entries(headers).filter(([key]) =>
    key.toLowerCase().startsWith("x-definitive-")
  );
 
  // ensure that the headers are sorted for consistency
  const sortedHeaders = filtered
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([key, value]) => `${key}:${JSON.stringify(value)}`)
    .join(",");
 
  // only pass x-definitive-api-key and x-definitive-timestamp
  if (filtered.length > 2) {
    throw new Error("Headers are too long - are you adding a new header?");
  }
 
  // stringify the query params eg. 'key=value&key2=value2'
  const queryParamsString = new URLSearchParams(queryParams).toString();
 
  const bodyString = body ?? "";
 
  return `${method}:${path}?${queryParamsString}:${timestamp}:${sortedHeaders}${bodyString}`;
}
 
const timestamp = Date.now().toString();
 
// generate the message to be signed
const message = preparePrehash({
  method: "GET",
  path: "/v1/orders",
  timestamp,
  headers: {
    "x-definitive-api-key": apiKey,
    "x-definitive-timestamp": timestamp,
  },
  queryParams: {},
});

Step 3: Sign the Request

Remove the dpks_ prefix from your api secret and use the resulting string to generate an HMAC of the secret and message.

const secret = apiSecret.replace("dpks_", "");
const signature = crypto
  .createHmac("sha256", secret)
  .update(message)
  .digest("hex");

Step 4: Make the request

These orders will be scoped ot the portfolio for which you created the keys. If you need data for another portfolio please generate another key / secret for that portfolio.

// Send request
const result = await fetch("https://ddp.definitive.fi/v1/orders", {
  method: "GET",
  headers: {
    "x-definitive-api-key": apiKey,
    "x-definitive-signature": signature,
    "x-definitive-timestamp": timestamp,
  },
});
 
// Parse response
const json = await result.json();
console.log(json);

The response will be a list of orders like so:

[
  {
    "orderDate": "2024-11-14T07:09:57.598Z",
    "rate": 1.3257605895554028,
    "filledNotional": 3.2845798790637404,
    "fromNotional": 3.2845798790637404,
    "vaultId": "12345678-1234-1234-1234-123412341234",
    "status": "ORDER_STATUS_FILLED",
    "fromTicker": "AERO",
    "toTicker": "cbBTC_0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf",
    "portfolioId": "12345678-1234-1234-1234-123412341234",
    "organizationId": "12345678-1234-1234-1234-123412341234",
    "organizationName": "My Portfolio",
    "closedAt": "2024-11-14T07:10:04.155Z",
    "orderId": "12345678-1234-1234-1234-123412341234",
    "size": 2.477506048181167,
    "filledSize": 2.477506048181167,
    "type": "ORDER_TYPE_MARKET",
    "acceptedAt": "2024-11-14T07:09:57.702Z",
    "maxPriceImpact": 0.05,
    "closeReason": "REASON_FULLY_FILLED"
  },
  {
    ...
  }
]

Error Handling

If the request fails, the API will return an error response with an appropriate status code and message. Common errors include:

401 Unauthorized: Invalid or missing API key/signature
403 Forbidden: Access denied
500 Internal Server Error: Unexpected server error

Summary

To fetch orders:

Generate a prehash message and sign it using your API secret.
Send a GET request to /v1/orders with the required headers.
Handle the response and possible errors appropriately.

For further details, refer to the Definitive API Documentation.