FX Order Management API

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

All endpoints require fintech API key authentication and IP allowlist verification.

FX Order Management API - Endpoints Overview

Section	Endpoint	Method	Description
Create Limit Order	`/fx/limit-order`	POST	Create a new limit order to provide liquidity
Update Limit Order	`/fx/limit-order/update`	PUT	Update an existing limit order
Delete Limit Order	`/fx/limit-order/delete`	DELETE	Delete a limit order permanently
List My Limit Orders	`/fx/limit-orders`	GET	Get list of your fintech’s limit orders with optional filters
Get Orderbook	`/fx/orderbook`	GET	Get public orderbook view for a trading pair
Get Orderbook Stats	`/fx/orderbook/stats`	GET	Get aggregated statistics for a trading pair
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.

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

Request (Create Limit Order)
Body (Create Limit Order)
Response (Create Limit Order)
Error (Create Limit Order)

POST {{BASE_URL}}/fx/limit-order

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

{
  "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"
  }
}

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "minAmount must be less than or equal to maxAmount"
}

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Spread must be at least 0.1%"
}

{
  "status": "Error",
  "response_code": "05",
  "message": "Insufficient liquidity",
  "error": "Wallet has insufficient balance for this order"
}

Update Limit Order

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

You can only update your own orders. Cannot update deleted orders.

Request (Update Limit Order)
Body (Update Limit Order)
Response (Update Limit Order)
Error (Update Limit Order)

PUT {{BASE_URL}}/fx/limit-order/update

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

{
    "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"
    }
}

{
  "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"
}

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Cannot update a deleted order"
}

Delete Limit Order

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

Request (Delete Limit Order)
Body (Delete Limit Order)
Response (Delete Limit Order)
Error (Delete Limit Order)

DELETE {{BASE_URL}}/fx/limit-order/delete

{
  "orderId": "unique_order_id"
}

Body Parameters

Parameter	Type	Required	Description
`orderId`	string	Yes	Order ID to delete

{
  "status": "Success",
  "response_code": "00",
  "message": "Order deleted successfully",
  "data": {
    "orderId": "order_abc123",
    "version": "1.0.0"
  }
}

{
  "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"
}

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Order is already deleted"
}

List My Limit Orders

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

Request (List My Limit Orders)
Response (List My Limit Orders)

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)

{
  "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"
  }
}

Get Orderbook

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

Request (Get Orderbook)
Response (Get Orderbook)

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)

{
  "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."
  }
}

Get Orderbook Stats

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

Request (Orderbook Stats)
Response (Orderbook Stats)

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

{
    "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"
    }
}

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.

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

Request (Orderbook Token)
Response (Orderbook Token)

GET {{BASE_URL}}/fx/orderbook-token

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

Trading Pairs: The tradingPairs array contains all currently active FX-enabled pairs. Use these exact strings when querying the orderbook to avoid typos.

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

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

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

Overview

Core APIs

FX & Trading

Configuration

FX Order Management API

FX Order Management API - Endpoints Overview

Create Limit Order

Parameters

Update Limit Order

Body Parameters

Delete Limit Order

Body Parameters

List My Limit Orders

Query Parameters

Get Orderbook

Query Parameters

Get Orderbook Stats

Query Parameters

Get Orderbook Token

Order Status Lifecycle

Status Transitions

Liquidity Notes

Best Practices

​FX Order Management API - Endpoints Overview

​Create Limit Order

​Parameters

​Update Limit Order

​Body Parameters

​Delete Limit Order

​Body Parameters

​List My Limit Orders

​Query Parameters

​Get Orderbook

​Query Parameters

​Get Orderbook Stats

​Query Parameters

​Get Orderbook Token

​Order Status Lifecycle

​Status Transitions

​Liquidity Notes

​Best Practices

FX Order Management API - Endpoints Overview

Create Limit Order

Parameters

Update Limit Order

Body Parameters

Delete Limit Order

Body Parameters

List My Limit Orders

Query Parameters

Get Orderbook

Query Parameters

Get Orderbook Stats

Query Parameters

Get Orderbook Token

Order Status Lifecycle

Status Transitions

Liquidity Notes

Best Practices