### Full Deposit Flow Integration Example

Source: https://ddp.definitive.fi/api/portfolio-info/get-deposit-address

This snippet demonstrates the complete integration flow for deposits, starting with getting the deposit address and outlining the subsequent steps for fund processing.

```javascript
// Step 1: Get the deposit address
const addressResponse = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/address/ethereum",
  method: "GET",
  queryParams: {
    walletAddress: "0x742d35Cc6634C0532925a3b8D400eE6a0b8CBd6",
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
const vaultAddress = addressResponse.address;
 
// Step 2: User sends funds to vaultAddress
// (This happens outside the API - user sends ETH/tokens to the address)
 
// Step 3: Assets will be automatically detected and credited to the portfolio.
// For native EVM assets (e.g. ETH/BNB/MATIC/AVAX), call "Refresh Balance"
// and wait 1-2 seconds for portfolio to update.
```

--------------------------------

### Example Request to Get QuickTrade Quote

Source: https://ddp.definitive.fi/api/quicktrade/quote

An example of how to call the QuickTrade quote endpoint using AuthHelpers.signAndSend. This demonstrates setting the path, method, body parameters, and API credentials.

```javascript
const quoteResponse = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/quicktrade/quote",
  method: "POST",
  body: {
    chain: "ethereum",
    targetAsset: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", // WETH
    contraAsset: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
    qty: "1000",
    orderSide: "buy",
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
```

--------------------------------

### Get Solana Deposit Address

Source: https://ddp.definitive.fi/api/portfolio-info/get-deposit-address

This example shows how to get a deposit address for a Solana vault. Remember to use a valid Solana wallet address.

```javascript
const solanaAddress = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/address/solana",
  method: "GET",
  queryParams: {
    walletAddress: "GszaaaaaaaaaaaaaaaaaaaaaaaaVcx",
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
```

--------------------------------

### Get Quote and Submit Trade Example

Source: https://ddp.definitive.fi/api/trade/submit

Demonstrates the process of first obtaining a quote for a trade and then submitting the actual trade using the obtained quote ID. Ensure the quote is submitted immediately as they are short-lived.

```javascript
// Build the order request once and reuse it for quote + submit
const externalOrderRequest = {
  type: "market",
  chain: "ethereum",
  targetAsset: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
  contraAsset: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", // WETH
  qty: "1000",
  orderSide: "buy",
  slippageTolerance: "0.01",
  maxPriceImpact: "0.01",
};
 
// First, get a quote
const quoteResponse = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/trade/quote",
  method: "POST",
  body: externalOrderRequest,
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
// Then, submit the trade with quoteId + the same order request
const tradeResponse = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/trade",
  method: "POST",
  body: {
    externalOrderRequest,
    quoteId: quoteResponse.quote.quote.id,
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
console.log("Trade Response:", tradeResponse);
```

--------------------------------

### Create Portfolio Response Example

Source: https://ddp.definitive.fi/api/organization/portfolio/create

This is an example of a successful response when creating a new portfolio. It includes the unique portfolio ID and creation timestamp.

```json
{
  "portfolioId": "00000000-0000-0000-0000-000000000001",
  "portfolioName": "New Trading Portfolio",
  "createdAt": "2024-08-05 20:48:11.584827"
}
```

--------------------------------

### Make Authenticated Request to Portfolio API

Source: https://ddp.definitive.fi/api/getting-started

Send a GET request to the Portfolio API endpoint with the generated API key, signature, and timestamp in the headers. This example demonstrates fetching orders.

```javascript
const result = await fetch("https://ddp.definitive.fi/v2/portfolio/orders", {
  method: "GET",
  headers: {
    "x-definitive-api-key": apiKey,
    "x-definitive-signature": signature,
    "x-definitive-timestamp": timestamp,
  },
});
const json = await result.json();
```

--------------------------------

### Retrieve Portfolio Fees with Start Timestamp Only

Source: https://ddp.definitive.fi/api/organization/portfolio/fees

Use this to get fee data for a portfolio starting from a specific timestamp. The end timestamp is optional. Requires an organization-level API key.

```javascript
const result2 = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/fees",
  method: "GET",
  queryParams: {
    startTimestamp: "2023-07-21T05:19:18.000Z",
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
```

--------------------------------

### Example API Response for Portfolio Fees

Source: https://ddp.definitive.fi/api/organization/portfolio/fees

This is an example of the JSON response structure when retrieving portfolio fee data. It includes portfolio and organization details, fee breakdowns, and the time period for the calculation.

```json
{
  "portfolioId": "00000000-0000-0000-0000-000000000003",
  "portfolioName": "examplePortfolio",
  "organizationName": "exampleOrganization",
  "netNotionalVolume": "1000",
  "netNotionalFees": "20.03",
  "netBaseFees": "19.3",
  "netGasFees": "1",
  "period": {
    "start": "2025-08-12T16:29:20.000Z",
    "end": "2025-08-14T16:29:20.000Z",
  },
}
```

--------------------------------

### Paginate Through All Portfolio Positions

Source: https://ddp.definitive.fi/api/portfolio-info/positions

This example demonstrates how to paginate through all positions in an organization's portfolio. It repeatedly fetches data using the `nextCursor` until all positions are retrieved. This is useful for handling large datasets.

```javascript
let cursor = null;
let allPositions = [];
 
do {
  const queryParams = { limit: "20" };
  if (cursor) queryParams.cursor = cursor;
 
  const response = await AuthHelpers.signAndSend({
    path: `/v2/organization/portfolios/${portfolioId}/positions`,
    method: "GET",
    apiKey: process.env.API_KEY,
    apiSecret: process.env.API_SECRET,
    queryParams,
  });
 
  allPositions.push(...response.positions);
  cursor = response.nextCursor;
} while (response.hasMore);
```

--------------------------------

### Order Details Response Example

Source: https://ddp.definitive.fi/api/orders/details

This is a sample response for a partially filled order, showing details like order ID, status, asset information, filled amounts, and placement times.

```json
{
  "order": {
    "orderId": "00000000-0000-0000-0000-000000000005",
    "type": "ORDER_TYPE_LIMIT",
    "status": "ORDER_STATUS_PARTIALLY_FILLED",
    "orderSide": "ORDER_SIDE_BUY",
    "targetAsset": {
      "id": "00000000-0000-0000-0000-000000000010",
      "name": "USD Coin",
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "ticker": "USDC",
      "chain": { "name": "Ethereum", "id": "1", "namespace": "eip155" }
    },
    "contraAsset": {
      "id": "00000000-0000-0000-0000-000000000011",
      "name": "Wrapped Ether",
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "ticker": "WETH",
      "chain": { "name": "Ethereum", "id": "1", "namespace": "eip155" }
    },
    "filled": {
      "targetAssetAmount": "899625.000000",
      "contraAssetAmount": "500.000000",
      "averagePrice": "1799.25",
      "averageNotionalPrice": "1799.50"
    },
    "size": {
      "amount": "1000.000000",
      "filled": "750.000000",
      "asset": "contra"
    },
    "maxPriceImpact": "0.01",
    "limit": { "isNotional": false, "price": "1800.00" },
    "trigger": { "isNotional": false, "price": "" },
    "placedAt": "2024-08-05T20:48:11.584Z",
    "acceptedAt": "2024-08-05T20:48:12.584Z",
    "closedAt": null,
    "closeReason": null,
    "organizationName": "Example Organization",
    "portfolioId": "00000000-0000-0000-0000-000000000004",
    "vaultId": "00000000-0000-0000-0000-000000000003"
  },
  "fills": [
    {
      "status": "CHAIN_STATUS_FINALIZED",
      "notional": "1799625.000000",
      "venues": ["Uniswap V3"],
      "filledAt": "2024-08-05T20:48:30.584Z",
      "rootOrderId": "00000000-0000-0000-0000-000000000005",
      "orderId": "00000000-0000-0000-0000-000000000006",
      "parentOrderId": "00000000-0000-0000-0000-000000000005",
      "transactionId": "0x1234567890abcdef...",
      "fillPrice": "1799.25",
      "feeAmount": "0.5",
      "feeTicker": "WETH",
      "tradeFeeAmount": "0.45",
      "networkFeeAmount": "0.05",
      "feeNotional": "900.00",
      "tradeFeeNotional": "810.00",
      "networkFeeNotional": "90.00",
      "contraAmount": "500.000000",
      "targetAmount": "899625.000000"
    }
  ]
}
```

--------------------------------

### TWAP Order Details Response Example

Source: https://ddp.definitive.fi/api/orders/details

This example shows the response structure for a TWAP (Time-Weighted Average Price) order, highlighting the additional `twap` field with `buckets` and `durationSeconds`.

