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

# Marketplace

> Place buy orders and counter-offers on the Afriex marketplace.

Marketplace orders let your business buy an asset at a price it sets, and answer offers with a counter-offer. You can create, list, and withdraw orders through the API.

> [!NOTE]
>
> **The marketplace is available to approved businesses only.** If your business isn't approved, every marketplace endpoint returns `403` with `FEATURE_NOT_AVAILABLE_FOR_BUSINESS`. Contact [support@afriex.com](mailto:support@afriex.com) to ask for approval.

## Orders

| Order | `orderSide` | What it is |
| - | - | - |
| Offer | `BUY` | An offer to buy an asset (`baseSymbol`) for another asset (`quoteSymbol`). You create it with [Create Marketplace Order](https://docs.afriex.com/api-reference/endpoint/marketplace/create-order.md). |
| Counter-offer | `SELL` | An answer to an offer. You create it with [Create Marketplace Counter-Offer](https://docs.afriex.com/api-reference/endpoint/marketplace/create-counter-offer.md), and it must use the same pair as the offer it answers. |

An `orderId` names its side: `BUY-12` is an offer and `SELL-3` is a counter-offer. Use [List Available Marketplace Offers](https://docs.afriex.com/api-reference/endpoint/marketplace/available-orders.md) to see the offers you can answer.

Amounts are decimal values in the asset's main unit, sent as strings:

```json theme={null}
{
  "orderSide": "BUY",
  "baseSymbol": "USD",
  "quoteSymbol": "NGN",
  "amount": {"asset": "USD", "value": "1000"},
  "price": {"asset": "NGN", "value": "1600"},
  "clientOrderId": "order-2026-11-14-001"
}
```

## Order statuses

| Status | Meaning |
| - | - |
| `OPEN` | An offer that is open. A new offer is `OPEN` as soon as you create it. |
| `PENDING_APPROVAL` | Only on offers created before approval was removed. Afriex approves them, and they become `OPEN`. |
| `PENDING_ACCEPTANCE` | A counter-offer that Afriex is reviewing. |
| `ACCEPTED` | A counter-offer that was accepted and is waiting to be funded. |
| `REJECTED` | A counter-offer that was not accepted. |
| `FILLED` | The amount has traded. |
| `CANCELLED` | The owner withdrew the order. |
| `EXPIRED` | The order lapsed. |

A counter-offer never expires. It waits for Afriex to review it.

## Repeating a request safely

Send a `clientOrderId`, your own id for the order, unique for your business. If you repeat a create with a `clientOrderId` you already used, the API returns `409` with `DUPLICATE_REQUEST` and creates nothing, so a retry never places a second order. Look the order up with [List Marketplace Orders](https://docs.afriex.com/api-reference/endpoint/marketplace/list-orders.md).

## API key permissions

Listing and getting orders needs `MARKET_PLACE.READ`. Creating, counter-offering, and withdrawing needs `MARKET_PLACE.MANAGE`. In the dashboard, these are the **Marketplace orders** resource. See [Permissions](https://docs.afriex.com/api-reference/permissions.md).

## Rate limit

Creating orders and counter-offers share one limit of 60 requests per business per 60 seconds. Going over it returns `429`. See [Rate limits](https://docs.afriex.com/api-reference/rate-limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.