Trading

Trading lets your clients buy and sell crypto at a price locked in real time. The Partner API uses a two-step model — first calculate a quote, then execute it — so your clients always trade at a guaranteed price with no slippage.

Overview

Trading on behalf of a client is always two steps:

1. Calculate a quote — Call POST /v1/partner/quotes with the client, asset pair, side, and amount. CoinMENA returns a locked market price, fee breakdown, and a short-lived JWT token.
2. Execute the quote — Call POST /v1/partner/quotes/execute with the token from step 1. The order is placed at the locked price and returned as an order object.

The token is the bridge between the two steps. It is single-use and time-limited — if it expires or is reused, execution fails with error 4008.

📘

Why two steps?

The two-step model lets you show the client the exact price, fees, and totals before they commit. They see the final numbers, confirm, and only then do you execute. This avoids slippage and gives the client full visibility into what they are about to pay or receive.

The Core Rule

⛔

Quote → Execute — the rule you must not break

A quote must be executed within its lifetime using the token returned by calculation. If the quote expires, execution will fail with 4008 and a new quote must be requested. Tokens are single-use — once executed, they cannot be reused.

Price Lock & Slippage

Quotes lock the price for the duration specified in the lifetime field (in seconds). Inside that window, the price returned in the quote is exactly what the client pays or receives — there is no slippage.

After lifetime expires, the market price may have moved. Execution with the expired token is rejected, and you must re-quote to get the current price.

End-to-End Trading Flow

 1. List pairs              2. Calculate quote             3. Execute quote
    GET asset-pairs            POST quotes                    POST quotes/execute
    → price, limits            → locked price + token         → order created
                               (valid for `lifetime` sec)

A typical trade end-to-end:

1. Discover pairs — Call GET /v1/partner/asset-pairs to list tradeable pairs and their current buy/sell prices.
2. Calculate a quote — Submit the client, pair, side, and amount. Receive a locked price, fees, and a token valid for lifetime seconds.
3. Show the client the final numbers — Price, fees, total. Let the client confirm.
4. Execute — Send the token back before it expires. Optionally include a partner_order_ref for reconciliation.
5. Receive the order — The API returns the created order object. Persist the order ID (and your partner_order_ref if you used one).

The resulting order is covered in the Orders guide.

📘

Execution is synchronous

A successful execute response means the order has been placed and returned in its final state. Check the status field on the returned order to confirm the outcome — typically completed on success, or failed / rejected if something went wrong during placement. You do not need to poll for completion.

Asset Pairs

An asset pair is a tradeable combination of a base asset and a quote asset, written in BASE-QUOTE format — e.g. BTC-USD.

Reading the Pair Format

asset_pair: BTC-USD
            │   │
            │   └── quote asset (USD) — the pricing/fiat asset
            └────── base asset (BTC) — the asset being bought or sold

Asset Pair Object

Fetched via GET /v1/partner/asset-pairs or GET /v1/partner/asset-pairs/{asset_pair_id}:

Example

{
  "id": "BTC-USD",
  "type": "crypto",
  "base_id": "BTC",
  "quote_id": "USD",
  "decimal_places": 2,
  "inv_decimal_places": 8,
  "min_volume": "0.0001",
  "max_volume": "100",
  "trading_fee": "0.5",
  "tradable": true,
  "buy": "67550.75",
  "sell": "67450.25",
  "daily_change_pct": "2.35"
}

⚠️

Check tradable before calculating a quote

If tradable is false, quote calculation returns error 4000. Always check the flag when surfacing pairs to your users so they do not attempt trades that will be rejected.

Precision Per Pair

Every pair carries its own decimal precision:

• inv_decimal_places — precision for base asset amounts
• decimal_places — precision for quote asset amounts

For the BTC-USD example above:

• base_amount is accepted up to 8 decimal places (e.g. 0.00100000)
• quote_amount is accepted up to 2 decimal places (e.g. 67.50)

These values vary per pair — always read them from the pair object rather than hardcoding.

Trading Limits

Every pair has min_volume and max_volume (nullable) in base asset units. Quotes outside these bounds are rejected:

