OpenOcean
GitHub

Guide

Limit Order API Integration Documentation

Overview

This document provides comprehensive integration guidelines for the OpenOcean Limit Order API, based on the implementation in LimitOrder.js. The API allows users to create, manage, and cancel limit orders for token trading on supported blockchain networks.

LimitOrder.js(GitHub)

API Base Information

Base URL

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

View the current supported chains here.

Token Configuration

Token Approval

Before creating a limit order, 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 tx = await tokenContract.approve(contractAddress, ethers.MaxUint256);
7
  await tx.wait();
8
}

API Endpoints

1. Create Limit Order

Endpoint: POST /v2/{chainId}/limit-order

URL Parameters:

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

Request Body:

Terminal
{}
1
{
2
  "makerAsset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
3
  "takerAsset": "0xfde4c96c8593536e31f229ea8f37b2ada2699bb2",
4
  "makerAmount": "1000000",
5
  "takerAmount": "2000000",
6
  "expireTime": 1704067200000,
7
  "signature": "0x...",
8
  "orderMaker": "0x..."
9
}

Field Descriptions:

  • makerAsset: Address of the token being sold
  • takerAsset: Address of the token being bought
  • makerAmount: Amount of maker token (in smallest units)
  • takerAmount: Amount of taker token (in smallest units)
  • expireTime: Order expiration timestamp (milliseconds)
  • signature: signMessage
  • orderMaker: User's wallet address

Response:

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

2. Cancel Limit Order

Endpoint: POST /v2/{chainId}/limit-order/cancelLimitOrder

Request Body:

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

Field Descriptions:

  • orderHash: Hash of the order to cancel
  • signature: signMessage

Response:

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

3. Get User Orders

Endpoint: GET /v2/{chainId}/limit-order/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/limit-order/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": "1000000",
10
      "takerAmount": "2000000",
11
      "createDateTime": "2024-01-01T00:00:00Z",
12
      "statuses": 2,
13
      "expireTime": 1704067200000
14
    }
15
  ]
16
}

Request/Response Formats

Order Status Codes

CodeStatusDescription
1PendingOrder is pending execution
2ActiveOrder is active and can be filled
3FilledOrder has been completely filled
4CancelledOrder has been cancelled
5ExpiredOrder has expired

Message Signing Format

For Order Creation:

Terminal
TXT
1
makerAsset:
2
{makerAsset}
3
takerAsset:
4
{takerAsset}
5
makerAmount:
6
{makerAmount}
7
takerAmount:
8
{takerAmount}
9
expireTime:
10
{expireTime}

For Order Cancellation:

Terminal
TXT
1
orderHash:
2
{orderHash}

Signature Generation

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

Integration Examples

Complete Order Creation Flow

Terminal
JS
1
async function createLimitOrder(makerAmount, takerAmount, expireTime) {
2
  try {
3
    // 1. Validate inputs
4
    if (!makerAmount || !takerAmount || makerAmount <= 0 || takerAmount <= 0) {
5
      throw new Error('Invalid parameters');
6
    }
7


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


13
    // 3. Get contract address
14
    const contractAddress = getLimitContractAddress(chainName);
15


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


22
    // 5. Prepare order parameters
23
    const messageParams = {
24
      makerAsset: inToken.address,
25
      takerAsset: outToken.address,
26
      makerAmount: (makerAmount * (10 ** inToken.decimals)).toString(),
27
      takerAmount: (takerAmount * (10 ** outToken.decimals)).toString(),
28
      expireTime: expireTime,
29
    };
30


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


36
    // 7. Submit order
37
    const order = {
38
      ...messageParams,
39
      signature,
40
      orderMaker: walletAccount,
41
    };
42


43
    const response = await axios.post(
44
      'https://open-api.openocean.finance/v2/8453/limit-order',
45
      order,
46
      { headers: { 'Content-Type': 'application/json' } }
47
    );
48


49
    return response.data;
50
  } catch (error) {
51
    console.error('Error creating limit order:', error);
52
    throw error;
53
  }
54
}

Order Management

Terminal
JS
1
// Get user orders
2
const orders = await getLimitOrders(walletAddress);
3
const { orderHash } = orders[0];
4
const message = 'orderHash:\n' + orderHash;
5
const signer = await state.provider.getSigner();
6
const signature = await signer.signMessage(message);
7


8
await axios.post(
9
  'https://open-api.openocean.finance/v2/8453/limit-order/cancelLimitOrder',
10
  { orderHash, signature }
11
);

Support

For technical support or questions about the API: