Orders

An order is the record of any financial operation on CoinMENA. Every trade (buy / sell), every fiatdeposit, and every fiat withdrawal produces one order. This page explains the order object, how to interpret the debit and credit fields, the order lifecycle, and the three ways you can retrieve an order.

Overview

An order represents any financial operation performed on behalf of a client:

Each of those calls returns a freshly created order in the response body. From there, you can retrieve the order again later using one of three lookup endpoints, or list orders across your partner account with filters.

📘

One order object, multiple shapes

All four order types share the same JSON shape. What changes between types is which fields are populated and what they mean. See Reading Order Fields for the per-type mapping.

📘

This page is about the order object

If you want to create a trade order, see the Trading guide. For creating a deposit or withdrawal, see the Funding guide. This page covers what an order looks like, what its statuses mean, and how to retrieve it.

Core Rules

⛔

Orders created through the Partner API are synchronous

Orders created through POST /v1/partner/quotes/execute, POST /v1/partner/deposits, and POST /v1/partner/withdrawals are returned in a final status on the creation response — typically completed on success, or failed / rejected if something went wrong. You do not need to poll for completion.

📘

The order object is the source of truth

For any transaction, the order object is authoritative for status, amounts, and fees. Do not recalculate values from the quote, and do not treat the quote response as final — the order response is final. Always persist the order and use it for reconciliation and accounting.

The Order Object

Every order endpoint returns the same shape, regardless of type.

Identifiers

Classification

Amounts

The meaning of debit and credit depends on the order's type — see Reading Order Fields below for the mapping.

Timestamps

Reading Order Fields

This is the most important table on this page. The debit and credit fields hold different things depending on the order type. Always check type first, then read the fields according to this mapping:

📘

Why the field names do not match the client's perspective

The debit and credit fields reflect CoinMENA's internal accounting convention, not the client's view of the transaction. You do not need to understand the accounting model — read the type field first, then apply the mapping above. The client's balance effect column tells you exactly what happens to the client.

Worked Examples

Here is how the mapping applies in practice.

Buy trade — client bought BTC using USD:

{
  "type": "buy",
  "credit": "98.50",
  "credit_asset_id": "USD",
  "debit": "0.00130000",
  "debit_asset_id": "BTC",
  "price": "75198.9192",
  "fee": "0.73",
  "fee_asset_id": "USD"
}

Client paid 98.50 USD (credit) and received 0.00130000 BTC (debit). Fee was 0.73 USD.

Sell trade — client sold BTC for USD:

{
  "type": "sell",
  "credit": "0.00110000",
  "credit_asset_id": "BTC",
  "debit": "82.11",
  "debit_asset_id": "USD",
  "price": "75208.4784",
  "fee": "0.00000825",
  "fee_asset_id": "BTC"
}

Client gave 0.00110000 BTC (credit) and received 82.11 USD (debit). Fee was 0.00000825 BTC.

Deposit — client deposited USD:

{
  "type": "deposit",
  "credit": null,
  "credit_asset_id": null,
  "debit": "1000.00",
  "debit_asset_id": "USD",
  "price": null
}

Client's USD balance increased by 1000.00 (read from debit).

Withdrawal — client withdrew USD:

{
  "type": "withdrawal",
  "credit": "500.00",
  "credit_asset_id": "USD",
  "debit": null,
  "debit_asset_id": null,
  "price": null
}

Client's USD balance decreased by 500.00 (read from credit).

Order Types

Order Sources

The source field identifies the channel or origin of the order. Most partner-created orders will be bank (deposits, withdrawals) or market (trades), but the full enum lets you distinguish partner orders from other activity on the account:

Order Statuses

The status field reflects the order's current lifecycle state.

Final vs Non-Final Statuses

A final status means the order is finished and will not transition further. A non-final status means the order may still change state.

For orders created through the Partner API, the status returned on the creation response is always a final status — typically completed. Your integration does not need to poll for status changes on partner-created orders.

📘

When you might see non-final statuses

Non-final statuses exist in the enum because the same order model is used elsewhere on the CoinMENA platform. Orders you retrieve via the list or lookup endpoints reflect the current state of the underlying record — in practice, for partner-API-created orders this will almost always be a final status. If you ever see a non-final status on a partner-API order, treat it as an exceptional case worth logging.

Retrieving an Order

The API provides three ways to retrieve orders:

By Order ID

GET /v1/partner/orders/{order_id} returns a single order by CoinMENA's numeric identifier:

GET /v1/partner/orders/67890

Returns the single matching order. If the order does not exist or does not belong to your partner account, the API returns 404 Not Found.

By Partner Order Reference

GET /v1/partner/orders/ref/{partner_order_ref} returns a single order using your own reference:

GET /v1/partner/orders/ref/order-abc-123

This is the reconciliation-friendly lookup path — you never need to store or map CoinMENA's internal id if you tracked your partner_order_ref at creation. Returns 404 if no order under your partner account has that reference.

Listing Orders

GET /v1/partner/orders returns a paginated list of orders. Supported query filters:

See the Pagination guide for the list response shape.

📘

Filter aggressively before paginating

Combine partner_client_id, from_datetime, and status to narrow results before iterating pages. Listing all orders across your partner account and filtering client-side is slower and wastes bandwidth. See the Pagination guide for full guidance.

partner_order_ref on Orders

⚠️

partner_order_ref must be unique per partner

Every partner_order_ref must be unique across all orders under your partner account — deposits, withdrawals, and trades share the same namespace. Reusing a value when creating an order returns error 2020 with HTTP 409 Conflict. This prevents duplicate order creation. It is not silent retry — a conflict means you must fetch the existing order yourself.

• Required for POST /v1/partner/deposits and POST /v1/partner/withdrawals.
• Optional for POST /v1/partner/quotes/execute. If omitted, the returned order has partner_order_ref: null and can only be retrieved later by its numeric id.

Handling a 2020 Conflict

If an order-creating call returns 2020:

1. Do not retry with the same partner_order_ref.
2. Fetch the existing order with GET /v1/partner/orders/ref/{partner_order_ref}.
3. Check the status:
   • If completed — the original succeeded. Treat as done.
   • If failed / rejected — retry with a new partner_order_ref.
4. Update your internal state to reflect the actual outcome.

See Trading and Funding for the full creation flows.

Reconciliation Patterns

How you reconcile depends on whether you tracked partner_order_ref at order creation.

Pattern 1 — You Submitted partner_order_ref (Recommended)

At creation, use your internal order ID as partner_order_ref. Reconciliation becomes a direct lookup:

1. Your system records its internal order ID as partner_order_ref.
2. Periodically (or on demand), call GET /v1/partner/orders/ref/{partner_order_ref}.
3. Match the returned order fields against your records.

No ID mapping needed — your system remains the system of record.

Pattern 2 — You Only Have the CoinMENA id

If you did not provide a partner_order_ref at creation (only applicable to trades), persist the id from the execute response and look up by GET /v1/partner/orders/{order_id} later.

Pattern 3 — Bulk Reconciliation

For daily or batch reconciliation:

1. Call GET /v1/partner/orders?from_datetime=...&to_datetime=...&page=1&page_size=100 with your target time window.
2. Paginate through results until all pages are fetched.
3. Match each order against your records using partner_order_ref (preferred) or id.
4. Flag any orders in CoinMENA but not in your system, and vice versa.

Filter by status: completed if you only want successful orders, or omit the filter to catch failures too.

Common Mistakes

The most frequent issues partners hit when working with orders:

Related Error Codes

The errors you are most likely to see when retrieving orders:

See the Error Codes guide for the full reference.