Guide to Liquidate All Positions to USDC

This guide explains how to "sweep" your portfolio by liquidating all positions to USDC. It is broken down into several steps, using the provided code as a basis.

1. Get API Key

Before running any trades, set your API credentials as environment variables. The code uses the dotenv package to load these credentials:

require('dotenv').config();
 
const apiKey = process.env.API_KEY;
const apiSecret = process.env.API_SECRET;
 
if (!apiKey || !apiSecret) {
  console.error("Please set the API_KEY and API_SECRET environment variables.");
  process.exit(1);
}

If you do not have an API key, visit the Getting Started page for instructions.

2. Prehashing and Signing

The security of your API requests depends on correctly preparing and signing your messages. Two helper functions are used: preparePrehash() and signMessage(). These functions filter and sort headers, create a prehash string, and then sign it using your API secret.

const crypto = require('crypto');
 
function preparePrehash({ method, path, timestamp, headers, queryParams, body }) {
  // Filter headers that start with "x-definitive-"
  const filteredHeaders = Object.entries(headers)
    .filter(([key]) => key.toLowerCase().startsWith("x-definitive-"));
  
  // Ensure headers are sorted alphabetically
  const sortedHeaders = filteredHeaders
    .sort(([keyA], [keyB]) => keyA.localeCompare(keyB))
    .map(([key, value]) => `${key}:${JSON.stringify(value)}`)
    .join(",");
  
  // Stringify query parameters (if any)
  const queryParamsString = new URLSearchParams(queryParams).toString();
  
  // Use an empty string if no body is provided
  const bodyString = body || "";
  
  return `${method}:${path}?${queryParamsString}:${timestamp}:${sortedHeaders}${bodyString}`;
}
 
// Remove the "dpks_" prefix from your API secret for signing
const signingSecret = apiSecret.replace("dpks_", "");

function signMessage(message) {
  return crypto.createHmac("sha256", signingSecret)
    .update(message)
    .digest("hex");
}

If you have more question, visit the Swaps page for more details on preshashing and signing.

3. Get Positions

Retrieve your current positions using the getPositions() function. This function makes a GET request to the /v1/positions endpoint and returns the list of positions.