```json
{
  "order": {
    "orderId": "00000000-0000-0000-0000-000000000008",
    "type": "ORDER_TYPE_TWAP",
    "status": "ORDER_STATUS_FILLED",
    "orderSide": "ORDER_SIDE_BUY",
    "targetAsset": {
      "id": "...", "name": "USD Coin", "address": "0xa0b...", "ticker": "USDC",
      "chain": { "name": "Ethereum", "id": "1", "namespace": "eip155" }
    },
    "contraAsset": {
      "id": "...", "name": "Wrapped Ether", "address": "0xc02...", "ticker": "WETH",
      "chain": { "name": "Ethereum", "id": "1", "namespace": "eip155" }
    },
    "filled": {
      "targetAssetAmount": "...",
      "contraAssetAmount": "...",
      "averagePrice": "...",
      "averageNotionalPrice": "..."
    },
    "size": { "amount": "1000.000000", "filled": "1000.000000", "asset": "contra" },
    "maxPriceImpact": "0.01",
    "limit": { "isNotional": false, "price": "" },
    "trigger": { "isNotional": false, "price": "" },
    "twap": { "buckets": 6, "durationSeconds": 3600 },
    "placedAt": "2024-08-05T20:48:11.584Z",
    "acceptedAt": "2024-08-05T20:48:12.584Z",
    "closedAt": "2024-08-05T21:48:11.584Z",
    "closeReason": "REASON_FULLY_FILLED",
    "organizationName": "...",
    "portfolioId": "...",
    "vaultId": "..."
  },
  "fills": [...]
```

--------------------------------

### Paginate Through All Orders

Source: https://ddp.definitive.fi/api/orders/list

This example illustrates how to fetch all orders for a portfolio by repeatedly calling the API and using the `nextCursor` from the response to paginate through the results until `hasNextPage` is false. It also shows how to construct query parameters for each request.

```javascript
let cursor = null;
let allOrders = [];
 
do {
  const queryParams = { limit: "50" };
  if (cursor) queryParams.cursor = cursor;
 
  const response = await AuthHelpers.signAndSend({
    path: `/v2/organization/portfolios/${portfolioId}/orders`,
    method: "GET",
    queryParams,
    apiKey: process.env.API_KEY,
    apiSecret: process.env.API_SECRET,
  });
 
  allOrders.push(...response.orders);
  cursor = response.nextCursor;
} while (response.hasNextPage);
```

--------------------------------

### Retrieve Portfolio Fees with Time Range

Source: https://ddp.definitive.fi/api/organization/portfolio/fees

Use this to get fee data for a portfolio between a start and end timestamp. Ensure you have an organization-level API key.

```javascript
const result1 = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/fees",
  method: "GET",
  queryParams: {
    startTimestamp: "2025-08-12T16:29:20.000Z",
    endTimestamp: "2025-08-14T16:29:20.000Z",
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
```

--------------------------------

### Make Authenticated Request to Organization API

Source: https://ddp.definitive.fi/api/getting-started

Send a GET request to the Organization API endpoint, including necessary headers like API key, signature, and timestamp. This example shows fetching organization data.

```javascript
const result = await fetch("https://ddp.definitive.fi/v2/organization", {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
    "x-definitive-api-key": apiKey,
    "x-definitive-signature": signature,
    "x-definitive-timestamp": timestamp,
  },
});
const json = await result.json();
```

--------------------------------

### Define API Key, Secret, and Timestamp

Source: https://ddp.definitive.fi/api/getting-started

Set up your API key, secret, and a timestamp for authentication. Ensure these are securely managed, for example, by using environment variables.

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

--------------------------------

### Initialize and Make Organization API Call

Source: https://ddp.definitive.fi/overview

Initialize with organization credentials and make a GET request to retrieve organization details and portfolios. Ensure API key and secret are securely stored.

```javascript
import { AuthHelpers } from "./auth-helpers";

// Initialize with your organization credentials
const apiKey = process.env.DEFINITIVE_API_KEY;
const apiSecret = process.env.DEFINITIVE_API_SECRET;

// Example: Get organization details and portfolios
const organizationData = await AuthHelpers.signAndSend({
  path: "/v2/organization",
  method: "GET",
  apiKey,
  apiSecret,
});
```

--------------------------------

### EVM Withdrawal Response Example

Source: https://ddp.definitive.fi/api/organization/portfolio/withdraw

This is an example of a successful response when submitting an EVM transaction. Use the transactionId to poll for status.

```json
{
  "transactionId": "00000000-0000-0000-0000-000000000010",
  "status": "submitted",
  "chain": "ethereum",
  "debug": {
    "requestReceived": {
      "portfolioId": "00000000-0000-0000-0000-000000000001",
      "chain": "ethereum",
      "userOpHash": "0xabcdef...",
      "hasSignature": true,
      "sender": "0x742d35...",
      "timestamp": "2024-08-05T20:48:11.584Z"
    },
    "responseGenerated": {
      "transactionId": "00000000-0000-0000-0000-000000000010",
      "timestamp": "2024-08-05T20:48:12.100Z"
    }
  }
}
```

