OpenOcean
GitHub
Back to DCA API

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.

Dca.js (GitHub)

API Base Information

Base URL

Terminal
TXT
1
https://open-api.openocean.finance

Supported Networks

The DCA API supports the following blockchain networks:

Terminal
JS
1
// Some code
2
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:

Terminal
JS
1
// Check current allowance
2
const currentAllowance = await tokenContract.allowance(account, contractAddress);
3


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

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:

Terminal
{}
1
{
2
  "makerAsset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
3
  "takerAsset": "0xfde4c96c8593536e31f229ea8f37b2ada2699bb2",
4
  "makerAmount": "20000000",
5
  "signature": "0x...",
6
  "orderMaker": "0x...",
7
  "minPrice": 0,
8
  "maxPrice": 0,
9
  "time": 3600,
10
  "times": 2
11
}

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:

Terminal
{}
1
{
2
  "success": true,
3
  "data": {
4
    "orderHash": "0x...",
5
    "status": "pending"
6
  }
7
}

2. Cancel DCA Strategy

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

Request Body:

Terminal
{}
1
{
2
  "orderHash": "0x...",
3
  "signature": "0x..."
4
}

Field Descriptions:

  • orderHash: Hash of the DCA strategy to cancel
  • signature: signMessage

Response:

Terminal
{}
1
{
2
  "code": 200,
3
  "success": true,
4
  "data": {
5
    "status": "cancelled"
6
  }
7
}

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:

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

Response:

Terminal
{}
1
{
2
  "success": true,
3
  "data": [
4
    {
5
      "id": "123",
6
      "orderHash": "0x...",
7
      "makerAsset": "0x...",
8
      "takerAsset": "0x...",
9
      "makerAmount": "20000000",
10
      "createDateTime": "2024-01-01T00:00:00Z",
11
      "statuses": 2,
12
      "time": 3600,
13
      "times": 2,
14
      "minPrice": 0,
15
      "maxPrice": 0
16
    }
17
  ]
18
}

Request/Response Formats

Order Status Codes

CodeStatusDescription
1PendingDCA strategy is pending execution
2ActiveDCA strategy is active and executing trades
3FilledDCA strategy has completed all trades
4CancelledDCA strategy has been cancelled
5ExpiredDCA strategy has expired

Message Signing Format

For DCA Strategy Creation:

Terminal
TXT
1
makerAsset:
2
{makerAssetAddress}
3
takerAsset:
4
{takerAssetAddress}
5
makerAmount:
6
{makerAmount}

For DCA Strategy Cancellation:

Terminal
TXT
1
orderHash:
2
{orderHash}

Signature Generation

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

Integration Examples

Complete DCA Strategy Creation Flow

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


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


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


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


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


26
    // 5. Prepare DCA parameters
27
    const messageParams = {
28
      makerAsset: inToken.address,
29
      takerAsset: outToken.address,
30
      makerAmount: (makerAmount * (10 ** inToken.decimals)).toString(),
31
    };
32


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


38
    // 7. Submit DCA strategy
39
    const order = {
40
      ...messageParams,
41
      signature,
42
      orderMaker: walletAccount,
43
      minPrice: minPrice || 0,
44
      maxPrice: maxPrice || 0,
45
      time: everyUnit * time,
46
      times: frequency,
47
    };
48


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


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


59
    return response.data;
60
  } catch (error) {
61
    console.error('Error creating DCA strategy:', error);
62
    throw error;
63
  }
64
}

DCA Strategy Management

Terminal
JS
1
const { orderHash } = order;
2


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


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

Support

For technical support or questions about the API:

Next Steps

DCA API

Back to DCA API overview.

Swagger UI

Try API endpoints interactively.