async function getPositions() {
  const method = "GET";
  const path = "/v1/positions";
  const queryParams = {};
  const timestamp = Date.now().toString();
 
  const headers = {
    "x-definitive-api-key": apiKey,
    "x-definitive-timestamp": timestamp,
  };
 
  const message = preparePrehash({ method, path, timestamp, headers, queryParams });
  const signature = crypto.createHmac("sha256", signingSecret)
    .update(message)
    .digest("hex");
 
  try {
    const response = await fetch(`https://ddp.definitive.fi${path}`, {
      method,
      headers: {
        ...headers,
        "x-definitive-signature": signature,
      },
    });
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status} - ${response.statusText}`);
    }
    const json = await response.json();
    console.log("User Positions:", json);
    // Return only the positions array.
    return json.positions;
  } catch (error) {
    console.error("Error fetching positions:", error);
    throw error;
  }
}

4. Go Through All Positions to Generate Quote for Position

For each position, generate a trade quote to convert the asset to USDC. The function generateQuoteForPosition() creates a quote by sending a POST request to the /v1/trade/quote endpoint:

async function generateQuoteForPosition(position, targetUSDCAddress, chain) {
  const method = "POST";
  const path = "/v1/trade/quote";
  const timestamp = Date.now().toString();
 
  const headers = {
    "x-definitive-api-key": apiKey,
    "x-definitive-timestamp": timestamp,
    "Content-Type": "application/json"
  };
 
  // Use a placeholder for native ETH if needed.
  const nativeETHPlaceholder = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
  let fromAddress = position.asset.address;
  if (
    (position.asset.ticker && 
     (position.asset.ticker.toUpperCase() === "ETH")) ||
    fromAddress.length !== 42
  ) {
    fromAddress = nativeETHPlaceholder;
  }
 
  const quoteRequest = {
    type: "market",
    chain: chain,                 // e.g., "ethereum", "polygon", etc.
    from: fromAddress,
    to: targetUSDCAddress,        // USDC address on that chain
    qty: position.balance.toString(),
    orderSide: "sell",
    slippageTolerance: "0.01",
    maxPriceImpact: "0.05"
  };
 
  const bodyString = JSON.stringify(quoteRequest);
  const prehashMessage = preparePrehash({
    method,
    path,
    timestamp,
    headers,
    queryParams: {},
    body: bodyString
  });
 
  const newSignature = signMessage(prehashMessage);
 
  try {
    const response = await fetch(`https://ddp.definitive.fi${path}`, {
      method,
      headers: {
        ...headers,
        "x-definitive-signature": newSignature
      },
      body: bodyString
    });
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status} - ${response.statusText}`);
    }
    const json = await response.json();
    console.log("Quote for position:", json);
    return json;
  } catch (error) {
    console.error("Error generating quote for position:", error);
    throw error;
  }
}

5. Submit the Trade

After obtaining a valid quote, use the submitTrade() function to execute the swap. This function merges the quote and metadata before sending a POST request to the /v1/trade endpoint.

async function submitTrade(tradePayload) {
  const method = "POST";
  const path = "/v1/trade";
  const timestamp = Date.now().toString();
 
  const headers = {
    "x-definitive-api-key": apiKey,
    "x-definitive-timestamp": timestamp,
    "Content-Type": "application/json",
  };
 
  const bodyString = JSON.stringify(tradePayload);
 
  // Prepare prehash using the same endpoint path
  const prehashMessage = preparePrehash({
    method,
    path,
    timestamp,
    headers,
    queryParams: {},
    body: bodyString,
  });
 
  const signature = signMessage(prehashMessage);
 
  try {
    const response = await fetch(`https://ddp.definitive.fi${path}`, {
      method,
      headers: {
        ...headers,
        "x-definitive-signature": signature,
      },
      body: bodyString,
    });
 
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status} - ${response.statusText}`);
    }
 
    const data = await response.json();
    console.log("Trade submission response:", data);
    return data;
  } catch (error) {
    console.error("Error submitting trade:", error);
    throw error;
  }
}

6. Liquidating Positions Across Chains

If this is confusing, don't worry! This function ties all the previous steps together. It:

Retrieves all positions.
Iterates through each position.
Generates a quote for converting each asset to USDC (if not already in USDC).
Submits the trade.

async function liquidatePositionsAcrossChains() {
  try {
    // Fetch the positions
    const positions = await getPositions();
    if (!positions || positions.length === 0) {
      console.log("No positions found.");
      return;
    }
    
    // Define USDC addresses per chain.
    const usdcAddresses = {
      ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      polygon: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
      base: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      arbitrum: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      avalanche: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
      blast: "0x4300000000000000000000000000000000000003",
      optimism: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
      solana: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      // Add other chains as needed...
    };
  
    for (const position of positions) {
      // Extract chain name from position.asset.chain.name (default to ethereum)
      const chainName = (position.asset.chain && position.asset.chain.name)
        ? position.asset.chain.name.toLowerCase()
        : "ethereum";
      
      const targetUSDC = usdcAddresses[chainName];
      if (!targetUSDC) {
        console.log(`No USDC address for chain: ${chainName}. Skipping asset: ${position.asset.address}`);
        continue;
      }
      
      // Skip if the position is already in USDC.
      if (position.asset.address.toLowerCase() === targetUSDC.toLowerCase()) {
        console.log(`Skipping USDC position on ${chainName}: ${position.asset.address}`);
        continue;
      }
      
      console.log(`Liquidating position for asset ${position.asset.address} on ${chainName}`);
  
      // Generate a trade quote for this position.
      const quoteResponse = await generateQuoteForPosition(position, targetUSDC, chainName);
      if (!quoteResponse || !quoteResponse.quote) {
        console.error("Invalid quote response for asset:", position.asset.address);
        continue;
      }
      
      // Merge the quote and metadata objects.
      const tradePayload = { 
        ...quoteResponse.quote,
        ...quoteResponse.metadata
      };
      console.log("Trade payload for asset", position.asset.address, ":", tradePayload);
      
      // Submit the trade.
      const orderResponse = await submitTrade(tradePayload);
      console.log("Order response for asset", position.asset.address, ":", orderResponse);
    }
  } catch (error) {
    console.error("Error liquidating positions across chains:", error);
  }
}

At the end of the file, the function is called to start the liquidation process:

liquidatePositionsAcrossChains();

Summary

Get API Key: Set your API credentials via environment variables.
Prepare Prehash and Sign: Use preparePrehash() and signMessage() to create secure, signed requests.
Get Positions: Retrieve your current asset positions using the getPositions() function.
Generate Quote for Each Position: For each asset (excluding USDC), generate a sell order quote with generateQuoteForPosition().
Submit the Trade: Merge the quote and metadata, then execute the trade with submitTrade().
Liquidate All Positions: The liquidatePositionsAcrossChains() function ties everything together, iterating over positions and executing trades to convert all assets to USDC.

This guide provides a complete walkthrough of the sweeping process using the provided code. Follow the steps and review the code samples to understand how everything works together.