--------------------------------

### Market Order Quote Request

Source: https://ddp.definitive.fi/api/trade/quote

Example of how to request a quote for a market order.

```APIDOC
## Market Order Quote Request

### Description
This example demonstrates how to request a quote for a market order using the API.

### Method
POST

### Endpoint
/v2/portfolio/trade/quote

### Parameters
#### Request Body
- **type** (string) - Required - Must be `"market"`
- **chain** (string) - Required - The blockchain network (e.g., `"ethereum"`)
- **targetAsset** (string) - Required - The asset to be bought or sold
- **contraAsset** (string) - Required - The asset used for trading (e.g., stablecoin)
- **qty** (string) - Required - The quantity of the target asset to trade
- **orderSide** (string) - Required - `"buy"` or `"sell"`
- **slippageTolerance** (string) - Required - The maximum acceptable slippage
- **maxPriceImpact** (string) - Required - The maximum acceptable price impact

### Request Example
```javascript
const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/trade/quote",
  method: "POST",
  body: {
    type: "market",
    chain: "ethereum",
    targetAsset: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
    contraAsset: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", // WETH
    qty: "1000",
    orderSide: "buy",
    slippageTolerance: "0.01",
    maxPriceImpact: "0.01",
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
```

### Response
#### Success Response (200)
- **quote** (object) - Details of the quoted order
- **metadata** (object) - Metadata about the quote

#### Response Example
```json
{
  "quote": {
    "type": "market",
    "chain": "ethereum",
    "targetAsset": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "contraAsset": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "qty": "1000",
    "orderSide": "buy",
    "quote": {
      "id": "00000000-0000-0000-0000-000000000004",
      "amountOut": "0.555555",
      "priceImpact": "0.0025"
    },
    "slippageTolerance": "0.01",
    "maxPriceImpact": "0.01"
    // ...order-type-specific fields (e.g., trigger, limit, durationSeconds)
  },
  "metadata": {
    "toNotional": "1000.00",
    "fromNotional": "999.95",
    "estimatedPriceImpact": "0.0025",
    "estimatedFee": "1.50",
    "estimatedFeeNotional": "1.50",
    "buyAmount": "0.555555",
    "sellAmount": "1000",
    "sources": {"0x": "1.0"},
    "expectedSlippage": "0.005",
    "minAmountOut": "0.550000",
    "minAmountOutNotional": "995.00",
    "price": "0.000556",
    "isMarketable": true,
    "warnings": [] // optional, present when order size is below minimum
  }
}
```
```

--------------------------------

### Combine Filters and Pagination

Source: https://ddp.definitive.fi/api/orders/list

This example shows how to combine pagination parameters (`limit`, `cursor`) with filters to retrieve a specific subset of orders. It filters for 'CANCELLED' orders and sets a limit of 50.

```javascript
const queryParams = {
  limit: "50",
  cursor: "2025-06-05T01:26:30.560Z",
  filters: JSON.stringify({ status: "ORDER_STATUS_CANCELLED" }),
};
```

--------------------------------

### Portfolio API Response Structure

Source: https://ddp.definitive.fi/api/portfolio-info/details

This is an example of the JSON response structure when retrieving portfolio details. It includes portfolio information, vault details, and chain configurations.

```json
{
  portfolioId: "00000000-0000-0000-0000-000000000001",
  portfolioName: "Example Portfolio",
  organizationId: "00000000-0000-0000-0000-000000000002",
  createdAt: "2024-08-05T20:48:11.584Z",
  vaults: [
    {
      vaultId: "00000000-0000-0000-0000-000000000003",
      address: "0x0000000000000000000000000000000000000001",
      name: "Trading Vault",
      status: "VAULT_STATUS_ACTIVE",
      chain: {
        name: "Ethereum",
        id: "1",
        namespace: "eip155"
      },
      signers: [
        "0x0000000000000000000000000000000000000099"
      ]
    }
    // ... additional vaults
  ]
}
```

--------------------------------

### Get Order Details Request

Source: https://ddp.definitive.fi/api/orders/details

Use this snippet to make a GET request to retrieve details for a specific order. Ensure you have your API key and secret configured in the environment variables.

```javascript
const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/orders/00000000-0000-0000-0000-000000000001",
  method: "GET",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
console.log(json);
```

--------------------------------

### Get Portfolio Details

Source: https://ddp.definitive.fi/api/portfolio-info/details

Use this snippet to retrieve detailed metadata for a specific portfolio. Ensure you have your API key and secret configured in the environment variables.

```javascript
const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio",
  method: "GET",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
console.log(json);
```

--------------------------------

### Filter Orders by Status

Source: https://ddp.definitive.fi/api/orders/list

Use the `filters` query parameter to specify criteria for filtering orders. This example demonstrates filtering for orders with a 'FILLED' status.

```javascript
const queryParams = {
  filters: JSON.stringify({ status: "ORDER_STATUS_FILLED" }),
};
```

--------------------------------

### List Portfolios - Pagination Loop

Source: https://ddp.definitive.fi/api/organization/portfolios

Demonstrates a loop to fetch all portfolios, handling pagination by repeatedly requesting data until no more pages are available.

```javascript
let cursor = null;
let allPortfolios = [];

do {
  const queryParams = { limit: "50" };
  if (cursor) queryParams.cursor = cursor;

  const response = await AuthHelpers.signAndSend({
    path: "/v2/organization",
    method: "GET",
    queryParams,
    apiKey: process.env.API_KEY,
    apiSecret: process.env.API_SECRET,
  });

  allPortfolios.push(...response.data);
  cursor = response.pagination.nextCursor;
} while (response.pagination.hasMore);
```

--------------------------------

### Execute a QuickTrade

Source: https://ddp.definitive.fi/api/quicktrade/submit

Use this snippet to perform an instant trade. Ensure you have your API key and secret configured. The `AuthHelpers.signAndSend` function handles authentication and sending the request.

```javascript
const tradeResponse = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/quicktrade",
  method: "POST",
  body: {
    chain: "ethereum",
    targetAsset: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", // WETH
    contraAsset: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
    qty: "1000",
    orderSide: "buy",
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
```

--------------------------------

### GET /v2/portfolio/address/{chain}

Source: https://ddp.definitive.fi/api/portfolio-info/get-deposit-address

Retrieves the deposit address for a portfolio's vault on a specific blockchain. This endpoint is useful for getting the vault address where users should send their deposits.

```APIDOC
## GET /v2/portfolio/address/{chain}

### Description
Retrieves the deposit address for a portfolio's vault on a specific blockchain. This endpoint is useful for getting the vault address where users should send their deposits.

### Method
GET

### Endpoint
`https://ddp.definitive.fi/v2/portfolio/address/{chain}`

*Note: For Organization API, replace `/v2/portfolio/` with `/v2/organization/portfolios/{portfolioId}/`.*

### Parameters
#### Path Parameters
- **chain** (string) - Required - Blockchain network (see Supported Networks for full list)

#### Query Parameters
- **walletAddress** (string) - Required - User wallet address for the chain

### Request Example
```javascript
const ethAddress = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/address/ethereum",
  method: "GET",
  queryParams: {
    walletAddress: "0x742d35Cc6634C0532925a3b8D400eE6a0b8CBd6",
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});

const solanaAddress = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/address/solana",
  method: "GET",
  queryParams: {
    walletAddress: "GszaaaaaaaaaaaaaaaaaaaaaaaaVcx",
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
```

### Response
#### Success Response (200)
- **vaultId** (string) - UUID of the vault associated with the address
- **address** (string) - The deposit address where funds should be sent

#### Response Example
```json
{
  "vaultId": "00000000-0000-0000-0000-000000000002",
  "address": "0x1234567890abcdef1234567890abcdef12345678"
}
```

### Notes
- **Vault Creation**: If a vault doesn't exist for the specified chain, it will be created automatically.
- **Address Format**: The returned address is the actual blockchain address where deposits should be sent.
- **Chain Compatibility**: The `walletAddress` parameter must be a valid address format for the specified chain.
- **Authentication**: Requests must be signed and include the correct headers. See Request Authorization for details.
```

--------------------------------

### Initiate Asset Withdrawal (EVM)

Source: https://ddp.definitive.fi/api/organization/portfolio/withdraw

Use this to initiate an EVM withdrawal. Ensure `destinationAddress` and `sponsor_evm: true` are provided. The response contains `evmUserOp` and `evmUserOpHash` for the next step.

```javascript
const json = await AuthHelpers.signAndSend({
  path: "/v2/organization/portfolios/00000000-0000-0000-0000-000000000001/withdraw",
  method: "POST",
  body: {
    chain: "ethereum",
    asset: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
    amount: "500000000", // 500 USDC (6 decimals)
    walletAddress: "0x123456aaaaaaaaaaaaa45678",
    destinationAddress: "0x742d35aaaaaaaaaaaaaaaaaa",
    sponsor_evm: true, // required for EVM withdrawals
  },
 
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
```

--------------------------------

### List Portfolios - First Page

Source: https://ddp.definitive.fi/api/organization/portfolios

Fetches the first page of portfolios. Ensure you have your API key and secret configured.

```javascript
const json = await AuthHelpers.signAndSend({
  path: "/v2/organization",
  method: "GET",
  queryParams: { limit: "10" },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
```

--------------------------------

### Balance Refresh Response

Source: https://ddp.definitive.fi/api/organization/portfolio/refresh-balance

This is an example of the response received after a successful balance refresh operation. It confirms the vault ID that was refreshed.

```json
{
  vaultId: "00000000-0000-0000-0000-000000000003";
}
```

--------------------------------

### Using QuickTrade Quote with Submit Endpoint

Source: https://ddp.definitive.fi/api/quicktrade/quote

Demonstrates a two-step process: first obtaining a quote, then reviewing it for acceptable slippage before executing the trade using the QuickTrade submit endpoint. This ensures trades are executed only if they meet predefined criteria.

```javascript
// 1. Get quote
const quote = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/quicktrade/quote",
  method: "POST",
  body: tradeParams,
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
 
// 2. Review quote, then execute if acceptable
if (parseFloat(quote.metadata.expectedSlippage) < 0.02) {
  // Less than 2% slippage
  const execution = await AuthHelpers.signAndSend({
    path: "/v2/portfolio/quicktrade",
    method: "POST",
    body: tradeParams, // Same parameters
    apiKey: process.env.API_KEY,
    apiSecret: process.env.API_SECRET,
  });
}
```

--------------------------------

### GET /v2/portfolio/orders

Source: https://ddp.definitive.fi/api/orders/list

Retrieves the order history for a portfolio. This endpoint can be used directly or adapted for organization-level portfolios by modifying the path.

```APIDOC
## GET /v2/portfolio/orders

### Description
Retrieves the order history for a portfolio, including all order types and their current status.

### Method
GET

### Endpoint
`https://ddp.definitive.fi/v2/portfolio/orders`

**Note:** For organization-level portfolios, use `/v2/organization/portfolios/{portfolioId}/orders`.

### Query Parameters
#### Query Parameters
- **limit** (number) - Optional - Maximum number of orders to return. Default: 100
- **cursor** (string) - Optional - ISO 8601 timestamp for pagination (order `closedAt`).
- **filters** (string) - Optional - JSON string of filters. See Filters section below.

### Filters
The `filters` parameter accepts a JSON string with the following optional fields:
- **status** (string) - Required - Filter orders by status. Valid Values: `ORDER_STATUS_PENDING`, `ORDER_STATUS_ACCEPTED`, `ORDER_STATUS_PARTIALLY_FILLED`, `ORDER_STATUS_FILLED`, `ORDER_STATUS_CANCELLED`

### Filter Examples
**Filter by status:**
```javascript
const queryParams = {
  filters: JSON.stringify({ status: "ORDER_STATUS_FILLED" }),
};
```

**Combine filters with pagination:**
```javascript
const queryParams = {
  limit: "50",
  cursor: "2025-06-05T01:26:30.560Z",
  filters: JSON.stringify({ status: "ORDER_STATUS_CANCELLED" }),
};
```

### Request Example
```javascript
const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/orders",
  method: "GET",
  queryParams: {
    limit: "20",
    filters: JSON.stringify({ status: "ORDER_STATUS_FILLED" }),
  },
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
```

### Response
#### Success Response (200)
- **orders** (array) - An array of order objects.
- **limit** (number) - The limit applied to the request.
- **nextCursor** (string) - ISO timestamp for the next page of results.
- **hasNextPage** (boolean) - Indicates if there are more pages available.

#### Response Example
```json
{
  "orders": [
    {
      "orderId": "00000000-0000-0000-0000-000000000005",
      "type": "ORDER_TYPE_TWAP",
      "status": "ORDER_STATUS_FILLED",
      "orderSide": "ORDER_SIDE_SELL",
      "contraAsset": {
        "id": "00000000-0000-0000-0000-000000000001",
        "name": "Hyperliquid",
        "address": "1000003",
        "ticker": "HYPE",
        "chain": { "name": "Hyperevm", "id": "999", "namespace": "eip155" }
      },
      "targetAsset": {
        "id": "00000000-0000-0000-0000-000000000002",
        "name": "SUPERMILK",
        "address": "0xfe69bc93b936b34d371defa873686c116c8488c2",
        "ticker": "MILK",
        "chain": { "name": "Hyperevm", "id": "999", "namespace": "eip155" }
      },
      "filled": {
        "targetAssetAmount": "2678483.226019",
        "contraAssetAmount": "27.54374",
        "averagePrice": "35.43",
        "averageNotionalPrice": "975.8747082"
      },
      "size": {
        "amount": "27.54374",
        "filled": "27.54374",
        "asset": "target"
      },
      "maxPriceImpact": "0.05",
      "limit": { "isNotional": false, "price": "" },
      "trigger": { "isNotional": false, "price": "" },
      "placedAt": "2025-06-05T07:36:49.045Z",
      "acceptedAt": "2025-06-05T07:36:49.403Z",
      "closedAt": "2025-06-06T07:34:43.048Z",
      "closeReason": "REASON_FULLY_FILLED",
      "organizationName": "Example Organization",
      "portfolioId": "00000000-0000-0000-0000-000000000004",
      "vaultId": "00000000-0000-0000-0000-000000000003",
      "twap": { "buckets": 6, "durationSeconds": 3600 }
    }
  ],
  "limit": 100,
  "nextCursor": "2024-08-05T20:48:11.584Z",
  "hasNextPage": true
}
```

### Pagination
This endpoint uses cursor-based pagination based on the `closedAt` timestamp:
  * **First Request** : Omit the `cursor` parameter
  * **Subsequent Requests** : Use the `nextCursor` value from the previous response
  * **End of Data** : When `hasNextPage` is `false`, there are no more orders to fetch
  * **Cursor Format** : The cursor is an ISO 8601 timestamp string (e.g., `"2024-08-05T20:48:11.584Z"`)

### Pagination Example
```javascript
let cursor = null;
let allOrders = [];
 
do {
  const queryParams = { limit: "50" };
  if (cursor) queryParams.cursor = cursor;
 
  const response = await AuthHelpers.signAndSend({
    path: `/v2/organization/portfolios/${portfolioId}/orders`,
    method: "GET",
    queryParams,
    apiKey: process.env.API_KEY,
    apiSecret: process.env.API_SECRET,
  });
 
  allOrders.push(...response.orders);
  cursor = response.nextCursor;
} while (response.hasNextPage);
```

### Size Object
The `size` property is an object containing:
- **amount** (string) - The total order size
- **filled** (string) - The amount that has been filled
- **asset** (string) - Which asset the size refers to ("target" or "contra")

### References
  * [Order Statuses](link-to-order-statuses)
```

--------------------------------

### GET /v2/portfolio/orders/{orderId}

Source: https://ddp.definitive.fi/api/orders/details

Retrieves detailed information about a specific order using its UUID. This is the primary endpoint for portfolio-level order details.

```APIDOC
## GET /v2/portfolio/orders/{orderId}

### Description
Retrieves detailed information about a specific order, including execution details, fill events, and current status.

### Method
GET

### Endpoint
`https://ddp.definitive.fi/v2/portfolio/orders/{orderId}`

Note: For Organization API, replace `/v2/portfolio/` with `/v2/organization/portfolios/{portfolioId}/`.

### Parameters
#### Path Parameters
- **orderId** (string) - Required - UUID of the order

### Request Example
```javascript
const json = await AuthHelpers.signAndSend({
  path: "/v2/portfolio/orders/00000000-0000-0000-0000-000000000001",
  method: "GET",
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET,
});
console.log(json);
```

### Response
#### Success Response (200)
- **order** (object) - Contains the main order details.
  - **orderId** (string) - The unique identifier for the order.
  - **type** (string) - The type of the order (e.g., ORDER_TYPE_LIMIT, ORDER_TYPE_TWAP).
  - **status** (string) - The current status of the order (e.g., ORDER_STATUS_PARTIALLY_FILLED, ORDER_STATUS_FILLED).
  - **orderSide** (string) - The side of the order (e.g., ORDER_SIDE_BUY).
  - **targetAsset** (object) - Details of the target asset.
  - **contraAsset** (object) - Details of the contra asset.
  - **filled** (object) - Summary of filled amounts and prices.
  - **size** (object) - Object detailing the total and filled amounts.
    - **amount** (string) - The total order size.
    - **filled** (string) - The amount that has been filled.
    - **asset** (string) - Which asset the size refers to ("target" or "contra").
  - **maxPriceImpact** (string) - Maximum price impact allowed for the order.
  - **limit** (object) - Limit price details.
  - **trigger** (object) - Trigger price details.
  - **twap** (object, optional) - TWAP-specific fields if applicable.
    - **buckets** (number) - Number of execution buckets for the TWAP order.
    - **durationSeconds** (number) - Duration of the TWAP order in seconds.
  - **placedAt** (string) - Timestamp when the order was placed.
  - **acceptedAt** (string) - Timestamp when the order was accepted.
  - **closedAt** (string or null) - Timestamp when the order was closed.
  - **closeReason** (string or null) - Reason for closing the order.
  - **organizationName** (string) - Name of the organization.
  - **portfolioId** (string) - ID of the portfolio.
  - **vaultId** (string) - ID of the vault.
- **fills** (array) - An array of fill events for the order.
  - **status** (string) - Status of the fill event.
  - **notional** (string) - Notional value of the fill.
  - **venues** (array) - List of venues where the fill occurred.
  - **filledAt** (string) - Timestamp when the fill occurred.
  - **rootOrderId** (string) - Root order ID associated with the fill.
  - **orderId** (string) - Order ID for this specific fill.
  - **parentOrderId** (string) - Parent order ID.
  - **transactionId** (string) - Transaction ID on the blockchain.
  - **fillPrice** (string) - The price at which the fill occurred.
  - **feeAmount** (string) - Total fee amount for the fill.
  - **feeTicker** (string) - Ticker symbol for the fee asset.
  - **tradeFeeAmount** (string) - Fee amount related to the trade.
  - **networkFeeAmount** (string) - Fee amount for the network transaction.
  - **feeNotional** (string) - Notional value of the total fee.
  - **tradeFeeNotional** (string) - Notional value of the trade fee.
  - **networkFeeNotional** (string) - Notional value of the network fee.
  - **contraAmount** (string) - Amount filled in the contra asset.
  - **targetAmount** (string) - Amount filled in the target asset.

#### Response Example
```json
{
  "order": {
    "orderId": "00000000-0000-0000-0000-000000000005",
    "type": "ORDER_TYPE_LIMIT",
    "status": "ORDER_STATUS_PARTIALLY_FILLED",
    "orderSide": "ORDER_SIDE_BUY",
    "targetAsset": {
      "id": "00000000-0000-0000-0000-000000000010",
      "name": "USD Coin",
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "ticker": "USDC",
      "chain": { "name": "Ethereum", "id": "1", "namespace": "eip155" }
    },
    "contraAsset": {
      "id": "00000000-0000-0000-0000-000000000011",
      "name": "Wrapped Ether",
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "ticker": "WETH",
      "chain": { "name": "Ethereum", "id": "1", "namespace": "eip155" }
    },
    "filled": {
      "targetAssetAmount": "899625.000000",
      "contraAssetAmount": "500.000000",
      "averagePrice": "1799.25",
      "averageNotionalPrice": "1799.50"
    },
    "size": {
      "amount": "1000.000000",
      "filled": "750.000000",
      "asset": "contra"
    },
    "maxPriceImpact": "0.01",
    "limit": { "isNotional": false, "price": "1800.00" },
    "trigger": { "isNotional": false, "price": "" },
    "placedAt": "2024-08-05T20:48:11.584Z",
    "acceptedAt": "2024-08-05T20:48:12.584Z",
    "closedAt": null,
    "closeReason": null,
    "organizationName": "Example Organization",
    "portfolioId": "00000000-0000-0000-0000-000000000004",
    "vaultId": "00000000-0000-0000-0000-000000000003"
  },
  "fills": [
    {
      "status": "CHAIN_STATUS_FINALIZED",
      "notional": "1799625.000000",
      "venues": ["Uniswap V3"],
      "filledAt": "2024-08-05T20:48:30.584Z",
      "rootOrderId": "00000000-0000-0000-0000-000000000005",
      "orderId": "00000000-0000-0000-0000-000000000006",
      "parentOrderId": "00000000-0000-0000-0000-000000000005",
      "transactionId": "0x1234567890abcdef...",
      "fillPrice": "1799.25",
      "feeAmount": "0.5",
      "feeTicker": "WETH",
      "tradeFeeAmount": "0.45",
      "networkFeeAmount": "0.05",
      "feeNotional": "900.00",
      "tradeFeeNotional": "810.00",
      "networkFeeNotional": "90.00",
      "contraAmount": "500.000000",
      "targetAmount": "899625.000000"
    }
  ]
}
```
```

--------------------------------

### Create User Portfolio

Source: https://ddp.definitive.fi/overview

Create a new portfolio for a user by making a POST request to the create-portfolio endpoint. The portfolio name is typically set to the user ID.

```javascript
// Create a new portfolio for the user
const portfolio = await AuthHelpers.signAndSend({
  path: "/v2/organization/create-portfolio",
  method: "POST",
  body: {
    portfolioName: `${userId}`,
  },
  apiKey,
  apiSecret,
});

const portfolioId = portfolio.portfolioId;
```