FX Trading API: Execute cNGN Trades & Track Status

Execute trades against the Strails FX orderbook using one of three execution modes: quote-based (recommended for price certainty), direct market (best available price), or targeted (against a specific liquidity provider’s order). All trades settle through an on-chain escrow: your cNGN is locked at the time of matching and released to the counterparty only after the blockchain transaction confirms. Use the status endpoints to track each trade through its full lifecycle.

Endpoints Overview

Section	Endpoint	Method	Description
Get Quote	`/fx/quote`	POST	Generate a price quote matched against current orderbook liquidity
Execute Trade	`/fx/trade`	POST	Execute a trade using quote ID, direct params, or a targeted order
Create Market Order	`/fx/market-order`	POST	Submit an immediate market order at the current best price
Get Trade Status	`/fx/trades/status`	GET	Retrieve the current status and details of a single trade
List Trades	`/fx/trades`	GET	List your fintech’s trades with optional filters and pagination

Get Quote

Generate a price quote by matching your requested cNGN amount against live orderbook liquidity. The response includes the matched order(s), the resulting stablecoin amount you will receive, and a quoteId you can pass directly to POST /fx/trade. The quote is valid for five minutes.

Quotes expire exactly five minutes after generation. If you pass an expired quoteId to POST /fx/trade, the request is rejected. Generate a fresh quote and retry.

Request
Response

curl --request POST \
  --url https://api.strails.io/v1/fx/quote \
  --header "x-api-key: <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "pair": "CNGN-USDC",
    "side": "sell",
    "cngnAmount": "50000"
  }'

string

required

Trading pair in the format CNGN-TOKEN. Accepted values: "CNGN-USDC" or "CNGN-USDT".

string

required

Trade direction. Use "sell" to exchange cNGN for the quote currency, or "buy" to acquire cNGN by spending the quote currency.

string

The cNGN amount to trade, expressed as a human-readable decimal (e.g., "50000" means 50,000 cNGN). Provide this or tokenAmount, not both. Minimum is 1,000 cNGN.

string

The pair-currency amount to trade, expressed as a human-readable decimal (e.g., "37.04" for USDC or "37.04" for USDT). Use this when you want the quote denominated in the pair token instead of cNGN. Provide this or cngnAmount, not both.

{
  "status": "Success",
  "response_code": "00",
  "message": "Quote generated successfully",
  "data": {
    "quote": {
      "quoteId": "quote_7f3a9d2c-8e41-4b29-9a1c-5d8e7f2b3a9c",
      "pair": "CNGN-USDC",
      "side": "sell",
      "cngnAmount": "50000",
      "usdcAmount": "37.04",
      "price": "1350.00",
      "matchedOrders": [
        {
          "orderId": "order_abc123",
          "price": "1350.00",
          "cngnAmount": "50000",
          "usdcAmount": "37.04"
        }
      ],
      "expiresAt": "2026-05-01T10:35:00.000Z"
    },
    "version": "1.0.0"
  }
}

string

Unique quote identifier. Pass this to POST /fx/trade to execute at the quoted price.

string

The cNGN amount this quote is priced for.

string

The stablecoin amount you will receive (or spend) if you execute this quote. Field name is dynamic based on the pair: usdcAmount or usdtAmount.

string

The effective exchange rate used for this quote (cNGN per stablecoin unit, human-readable).

array

The orderbook orders matched to fill this quote. Each entry shows the contributing order’s price and amounts.

string

ISO 8601 UTC timestamp after which this quote can no longer be executed.

Execute Trade

Execute an FX trade. Choose from three execution modes depending on how much price certainty and targeting you need.

Before calling this endpoint, ensure the cNGN you intend to trade is held in your Fintech Smart Wallet. You can retrieve your smart wallet address from GET /getfintechwallet.

Mode 1 - Quote (Recommended)
Mode 2 - Direct
Mode 3 - Targeted
Response

Execute against a quote you obtained from POST /fx/quote. This mode locks in the price shown in the quote and is the safest choice to avoid slippage.

curl --request POST \
  --url https://api.strails.io/v1/fx/trade \
  --header "x-api-key: <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "quoteId": "quote_7f3a9d2c-8e41-4b29-9a1c-5d8e7f2b3a9c",
    "idempotencyKey": "trade_20260501_001"
  }'

string

required

The quoteId returned by POST /fx/quote. The quote must not be expired (valid for 5 minutes).

string

An optional client-generated key to prevent duplicate trade submissions. If you retry a request with the same key and the original trade was accepted, the original trade is returned instead of creating a new one.

Execute at the best available market price without generating a quote first. The engine matches your order against the orderbook at the moment of execution.

curl --request POST \
  --url https://api.strails.io/v1/fx/trade \
  --header "x-api-key: <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "pair": "CNGN-USDC",
    "side": "sell",
    "cngnAmount": "50000",
    "destinationWalletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }'

string

required

Trading pair. Accepted values: "CNGN-USDC" or "CNGN-USDT".

string

required

Trade direction: "sell" to exchange cNGN for the quote currency, or "buy" to acquire cNGN.

string

required

cNGN amount in human-readable format (e.g., "50000" = 50,000 cNGN).

string

On-chain wallet address to receive the traded tokens. Defaults to your registered fintech wallet if omitted.

Execute against a specific liquidity provider’s order using its orderId. Use this when you want to trade at an exact LP’s price without going through the quote flow.

curl --request POST \
  --url https://api.strails.io/v1/fx/trade \
  --header "x-api-key: <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "orderId": "order_abc123",
    "cngnAmount": "25000"
  }'

string

required

The orderId of the specific limit order you want to trade against. Retrieve available orders from GET /fx/orderbook.

string

required

cNGN amount to trade against this specific order, in human-readable format. Must fall within the order’s minAmount and maxAmount.

{
  "status": "Success",
  "response_code": "00",
  "message": "Trade executed successfully",
  "data": {
    "trade": {
      "tradeId": "trade_abc123",
      "orderId": "order_abc123",
      "pair": "CNGN-USDC",
      "side": "sell",
      "cngnAmount": "50000",
      "usdcAmount": "37.04",
      "price": "1350.00",
      "strailsFeePercentage": 20,
      "status": "pending",
      "lockId": "lock_xyz789",
      "expiresAt": "2026-05-01T10:35:00.000Z",
      "createdAt": "2026-05-01T10:30:00.000Z"
    },
    "version": "1.0.0"
  }
}

string

Unique trade identifier. Use this with GET /fx/trades/status to track settlement progress.

string

The matched limit order ID. Only present when using Mode 3 (targeted execution).

string

Initial trade status. Always "pending" immediately after submission.

string

Identifier for the escrow lock placed on your cNGN during settlement.

string

ISO 8601 UTC timestamp. If the trade has not progressed to settling by this time, it moves to expired and the locked funds are released.

number

The Strails platform fee percentage applied to this trade.

Create Market Order

Submit an immediate market order that executes at the current best available price from the orderbook. Market orders skip the quote step and settle based on your auto-signing configuration.

Market orders execute against the best available limit order at the time of submission. If orderbook liquidity changes between your request and matching, the final fill price may differ slightly from what you observed in the orderbook stats. Use POST /fx/quote followed by POST /fx/trade (Mode 1) if exact price certainty is required.

Request
Response

curl --request POST \
  --url https://api.strails.io/v1/fx/market-order \
  --header "x-api-key: <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "pair": "CNGN-USDC",
    "side": "sell",
    "cngnAmount": "50000",
    "destinationWalletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "idempotencyKey": "market_20260501_001"
  }'

string

required

Trading pair. Accepted values: "CNGN-USDC" or "CNGN-USDT".

string

required

Trade direction: "sell" to exchange cNGN for the quote currency, or "buy" to acquire cNGN.

string

required

Amount of cNGN to trade, in human-readable format (e.g., "50000" = 50,000 cNGN). Your wallet must hold at least this amount.

string

On-chain address to receive the output tokens. Defaults to your registered fintech wallet if omitted.

string

Client-generated unique key to prevent duplicate order execution on retry.

{
  "responseCode": "00",
  "responseMessage": "Market order executed successfully",
  "data": {
    "trade": {
      "tradeId": "trade_xyz789",
      "pair": "CNGN-USDC",
      "side": "sell",
      "cngnAmount": "50000.00",
      "usdcAmount": "37.04",
      "averagePrice": "1350.00",
      "status": "pending",
      "expiresAt": "2026-05-01T10:35:00.000Z",
      "createdAt": "2026-05-01T10:30:00.000Z"
    },
    "version": "1.0.0",
    "note": "Market order executes at current best price. Settlement proceeds automatically based on your auto-signing configuration."
  }
}

string

Unique trade identifier. Poll GET /fx/trades/status with this ID to track settlement.

string

The effective exchange rate at which the market order was filled.

string

Initial trade status. Always "pending" immediately after submission.

string

ISO 8601 UTC timestamp after which an un-settled trade transitions to "expired".

Get Trade Status

Retrieve the full details and current status of a single trade. Poll this endpoint to track a trade from pending through to completed or failed.

Request
Response

curl --request GET \
  --url "https://api.strails.io/v1/fx/trades/status?tradeId=trade_abc123" \
  --header "x-api-key: <API_KEY>"

string

required

The tradeId returned when the trade was created.

{
  "status": "Success",
  "response_code": "00",
  "message": "Trade status retrieved successfully",
  "data": {
    "trade": {
      "tradeId": "trade_abc123",
      "pair": "CNGN-USDC",
      "side": "sell",
      "cngnAmount": "50000",
      "usdcAmount": "37.04",
      "price": "1350.00",
      "fintechNetAmount": "29.63",
      "status": "completed",
      "lockId": "lock_xyz789",
      "createdAt": "2026-05-01T10:30:00.000Z",
      "priceLockExpiresAt": "2026-05-01T10:35:00.000Z",
      "errorMessage": null,
      "failedAt": null
    },
    "version": "1.0.0"
  }
}

