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.

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

API Base Information

Base URL

https://open-api.openocean.finance

Supported Chains

Ethereum mainnet: 0xcC8d695603ce0b43D352891892FcC716c6a7C9f4

BSC mainnet: 0xA8A0213bb2ce671E457Ec14D08EB9d40E6DA8e2d

Polygon mainnet: 0xFA9B584Bc9543B66BeFdc41fb1DA8636edD7a697

Avalanche C-chain mainnet: 0x99b3488Ee3432bB60256140b4BD2488E3b6A705f

Fantom mainnet: 0x44A632dC8ee03ad2cF5d530280a044DaED3E1ec0

Arbitrum mainnet: 0x23C78B3d85b45BfA6DC8e09b517ba2d9b0ECCA8C

Optimism mainnet: 0xc0A62DDCd284020dC883C642A3Ed5D2A1770eb91

Base mainnet: 0xb5486f71C902fe0844Bb07221Fa8f47834d90B1b

Soinc mainnet: 0xb45373129b4220160b92bd2320869f44d48ecd01

Bear mainnet: 0x8D2B7e5501Eb6D92F8e349f2FEbe785DD070bE74

Sei mainnet: 0xfE9a934A8607EF020aDf22D4431d6cE6005Aa4d3

HyperEVM mainnet: 0x4E6b18217AC75A779262c20B3Cc07050cBe7282B

Linea mainnet: 0x4045734fe21c7B7E0cE516BE009780Cc2BA39A8f

Moonriver mainnet: 0xc0A62DDCd284020dC883C642A3Ed5D2A1770eb91

Gnosis mainnet: 0xc0A62DDCd284020dC883C642A3Ed5D2A1770eb91

Harmony mainnet: 0xc0A62DDCd284020dC883C642A3Ed5D2A1770eb91

Cronos mainnet: 0xc0A62DDCd284020dC883C642A3Ed5D2A1770eb91

Zksync mainnet: 0x6a9115a77598cb9897347a6c31E6a164Ea06F870

Token Configuration

Token Approval

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

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:

{
  "makerAsset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "takerAsset": "0xfde4c96c8593536e31f229ea8f37b2ada2699bb2",
  "makerAmount": "1000000",
  "takerAmount": "2000000",
  "expireTime": 1704067200000,
  "signature": "0x...",
  "orderMaker": "0x..."
}

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:

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

2. Cancel Limit Order

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

Request Body:

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

Field Descriptions:

  • orderHash: Hash of the order to cancel

  • signature: signMessage

Response:

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

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:

/v2/8453/limit-order/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": "1000000",
      "takerAmount": "2000000",
      "createDateTime": "2024-01-01T00:00:00Z",
      "statuses": 2,
      "expireTime": 1704067200000
    }
  ]
}

Request/Response Formats

Order Status Codes

Code
Status
Description

1

Pending

Order is pending execution

2

Active

Order is active and can be filled

3

Filled

Order has been completely filled

4

Cancelled

Order has been cancelled

5

Expired

Order has expired

Message Signing Format

For Order Creation:

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

For Order Cancellation:

orderHash:
{orderHash}

Signature Generation

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

Integration Examples

Complete Order Creation Flow

async function createLimitOrder(makerAmount, takerAmount, expireTime) {
  try {
    // 1. Validate inputs
    if (!makerAmount || !takerAmount || makerAmount <= 0 || takerAmount <= 0) {
      throw new Error('Invalid parameters');
    }

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

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

    // 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 order parameters
    const messageParams = {
      makerAsset: inToken.address,
      takerAsset: outToken.address,
      makerAmount: (makerAmount * (10 ** inToken.decimals)).toString(),
      takerAmount: (takerAmount * (10 ** outToken.decimals)).toString(),
      expireTime: expireTime,
    };

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

    // 7. Submit order
    const order = {
      ...messageParams,
      signature,
      orderMaker: walletAccount,
    };

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

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

Order Management

// Get user orders
const orders = await getLimitOrders(walletAddress);
const { orderHash } = orders[0];
const message = 'orderHash:\n' + orderHash;
const signer = await state.provider.getSigner();
const signature = await signer.signMessage(message);

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

Support

For technical support or questions about the API:

PreviousLimit Order APINextAPI

Last updated