# 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. {% embed url="" %} ### 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: ```javascript // 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:** ```json { "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:** ```json { "success": true, "data": { "orderHash": "0x...", "status": "pending" } } ``` #### 2. Cancel DCA Strategy **Endpoint:** `POST /v2/{chainId}/dca/cancel` **Request Body:** ```json { "orderHash": "0x...", "signature": "0x..." } ``` **Field Descriptions:** * `orderHash`: Hash of the DCA strategy to cancel * `signature`: signMessage **Response:** ```json { "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:** ```json { "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 ```javascript const message = `makerAsset:\n${makerAsset}\ntakerAsset:\n${takerAsset}\nmakerAmount:\n${makerAmount}`; const signature = await signer.signMessage(message); ``` ### Integration Examples #### Complete DCA Strategy Creation Flow ```javascript 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 ```javascript 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](https://docs.openocean.finance) * Contact the development team * Review error logs and API responses --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://apis.openocean.finance/developer/apis/dca-api/guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.