For 4003 and 4004, the error response includes both the applicable limit and a quote object in msg_detail — useful for showing the client the current rate and why their trade was rejected. See Error Codes.

Buy vs Sell

The side field controls the direction of the trade. Both sides use the same endpoints and schemas.

If the client does not have enough balance in the asset they need to spend, quote calculation returns error 3005 — Insufficient funds. The error response includes a quote object in msg_detail with the calculated price, so you can still show the client the market rate.

📘

Funding before trading

For buy orders, the client needs a quote asset (fiat) balance — fund them first via POST /v1/partner/deposits. For sell orders, the client needs a base asset (crypto) balance. See the Funding guide.

Calculating a Quote

A quote locks a price for the trade the client is about to make. Submit to POST /v1/partner/quotes:

⚠️

base_amount or quote_amount — pick one

Provide exactly one of the two. Sending both, or neither, returns a validation error. Use base_amount when the client wants to buy/sell a specific quantity of the crypto; use quote_amount when the client wants to spend/receive a specific amount of fiat.

Request Example

{
  "partner_client_id": "user_12345",
  "asset_pair": "BTC-USD",
  "side": "buy",
  "base_amount": "0.001"
}

Response — The Quote Object

Example

{
  "result": {
    "market_price": "67500.50",
    "base_amount": "0.00100000",
    "quote_amount": "67.50",
    "fee_amount": "0.34",
    "vat_amount": "0.00",
    "vat_percentage": null,
    "lifetime": 15,
    "token": "eyJhbGciOiJIUzI1NiJ9..."
  }
}

The Quote Token

📘

Design your UI around the token lifetime

Quote lifetimes are short (typically a few seconds). If you show the client a confirmation screen, either:

• Auto-refresh the quote in the background as the client reads, or
• Submit the execute call immediately upon confirmation and handle any 4008 by re-quoting and retrying.

Executing a Quote

Once you have a valid token, execute it to place the order via POST /v1/partner/quotes/execute.

Request

Request Example

{
  "partner_client_id": "user_12345",
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "partner_order_ref": "order-abc-123"
}

Response

The execute response returns the created order object — see the Orders guide for the full order schema and status semantics.

partner_order_ref Uniqueness

⚠️

partner_order_ref must be unique per partner

If you supply a partner_order_ref, the value must be unique across all orders under your partner account. Reusing a value returns error 2020 with HTTP 409 Conflict. This is a reconciliation-uniqueness rule, not a duplicate-submission guard — always use a fresh, unique reference for every new order.

📘

Use partner_order_ref for reconciliation

If you pass a partner_order_ref, you can later fetch the order using your own reference rather than CoinMENA's internal order ID. This simplifies reconciliation when your system is the system of record. See Orders for retrieval patterns.

Why Execute Can Fail

Beyond transport-level errors (timeouts, 5xx, etc.), execute can fail for these business reasons:

Failures specific to the quote step (4000, 4001, 4003, 4004, 3005, 2013) cannot occur at execute — those are already resolved by the time you have a valid token. If quote succeeded, the trade is priced, within limits, and the client has funds.

Client Trading Eligibility

Before any trade can go through, the client must meet these conditions:

See Clients for the active and status model, and Error Codes for full error details.

Amount Fields — Decimals and Precision

Amount fields (base_amount, quote_amount, market_price, fee_amount, etc.) are returned as JSON strings and may use scientific notation for very small values (e.g. "0E-8", "1e-8").

⚠️

Do not parse decimals as numbers

Parsing amount fields as JavaScript number or Python float causes precision loss that compounds across trades. Always use a decimal-aware type — Decimal in Python, decimal.js in JavaScript, or equivalent.

Submit amounts as strings in your requests too — e.g. "base_amount": "0.001", not 0.001. This preserves precision on the way in.

Match the pair's inv_decimal_places and decimal_places when submitting amounts — see Precision Per Pair.

Common Mistakes

The most frequent issues partners hit when implementing trading:

Related Error Codes

The errors you are most likely to see during trading:

See the Error Codes guide for the full reference.