# 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.

{% embed url="<https://github.com/openocean-finance/OpenOcean-API-Examples/blob/main/frontend/src/pages/LimitOrder.js>" %}

### API Base Information

#### Base URL

```
https://open-api.openocean.finance
```

#### View the current supported chains [here](https://apis.openocean.finance/developer/apis/supported-chains#limit-order-api-supported-chains).

### Token Configuration

#### Token Approval

Before creating a limit order, 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 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:**

```json
{
  "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:**

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

#### 2. Cancel Limit Order

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

**Request Body:**

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

**Field Descriptions:**

* `orderHash`: Hash of the order to cancel
* `signature`: signMessage

**Response:**

```json
{
  "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:**

```json
{
  "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

```javascript
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

```javascript
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

```javascript
// 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](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/limit-order-api/guide.md?ask=<question>
```

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.