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: EIP-712 signature of the DCA strategy
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: EIP-712 signature of the cancellation

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

Pending

DCA strategy is pending execution

Active

DCA strategy is active and executing trades

Filled

DCA strategy has completed all trades

Cancelled

DCA strategy has been cancelled

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

PreviousDCA API NextAPI

Last updated 6 days ago