Guide

DCA (Dollar Cost Averaging) API Integration Documentation

Overview

This document provides comprehensive integration guidelines for the OpenOcean DCA (Dollar Cost Averaging) API, based on the implementation in Dca.js. The API allows users to create and manage automated recurring buy strategies for token accumulation on supported blockchain networks.

OpenOcean-API-Examples/frontend/src/pages/Dca.js at main · openocean-finance/OpenOcean-API-ExamplesGitHub

API Base Information

Base URL

https://open-api.openocean.finance

Supported Networks

The DCA API supports the following blockchain networks:

// Some code
const dcaChains = ["eth", "bsc", "base", "sonic", "bera", "arbitrum", "hyperevm", "avax"];

Authentication & Wallet Integration

Prerequisites

• MetaMask or compatible Web3 wallet

• User must be connected to a supported network

• User must have sufficient token balance and gas fees

• Total allocation must be less than $5

Token Configuration

Token Approval

Before creating a DCA strategy, users must approve the contract to spend their tokens:

// Check current allowance
const currentAllowance = await tokenContract.allowance(account, contractAddress);

// Approve if needed
if (currentAllowance < requiredAmount) {
  const maxAmount = ethers.MaxUint256;
  const tx = await tokenContract.approve(contractAddress, maxAmount);
  await tx.wait();
}

API Endpoints

1. Create DCA Strategy

Endpoint: POST /v2/{chainId}/dca/swap

URL Parameters:

• chainId: The blockchain network ID (e.g., 8453 for Base)

Request Body:

{
  "makerAsset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "takerAsset": "0xfde4c96c8593536e31f229ea8f37b2ada2699bb2",
  "makerAmount": "20000000",
  "signature": "0x...",
  "orderMaker": "0x...",
  "minPrice": 0,
  "maxPrice": 0,
  "time": 3600,
  "times": 2
}

Field Descriptions:

• makerAsset: Address of the token being sold (e.g., USDC)

• takerAsset: Address of the token being bought (e.g., USDT)

• makerAmount: Total allocation amount in smallest units

• signature: signMessage

• orderMaker: User's wallet address

• minPrice: Minimum price limit in USD (optional, 0 for no limit)

• maxPrice: Maximum price limit in USD (optional, 0 for no limit)

• time: Time interval between trades in seconds

• times: Number of trades to execute

Response:

{
  "success": true,
  "data": {
    "orderHash": "0x...",
    "status": "pending"
  }
}

2. Cancel DCA Strategy

Endpoint: POST /v2/{chainId}/dca/cancel

Request Body:

{
  "orderHash": "0x...",
  "signature": "0x..."
}

Field Descriptions:

• orderHash: Hash of the DCA strategy to cancel

• signature: signMessage

Response:

{
  "code": 200,
  "success": true,
  "data": {
    "status": "cancelled"
  }
}

3. Get User DCA Orders

Endpoint: GET /v2/{chainId}/dca/address/{address}

URL Parameters:

• chainId: The blockchain network ID

• address: User's wallet address

Query Parameters:

• page: Page number (default: 1)

• limit: Number of orders per page (default: 100)

• statuses: Array of order statuses to filter [1,2,5]

• sortBy: Sort field (default: createDateTime)

• exclude: Exclude certain orders (default: 0)

Example URL:

/v2/8453/dca/address/0x1234...?page=1&limit=100&statuses=[1,2,5]&sortBy=createDateTime&exclude=0

Response:

{
  "success": true,
  "data": [
    {
      "id": "123",
      "orderHash": "0x...",
      "makerAsset": "0x...",
      "takerAsset": "0x...",
      "makerAmount": "20000000",
      "createDateTime": "2024-01-01T00:00:00Z",
      "statuses": 2,
      "time": 3600,
      "times": 2,
      "minPrice": 0,
      "maxPrice": 0
    }
  ]
}

Request/Response Formats

Order Status Codes

Code	Status	Description
1	Pending	DCA strategy is pending execution
2	Active	DCA strategy is active and executing trades
3	Filled	DCA strategy has completed all trades
4	Cancelled	DCA strategy has been cancelled
5	Expired	DCA strategy has expired

Message Signing Format

For DCA Strategy Creation:

makerAsset:
{makerAssetAddress}
takerAsset:
{takerAssetAddress}
makerAmount:
{makerAmount}

For DCA Strategy Cancellation:

orderHash:
{orderHash}

Signature Generation

const message = `makerAsset:\n${makerAsset}\ntakerAsset:\n${takerAsset}\nmakerAmount:\n${makerAmount}`;
const signature = await signer.signMessage(message);

Integration Examples

Complete DCA Strategy Creation Flow

async function createDcaStrategy(makerAmount, time, frequency, minPrice, maxPrice) {
  try {
    // 1. Validate inputs
    if (!makerAmount || makerAmount <= 0) {
      throw new Error('Invalid amount');
    }

    if (makerAmount >= 5) {
      throw new Error('Amount must be less than $5');
    }

    // 2. Check wallet connection
    if (!isWalletConnected) {
      throw new Error('Wallet not connected');
    }

    // 3. Get contract address
    const contractAddress = '0x6cBB2598881940D08d5Ea3fA8F557E02996e1031';

    // 4. Check and approve token if needed
    if (!isNativeToken(inToken.address)) {
      const approvalAmount = makerAmount * (10 ** inToken.decimals);
      await checkTokenApproval(inToken.address, contractAddress, approvalAmount, walletAccount, provider);
    }

    // 5. Prepare DCA parameters
    const messageParams = {
      makerAsset: inToken.address,
      takerAsset: outToken.address,
      makerAmount: (makerAmount * (10 ** inToken.decimals)).toString(),
    };

    // 6. Create and sign message
    const message = `makerAsset:\n${messageParams.makerAsset}\ntakerAsset:\n${messageParams.takerAsset}\nmakerAmount:\n${messageParams.makerAmount}`;
    const signer = await provider.getSigner();
    const signature = await signer.signMessage(message);

    // 7. Submit DCA strategy
    const order = {
      ...messageParams,
      signature,
      orderMaker: walletAccount,
      minPrice: minPrice || 0,
      maxPrice: maxPrice || 0,
      time: everyUnit * time,
      times: frequency,
    };

    const response = await axios.post(
      `https://open-api.openocean.finance/v2/${chainId}/dca/swap`,
      order,
      { headers: { 'Content-Type': 'application/json' } }
    );

    if (response.data.code === 400) {
      throw new Error(response.data.error);
    }

    return response.data;
  } catch (error) {
    console.error('Error creating DCA strategy:', error);
    throw error;
  }
}

DCA Strategy Management

const { orderHash } = order;

 // Create message for signing
 const message = 'orderHash:\n' + orderHash;
 const signer = await provider.getSigner();
 const signature = await signer.signMessage(message);

// Cancel order through API
const { data } = await axios.post(
     `https://open-api.openocean.finance/v2/${chain.chainId}/dca/cancel`,
     {
      orderHash,
      signature
     }
   );

Support

For technical support or questions about the API:

• Check the OpenOcean Documentation

• Contact the development team

• Review error logs and API responses