For AI Agents

// All API requests should be made to: https://ddp.definitive.fi/v1
 
// Authorization Helper Class
 
// The following TypeScript class handles request authorization, signing, and sending.
 
import crypto from "crypto";
 
export type DefinitiveApiKey = `dpka_${string}_${string}_${string}_${string}`;
export type DefinitiveApiSecret = `dpks_${string}`;
export type HTTPMethod = "GET" | "POST";
 
export type PrehashParams = {
  method: HTTPMethod;
  path: string;
  timestamp: string;
  headers: Record<string, string | number | object>;
  queryParams?: Record<string, string>;
  body?: string;
};
 
export class AuthHelpers {
  /**
   * Signs the message using HMAC SHA-256.
   * @param key - The secret key used for HMAC generation.
   * @param message - The message to be signed.
   * @returns HMAC signature.
   */
  static generateHMAC(key: string, message: string): string {
    return crypto.createHmac("sha256", key).update(message).digest("hex");
  }
 
  /**
   * Client-side signing of the prehash message.
   * @param apiSecret - The secret key.
   * @param message - The message to sign.
   * @returns Signed message.
   */
  static clientSignMessage(apiSecret: DefinitiveApiSecret, message: string) {
    const secret = apiSecret.replace("dpks_", "");
    return AuthHelpers.generateHMAC(secret, message);
  }
 
  /**
   * Generates a prehash string to sign the request.
   * @param params - The request parameters.
   * @returns The prehash string.
   */
  static preparePrehash({
    method,
    timestamp,
    path,
    headers,
    queryParams,
    body,
  }: PrehashParams) {
    const filteredHeaders = Object.entries(headers)
      .filter(([key]) => key.toLowerCase().startsWith("x-definitive-"))
      .sort(([a], [b]) => a.localeCompare(b))
      .map(([key, value]) => `${key}:${JSON.stringify(value)}`)
      .join(",");
 
    if (filteredHeaders.length > 2) {
      throw new Error("Headers are too long - are you adding a new header?");
    }
 
    const queryParamsString = new URLSearchParams(queryParams).toString();
    const bodyString = body ?? "";
 
    return `${method}:${path}?${queryParamsString}:${timestamp}:${filteredHeaders}${bodyString}`;
  }
 
  /**
   * Prepares, signs, and sends the request.
   * @param apiKey - The API key.
   * @param apiSecret - The API secret.
   * @param path - The request path.
   * @param method - The HTTP method.
   */
  static async signAndSend({
    apiKey,
    apiSecret,
    path,
    method,
    body,
    queryParams = {},
  }: {
    apiKey: DefinitiveApiKey;
    apiSecret: DefinitiveApiSecret;
    path: string;
    method: HTTPMethod;
    body?: unknown;
    queryParams?: Record<string, string>;
  }) {
    const timestamp = Date.now().toString();
 
    const headers = {
      "x-definitive-api-key": apiKey,
      "x-definitive-timestamp": timestamp,
    };
 
    // Prepare prehash message
    const message = AuthHelpers.preparePrehash({
      method,
      path,
      timestamp,
      headers,
      queryParams,
      body: body ? JSON.stringify(body) : undefined,
    });
 
    // Generate signature
    const signature = AuthHelpers.clientSignMessage(apiSecret, message);
 
    // Send request
    const baseURL = "https://ddp.definitive.fi";
    const result = await fetch(`${baseURL}${path}`, {
      method,
      headers: {
        ...headers,
        "x-definitive-signature": signature,
        "Content-Type": "application/json",
      },
      body: body ? JSON.stringify(body) : undefined,
    });
 
    return result.json();
  }
}
 
// API Information
 
// 1. Portfolio Information
 
// Get portfolio metadata and vaults:
 