string

Unique trade identifier.

string

Current trade status. See the Trade Status Lifecycle section for all possible values.

string

cNGN amount involved in the trade, human-readable.

string

Stablecoin amount involved in the trade. Field name is dynamic based on the pair (usdcAmount or usdtAmount).

string

The net stablecoin amount credited to your fintech after Strails fees are deducted.

string

Timestamp after which the escrow lock expires if the trade has not settled.

string

Human-readable description of the failure reason. null for non-failed trades.

string

ISO 8601 UTC timestamp of failure. null for non-failed trades.

List Trades

List your fintech’s FX trades with optional filters. Results are paginated using a cursor-based approach with startAfter.

Request
Response

curl --request GET \
  --url "https://api.strails.io/v1/fx/trades?status=completed&limit=50" \
  --header "x-api-key: <API_KEY>"

string

Filter by trading pair. Accepted values: "CNGN-USDC" or "CNGN-USDT".

string

Filter by trade direction. Accepted values: "buy" or "sell". Case-insensitive.

string

Filter by trade status. Case-insensitive. See the Trade Status Lifecycle section for all accepted values.

number

Maximum number of trades to return. Defaults to 50; maximum is 100.

string

The tradeId of the last trade in the previous page. Pass this value to fetch the next page of results.

{
  "status": "Success",
  "response_code": "00",
  "message": "Trades retrieved successfully",
  "data": {
    "trades": [
      {
        "tradeId": "trade_abc123",
        "pair": "CNGN-USDC",
        "side": "sell",
        "cngnAmount": "50000",
        "usdcAmount": "37.04",
        "price": "1350.00",
        "fintechNetAmount": "29.63",
        "status": "completed",
        "createdAt": "2026-05-01T10:30:00.000Z"
      }
    ],
    "count": 1,
    "version": "1.0.0"
  }
}

array

Array of trade objects matching the applied filters, ordered by createdAt descending.

number

Number of trades returned in this page.

Trade Status Lifecycle

Every trade passes through the following statuses as it progresses from submission to final settlement:

Status	Description
`pending`	Trade submitted and parameters are being validated.
`locked`	cNGN locked in escrow. A 5-minute countdown begins at this point.
`signing`	Awaiting MPC Vault signature to authorise the blockchain transaction.
`settling`	Signed transaction submitted to the blockchain; awaiting on-chain confirmation.
`completed`	Settlement confirmed. Tokens transferred to all parties.
`failed`	Trade failed at the `signing` or `settling` stage. Check `errorMessage`.
`expired`	The 5-minute escrow lock elapsed before the trade reached `settling`.

Status Flow

pending --> locked --> signing --> settling --> completed
                              |                 |
                              +--> failed       +--> failed

locked --> expired  (if 5-minute lock window elapses)

When a trade expires or fails, the escrowed cNGN is automatically released back to your wallet.

Common Errors

Code	Error	Description
`01`	`VALIDATION_ERROR`	One or more request fields failed validation.
`01`	`INVALID_QUOTE`	The `quoteId` has expired or does not exist.
`02`	`NO_LIQUIDITY`	Insufficient liquidity in the orderbook for the requested amount.
`02`	`NOT_FOUND`	The requested trade or order was not found, or you do not have access.
`03`	`AUTHENTICATION_FAILED`	The API key is invalid or missing from the request.
`03`	`IP_BLOCKED`	The request originated from an IP address not on your allowlist.
`04`	`RATE_LIMIT_EXCEEDED`	You have exceeded the allowed request rate. Back off and retry.
`05`	`INTERNAL_ERROR`	An unexpected server-side error occurred. Contact support if it persists.

Additional Notes

All cNGN and stablecoin amounts in request bodies use human-readable decimal notation (e.g., "50000" = 50,000 cNGN). All amounts in orderbook fields (price, minAmount, maxAmount, availableLiquidity) use the smallest unit with 6 decimal places. Divide those values by 1,000,000 to convert to human-readable form.

Quotes and trade locks both expire after exactly five minutes. Structure your integration to execute the trade immediately after generating a quote, and to poll GET /fx/trades/status for settlement confirmation rather than relying on synchronous responses.

Overview

Core APIs

FX & Trading

Configuration

FX Trading API: Execute cNGN Trades & Track Status

Endpoints Overview

Get Quote

Execute Trade

Create Market Order

Get Trade Status

List Trades

Trade Status Lifecycle

Status Flow

Common Errors

Additional Notes

​Endpoints Overview

​Get Quote

​Execute Trade

​Create Market Order

​Get Trade Status

​List Trades

​Trade Status Lifecycle

​Status Flow

​Common Errors

​Additional Notes

Endpoints Overview

Get Quote

Execute Trade

Create Market Order

Get Trade Status

List Trades

Trade Status Lifecycle

Status Flow

Common Errors

Additional Notes