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.
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 soldtakerAsset
: Address of the token being boughtmakerAmount
: Amount of maker token (in smallest units)takerAmount
: Amount of taker token (in smallest units)expireTime
: Order expiration timestamp (milliseconds)signature
: EIP-712 signature of the orderorderMaker
: 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 cancelsignature
: EIP-712 signature of the cancellation
Response:
{
"success": true,
"data": {
"status": "cancelled"
}
}
3. Get User Orders
Endpoint: GET /v2/{chainId}/limit-order/address/{address}
URL Parameters:
chainId
: The blockchain network IDaddress
: 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
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:
Check the OpenOcean Documentation
Contact the development team
Review error logs and API responses
Last updated