Creating a Limit Order: API Reference Guide

Overview

A limit order is an essential trading tool that allows users to buy or sell assets at predetermined prices on decentralized exchanges (DEX). This guide provides a detailed walkthrough of the API endpoint for creating limit orders.

API Endpoint

POST https://web3.okx.com/api/v5/dex/aggregator/limit-order/save-order

Request Parameters

Parameter	Type	Required	Description
`orderHash`	String	Yes	Unique identifier for the order
`signature`	String	Yes	Cryptographic signature for verification
`chainId`	String	Yes	Blockchain network ID (e.g., `1` for Ethereum)
Data Object	Object	Yes	Order details
`salt`	String	Yes	Random nonce for idempotency (timestamp in seconds)
`makingAmount`	String	Yes	Amount of token sold (with decimals, e.g., `1000000` for 1.00 USDT)
`takingAmount`	String	Yes	Amount of token bought (with decimals)
`makerToken`	String	Yes	Contract address of the sold token
`takerToken`	String	Yes	Contract address of the bought token
`maker`	String	Yes	Wallet address creating the order
`deadLine`	String	Yes	Order expiration timestamp (seconds)
`allowedSender`	String	Yes	Address permitted to execute the order (`0x00...` for open execution)
`receiver`	String	Yes	Destination address for assets
`minReturn`	String	Yes	Minimum acceptable return amount
`partiallyAble`	Bool	Yes	Whether partial order fulfillment is allowed

Response Parameters

Parameter	Type	Description
`code`	String	Status code (e.g., `0` for success)
`msg`	String	Server response message

Usage Scenarios

Token Swaps: Execute precise trades at specified rates.
Partial Fills: Enable partial order fulfillment for liquidity efficiency.
Expiry Control: Set deadlines to manage order validity periods.

👉 Learn advanced DEX strategies here

FAQs

What is a limit order?

A limit order specifies the maximum/minimum price at which you're willing to buy/sell an asset.

How do decimals work in amounts?

Token amounts must include decimal precision (e.g., 1000000 = 1.00 USDT).

Can I restrict order execution?

Yes, via allowedSender—set to 0x00... for open access or a specific address for restricted execution.

👉 Explore API integrations

Best Practices

Always validate chainId against supported networks.
Use recent timestamps for salt to prevent replay attacks.
Monitor minReturn to ensure favorable trade execution.

This guide adheres to Web3 security standards while optimizing for DEX trading efficiency.