const portfolioResponse = await AuthHelpers.signAndSend({
  path: "/v1/portfolio",
  method: "GET",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
// Response type
type PortfolioResponse = {
  portfolioId: string;
  portfolioName: string;
  organizationId: string;
  createdAt: string;
  vaults: {
    vaultId: string;
    address: string;
    name: string;
    status: string;
    chain: {
      name: string;
      id: string;
      namespace: string;
    };
  }[];
};
 
// 2. Positions
 
// Get current positions with optional dust filter:
 
const positionsResponse = await AuthHelpers.signAndSend({
  path: "/v1/positions",
  method: "GET",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
  queryParams: { showDust: "true" },
});
 
// Response type
type Position = {
  asset: {
    name: string;
    address: string;
    ticker: string;
    chain: {
      name: string;
      id: string;
      namespace: string;
    };
  };
  balance: number;
  notional: number;
  portfolioId: string;
  vaultId: string;
};
 
// 3. Orders
 
// Get all orders:
const ordersResponse = await AuthHelpers.signAndSend({
  path: "/v1/orders",
  method: "GET",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
// Response type
type Order = {
  fromAsset: {
    id: string;
    name: string;
    address: string;
    ticker: string;
    chain: {
      name: string;
      id: string;
      namespace: string;
    };
  };
  toAsset: {
    id: string;
    name: string;
    address: string;
    ticker: string;
    chain: {
      name: string;
      id: string;
      namespace: string;
    };
  };
  fromAmount: number;
  toAmount: number;
  orderDate: string;
  acceptedAt: string;
  closedAt: string;
  closeReason: string;
  filledSize: number;
  fromNotional: number;
  maxPriceImpact: number;
  orderId: string;
  organizationName: string;
  portfolioId: string;
  rate: number;
  size: number;
  status: string;
  type: string;
  vaultId: string;
};
 
// 4. Order Details
 
// Get details for a specific order:
 
const orderDetailsResponse = await AuthHelpers.signAndSend({
  path: `/v1/orders/${orderId}`,
  method: "GET",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
// Response type
type OrderDetails = {
  order: Order;
  fills: {
    id: string;
    status: string;
    feeAmount: number;
    notional: number;
    fromAmount: number;
    toAmount: number;
    venue: string;
  }[];
};
 
// Trade Quote
 
// Get a quote for a trade:
 
const quoteRequest = {
  type: "market", // or "limit" or "twap"
  chain: "base",
  from: "0xA12B34C56D78E90F12AB34CD56EF78A901BC234D", // From token address
  to: "0xF98765C43210D78E90AB56CD12EF34A908BC765D", // To token address
  qty: "1000.00",
  orderSide: "sell",
  slippageTolerance: "0.01",
  maxPriceImpact: "0.05",
};
 
const quoteResponse = await AuthHelpers.signAndSend({
  path: "/v1/trade/quote",
  method: "POST",
  body: quoteRequest,
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
// Response type
type QuoteResponse = {
  quote: {
    from: string;
    to: string;
    chain: string;
    qty: string;
    orderSide: "buy" | "sell";
    maxPriceImpact: string;
    slippageTolerance: string;
    quoteId: string;
    quotedAmountOut: string;
    quotedPriceImpact: string;
    type: "market" | "limit" | "twap";
  };
  metadata: {
    toNotional: string;
    fromNotional: string;
    estimatedPriceImpact: string;
    estimatedFee: string;
    estimatedFeeNotional: string;
    buyAmount: string;
    sellAmount: string;
    sources: Record<string, string>;
    expectedSlippage: string;
    minAmountOut: string;
    minAmountOutNotional: string;
    price: string;
    isMarketable: boolean;
  };
};
 
// Submit Trade
 
// Submit a trade order:
 
const orderResponse = await AuthHelpers.signAndSend({
  path: "/v1/trade",
  method: "POST",
  body: quoteResponse.quote, // Use the quote from the previous step
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
// Response type
type OrderResponse = {
  orderId: string;
  vaultIds: string[];
  chains: string[];
  status: string;
  from: string;
  fromAddress: string;
  to: string;
  toAddress: string;
  size: number;
  filledSize: number;
  orderType: string;
  createdAt: string;
  startsAt: string;
  acceptedAt: string;
  fills: any[];
  pendingCancel: boolean;
  paused: boolean;
  maxPriceImpact: number;
  slippageTolerance: number;
  side: "buy" | "sell";
};
 
// Cancel Order
 
// Cancel an existing order:
 
const cancelResponse = await AuthHelpers.signAndSend({
  path: `/v1/trade/${orderId}`,
  method: "DELETE",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
// Response type
type CancelResponse = {
  success: boolean;
  message: string;
};
 
// Response
 
{
  transfers: [
    {
      vaultLedgerId: string, // e.g. "9f725289-ed42-42ee-8e03-10168fd764d0"
      vaultId: string, // e.g. "a1859005-cd44-4bda-83f7-c6253a39c805"
      vaultDelta: number, // e.g. 0.028363
      transactionId: string, // e.g. "0xc5f5f8bb9c82214f1d25e8b8711a1fb27aad93c21bc3c235c26cdef20821ec9c"
      timestamp: string, // ISO date string e.g. "2025-03-12T07:35:10.233Z"
      actionType: string, // e.g. "VAULT_ACTION_DEPOSIT"
      notionalValue: number, // e.g. 0.028357525940999998
      asset: {
        id: string, // e.g. "bcf2f301-1db9-4e12-b3fd-da79e91d3940"
        name: string, // e.g. "USDC"
        ticker: string, // e.g. "USDC"
        address: string, // e.g. "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        chain: {
          id: string, // e.g. "8453"
          name: string, // e.g. "Base"
          namespace: string // e.g. "eip155"
        }
      }
    }
    // ... additional transfers
  ],
  limit: number, // e.g. 10
  offset: number, // e.g. 0
  totalCount: number // Total number of transfers available, e.g. 1387945
}
 
// Example
const json = await AuthHelpers.signAndSend({
  path: "/v1/portfolio/transfers",
  method: "GET",
  queryParams: {
    limit: 10,
    offset: 0,
    actionTypes: ["VAULT_ACTION_DEPOSIT", "VAULT_ACTION_WITHDRAWAL"],
    startTimestamp: new Date("2024-01-01").toISOString(),
    endTimestamp: new Date("2024-12-31").toISOString(),
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
console.log(json);
 
// Important Notes
//
// 1. All timestamps are in UTC
// 2. API keys must be generated from the [organization page](https://app.definitive.fi/account/// organization)
// 3. API secrets are only shown once during generation - store them securely
// 4. Requests must be signed and submitted within 2 minutes of signing
// 5. All amounts/numbers in requests should be strings to maintain precision
// 6. The base URL is `https://ddp.definitive.fi/v1`
//
// Error Handling
//
// Common HTTP status codes:
//
// - 401: Unauthorized (invalid/missing API key/signature)
// - 403: Forbidden (insufficient permissions)
// - 500: Internal Server Error
//
// Supported Chains
//
// - Ethereum
// - Optimism
// - Arbitrum
// - Avalanche
// - Polygon
// - Base
// - Solana
// - Blast