> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strails.co/llms.txt
> Use this file to discover all available pages before exploring further.

# FX Order Management API

> REST API endpoints for managing orderbook orders. Allows fintechs to create liquidity by placing buy/sell orders that other fintechs can trade against.

This section documents endpoints fintechs use to **create, update, delete, and view orderbook orders** for FX trading.

<Info>
  All endpoints require fintech API key authentication and IP allowlist verification.
</Info>

***

## FX Order Management API - Endpoints Overview

| Section                                           | Endpoint                 | Method | Description                                                   |
| ------------------------------------------------- | ------------------------ | ------ | ------------------------------------------------------------- |
| [**Create Limit Order**](#create-limit-order)     | `/fx/limit-order`        | POST   | Create a new limit order to provide liquidity                 |
| [**Update Limit Order**](#update-limit-order)     | `/fx/limit-order/update` | PUT    | Update an existing limit order                                |
| [**Delete Limit Order**](#delete-limit-order)     | `/fx/limit-order/delete` | DELETE | Delete a limit order permanently                              |
| [**List My Limit Orders**](#list-my-limit-orders) | `/fx/limit-orders`       | GET    | Get list of your fintech's limit orders with optional filters |
| [**Get Orderbook**](#get-orderbook)               | `/fx/orderbook`          | GET    | Get public orderbook view for a trading pair                  |
| [**Get Orderbook Stats**](#get-orderbook-stats)   | `/fx/orderbook/stats`    | GET    | Get aggregated statistics for a trading pair                  |
| [**Get Orderbook Token**](#get-orderbook-token)   | `/fx/orderbook-token`    | GET    | Generate a Firebase token for real-time orderbook access      |

***

### Create Limit Order

Create a new limit order to provide liquidity. Your blockchain wallet must have sufficient balance for the order.

<Info>
  Available liquidity is automatically queried from your wallet:

  * For **BUY** orders: you need cNGN in your wallet
  * For **SELL** orders: you need the stablecoin (USDC/USDT) in your wallet
</Info>

<Tabs>
  <Tab title="Request (Create Limit Order)">
    ```http theme={null}
    POST {{BASE_URL}}/fx/limit-order
    ```
  </Tab>

  <Tab title="Body (Create Limit Order)">
    ```json theme={null}
    {
      "pair": "CNGN-USDC",
      "side": "buy",
      "price": "1600.50",
      "spread": 0.5,
      "minAmount": "1000",
      "maxAmount": "100000"
    }
    ```

    ### Parameters

    | Parameter   | Type   | Required | Description                                                                  |
    | ----------- | ------ | -------- | ---------------------------------------------------------------------------- |
    | `pair`      | string | Yes      | Trading pair in format `CNGN-TOKEN` (`CNGN-USDT` or `CNGN-USDC`)             |
    | `side`      | string | Yes      | Order side: `buy` to buy tokens with cNGN, `sell` to sell tokens for cNGN    |
    | `price`     | string | Yes      | Price in cNGN per token (e.g., `1600.50` represents 1600.50 cNGN for 1 USDC) |
    | `spread`    | number | Yes      | Spread percentage (e.g., `0.5` represents 0.5%). Minimum: 0.1%               |
    | `minAmount` | string | Yes      | Minimum trade amount in cNGN. Must be greater than 0 and at most maxAmount   |
    | `maxAmount` | string | Yes      | Maximum trade amount in cNGN. Must be at least minAmount                     |
  </Tab>

  <Tab title="Response (Create Limit Order)">
    ```json theme={null}
    {
      "status": "Success",
      "response_code": "00",
      "message": "Limit order created successfully",
      "data": {
        "orderId": "order_abc123",
        "fintechId": "fintech_xyz789",
        "pair": "CNGN-USDC",
        "side": "buy",
        "price": "1600.50",
        "spread": 0.5,
        "minAmount": "1000.00",
        "maxAmount": "100000.00",
        "availableLiquidity": "95000.00",
        "status": "active",
        "createdAt": "2026-04-04T10:30:00.000Z",
        "updatedAt": "2026-04-04T10:30:00.000Z",
        "version": "1.0.0"
      }
    }
    ```
  </Tab>

  <Tab title="Error (Create Limit Order)">
    ```json theme={null}
    {
      "status": "Error",
      "response_code": "01",
      "message": "Validation error",
      "error": "minAmount must be less than or equal to maxAmount"
    }
    ```

    ```json theme={null}
    {
      "status": "Error",
      "response_code": "01",
      "message": "Validation error",
      "error": "Spread must be at least 0.1%"
    }
    ```

    ```json theme={null}
    {
      "status": "Error",
      "response_code": "05",
      "message": "Insufficient liquidity",
      "error": "Wallet has insufficient balance for this order"
    }
    ```
  </Tab>
</Tabs>

***

### Update Limit Order

Update an existing limit order. You can update price, spread, amounts, or status. At least one field must be provided.

<Info>
  You can only update your own orders. Cannot update deleted orders.
</Info>

<Tabs>
  <Tab title="Request (Update Limit Order)">
    ```http theme={null}
    PUT {{BASE_URL}}/fx/limit-order/update
    ```
  </Tab>

  <Tab title="Body (Update Limit Order)">
    ```json theme={null}
    {
      "orderId": "unique_order_id",
      "price": "1605.00",
      "spread": 0.6,
      "minAmount": "2000",
      "maxAmount": "150000",
      "status": "active"
    }
    ```

    ### Body Parameters

    | Parameter   | Type   | Required | Description                             |
    | ----------- | ------ | -------- | --------------------------------------- |
    | `orderId`   | string | Yes      | Order ID to update                      |
    | `price`     | string | No       | New price in cNGN per token             |
    | `spread`    | number | No       | New spread percentage                   |
    | `minAmount` | string | No       | New minimum trade amount                |
    | `maxAmount` | string | No       | New maximum trade amount                |
    | `status`    | string | No       | New order status (`active` or `paused`) |
  </Tab>

  <Tab title="Response (Update Limit Order)">
    ```json theme={null}
    {
        "status": "Success",
        "response_code": "00",
        "message": "Order updated successfully",
        "data": {
            "order": {
                "orderId": "order_31bb01a2-d20f-416f-8581-aeec687ac8e2",
                "fintechId": "fintech_id",
                "pair": "CNGN-USDC",
                "side": "sell",
                "availableLiquidity": "0",
                "status": "active",
                "createdAt": "2026-04-29T08:08:10.579Z",
                "minAmount": "1300000000",
                "price": "1350000000",
                "maxAmount": "2000000000",
                "spread": 0.6,
                "updatedAt": "2026-04-29T16:31:13.345Z"
            },
            "version": "1.0.0"
        }
    }
    ```
  </Tab>

  <Tab title="Error (Update Limit Order)">
    ```json theme={null}
    {
      "status": "Error",
      "response_code": "02",
      "message": "Order not found",
      "error": "No order found with the provided orderId or you don't have access to it"
    }
    ```

    ```json theme={null}
    {
      "status": "Error",
      "response_code": "01",
      "message": "Validation error",
      "error": "Cannot update a deleted order"
    }
    ```
  </Tab>
</Tabs>

***

### Delete Limit Order

Delete a limit order. This permanently removes the order from the orderbook.

<Tabs>
  <Tab title="Request (Delete Limit Order)">
    ```http theme={null}
    DELETE {{BASE_URL}}/fx/limit-order/delete
    ```
  </Tab>

  <Tab title="Body (Delete Limit Order)">
    ```json theme={null}
    {
      "orderId": "unique_order_id"
    }
    ```

    ### Body Parameters

    | Parameter | Type   | Required | Description        |
    | --------- | ------ | -------- | ------------------ |
    | `orderId` | string | Yes      | Order ID to delete |
  </Tab>

  <Tab title="Response (Delete Limit Order)">
    ```json theme={null}
    {
      "status": "Success",
      "response_code": "00",
      "message": "Order deleted successfully",
      "data": {
        "orderId": "order_abc123",
        "version": "1.0.0"
      }
    }
    ```
  </Tab>

  <Tab title="Error (Delete Limit Order)">
    ```json theme={null}
    {
      "status": "Error",
      "response_code": "02",
      "message": "Order not found",
      "error": "No order found with the provided orderId or you don't have access to it"
    }
    ```

    ```json theme={null}
    {
      "status": "Error",
      "response_code": "01",
      "message": "Validation error",
      "error": "Order is already deleted"
    }
    ```
  </Tab>
</Tabs>

***

### List My Limit Orders

Get list of your fintech's limit orders with optional filters. Returns orders with real-time liquidity information.

<Tabs>
  <Tab title="Request (List My Limit Orders)">
    ```http theme={null}
    GET {{BASE_URL}}/fx/limit-orders?pair=CNGN-USDC&status=active&limit=50
    ```

    ### Query Parameters

    | Parameter | Type   | Required | Description                                                |
    | --------- | ------ | -------- | ---------------------------------------------------------- |
    | `pair`    | string | No       | Filter by trading pair (`CNGN-USDT` or `CNGN-USDC`)        |
    | `status`  | string | No       | Filter by order status (`active`, `paused`, or `deleted`)  |
    | `limit`   | number | No       | Maximum number of orders to return (default: 50, max: 100) |
  </Tab>

  <Tab title="Response (List My Limit Orders)">
    ```json theme={null}
    {
      "status": "Success",
      "response_code": "00",
      "message": "Orders retrieved successfully",
      "data": {
        "orders": [
          {
            "orderId": "order_abc123",
            "fintechId": "fintech_xyz789",
            "pair": "CNGN-USDC",
            "side": "buy",
            "price": "1600.50",
            "spread": 0.5,
            "minAmount": "1000.00",
            "maxAmount": "100000.00",
            "availableLiquidity": "95000.00",
            "status": "active",
            "createdAt": "2026-04-04T10:30:00.000Z",
            "updatedAt": "2026-04-04T10:30:00.000Z"
          }
        ],
        "count": 5,
        "note": "availableLiquidity is informational only and reflects wallet balance at query time.",
        "version": "1.0.0"
      }
    }
    ```
  </Tab>
</Tabs>

***

### Get Orderbook

Get public orderbook view for a trading pair. Shows all active buy and sell orders from all fintechs with real-time liquidity.

<Tabs>
  <Tab title="Request (Get Orderbook)">
    ```http theme={null}
    GET {{BASE_URL}}/fx/orderbook?pair=CNGN-USDC&limit=20
    ```

    ### Query Parameters

    | Parameter | Type   | Required | Description                                               |
    | --------- | ------ | -------- | --------------------------------------------------------- |
    | `pair`    | string | Yes      | Trading pair to query (`CNGN-USDT` or `CNGN-USDC`)        |
    | `limit`   | number | No       | Maximum number of orders per side (default: 20, max: 100) |
  </Tab>

  <Tab title="Response (Get Orderbook)">
    ```json theme={null}
    {
      "status": "Success",
      "response_code": "00",
      "message": "Orderbook retrieved successfully",
      "data": {
        "pair": "CNGN-USDC",
        "buyOrders": [
          {
            "orderId": "order_abc123",
            "price": "1600.50",
            "spread": 0.5,
            "minAmount": "1000.00",
            "maxAmount": "100000.00",
            "availableLiquidity": "95000.00",
            "status": "active",
            "updatedAt": "2026-04-29T16:31:13.345Z"
          }
        ],
        "sellOrders": [
          {
            "orderId": "order_def456",
            "price": "1610.00",
            "spread": 0.6,
            "minAmount": "2000.00",
            "maxAmount": "150000.00",
            "availableLiquidity": "140000.00",
            "status": "active"
          }
        ],
        "version": "1.0.0",
        "note": "availableLiquidity is informational only and reflects wallet balance at query time. Actual available liquidity may change before trade execution and is validated in real-time during matching."
      }
    }
    ```
  </Tab>
</Tabs>

***

### Get Orderbook Stats

Get aggregated statistics for a trading pair including total liquidity and best prices.

<Tabs>
  <Tab title="Request (Orderbook Stats)">
    ```http theme={null}
    GET {{BASE_URL}}/fx/orderbook/stats?pair=CNGN-USDC
    ```

    ### Query Parameters

    | Parameter | Type   | Required | Description                                        |
    | --------- | ------ | -------- | -------------------------------------------------- |
    | `pair`    | string | Yes      | Trading pair to query (`CNGN-USDT` or `CNGN-USDC`) |
  </Tab>

  <Tab title="Response (Orderbook Stats)">
    ```json theme={null}
    {
        "status": "Success",
        "response_code": "00",
        "message": "Orderbook statistics retrieved successfully",
        "data": {
            "pair": "CNGN-USDC",
            "stats": {
                "pair": "CNGN-USDC",
                "totalActiveOrders": 8,
                "buyOrderCount": 2,
                "sellOrderCount": 6,
                "totalBuyLiquidity": "80.494652",
                "totalSellLiquidity": "8179.999",
                "bestBidPrice": "1400",
                "bestAskPrice": "700.5",
                "spreadPercentage": -49.96
            },
            "version": "1.0.0"
        }
    }
    ```
  </Tab>
</Tabs>

***

### Get Orderbook Token

Generate a Firebase custom token for real-time orderbook access. Use this token to subscribe to live orderbook updates via Firebase Realtime Database.

<Warning>
  **Wei Format (6 Decimals):** The following fields are returned in wei format with 6 decimal precision:

  * `price` - e.g., `"1500000"` = 1.5 (divide by 10^6)
  * `minAmount` - e.g., `"500000000"` = 500 tokens
  * `maxAmount` - e.g., `"2000000000"` = 2,000 tokens
  * `availableLiquidity` - e.g., `"95000000000"` = 95,000 tokens

  **Conversion:** To get the human-readable value, divide by `1,000,000` (10^6).
</Warning>

<Tabs>
  <Tab title="Request (Orderbook Token)">
    ```http theme={null}
    GET {{BASE_URL}}/fx/orderbook-token
    ```
  </Tab>

  <Tab title="Response (Orderbook Token)">
    ```json theme={null}
    {
      "responseCode": "00",
      "responseMessage": "Token generated successfully",
      "data": {
        "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expiresIn": 3600,
        "tradingPairs": ["CNGN-USDC", "CNGN-USDT", "CNGN-DAI"],
        "firebaseConfig": {
          "projectId": "Strails-prod",
          "databaseURL": "Strails-prod"
        },
        "usage": "Use this token with Firebase signInWithCustomToken() for real-time orderbook access"
      }
    }
    ```

    **Response Fields:**

    | Field                        | Type   | Description                               |
    | ---------------------------- | ------ | ----------------------------------------- |
    | `token`                      | string | Firebase custom token for authentication  |
    | `expiresIn`                  | number | Token validity in seconds (default: 3600) |
    | `tradingPairs`               | array  | List of active FX trading pairs           |
    | `firebaseConfig.projectId`   | string | Firebase project ID for connection        |
    | `firebaseConfig.databaseURL` | string | Firebase database identifier              |
    | `usage`                      | string | Instructions for using the token          |

    <Info>
      **Trading Pairs:** The `tradingPairs` array contains all currently active FX-enabled pairs. Use these exact strings when querying the orderbook to avoid typos.
    </Info>
  </Tab>
</Tabs>

***

### Order Status Lifecycle

Orders follow a specific status lifecycle:

| Status    | Description                                      |
| --------- | ------------------------------------------------ |
| `active`  | Order is active and can be matched with trades   |
| `paused`  | Order is temporarily paused and won't be matched |
| `deleted` | Order is permanently deleted                     |

### Status Transitions

* `active` -> `paused` (via update)
* `paused` -> `active` (via update)
* `active` -> `deleted` (via delete)
* `paused` -> `deleted` (via delete)

***

### Liquidity Notes

<Info>
  **Important information about liquidity:**

  * `availableLiquidity` is queried in real-time from your blockchain wallet
  * For **BUY** orders: liquidity = your cNGN wallet balance
  * For **SELL** orders: liquidity = your stablecoin (USDC/USDT) wallet balance
  * Liquidity shown is informational only - actual liquidity is validated during trade matching
  * Ensure your wallet has sufficient balance before creating orders
  * Liquidity can change between order creation and trade execution
</Info>

***

### Best Practices

* Monitor your wallet balance regularly
* Update or pause orders if liquidity becomes insufficient
* Use appropriate spreads to account for market volatility
* Set reasonable min/max amounts based on your liquidity
* Use the `paused` status instead of deleting orders you may reactivate
* Query orderbook stats before creating orders to understand market conditions