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

# Placing and Managing Orders

> Place limit and market orders on the Busha exchange, then list, fetch, and cancel them.

This guide will walk you through placing and managing orders on the Busha exchange. A **limit** order rests at a price you name and fills only when the market reaches it. A **market** order takes whatever the order book offers right now. Once placed, you can list, fetch, and cancel your orders.

> [!TIP]
>
> **What You'll Achieve:**
>
> 1. Understand the fields that make up an order.
>
> 2. Place a resting `limit` order and understand how `market` orders are sized.
>
> 3. List and fetch your orders.
>
> 4. Cancel a single order, every order on one market, or arm the dead-man's switch.

## Prerequisites

Before you begin, ensure you have:

* A **Busha Business Account** and **Secret API Key** (from the [Quick Start Tutorial](https://docs.busha.io/guides/getting-started/quick-start.md)).

* An API key that carries the `exchange:trade` (or `api:write`) scope for placing and cancelling orders.

* An understanding of market symbols and trading rules (from [Exchange Markets](https://docs.busha.io/guides/exchange/markets.md)).

## How to Place and Manage Orders

**1. Understand Order Parameters**

Every order needs `market`, `side`, and `type`. The remaining fields depend on the order type:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Required/Optional</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`market`</td>
      <td>Required</td>
      <td>The symbol, e.g. `USDT-NGN`.</td>
    </tr>

    <tr>
      <td>`side`</td>
      <td>Required</td>
      <td>`buy` or `sell`, in terms of the base asset.</td>
    </tr>

    <tr>
      <td>`type`</td>
      <td>Required</td>
      <td>`limit` rests at a named price; `market` takes what the book offers.</td>
    </tr>

    <tr>
      <td>`quantity`</td>
      <td>Optional</td>
      <td>Size in the base asset. Required for `limit` and for `market` `sell`. Mutually exclusive with `quote_quantity`.</td>
    </tr>

    <tr>
      <td>`quote_quantity`</td>
      <td>Optional</td>
      <td>Quote asset spend, used to size a `market` `buy`.</td>
    </tr>

    <tr>
      <td>`price`</td>
      <td>Optional</td>
      <td>Limit price in the quote asset. Required for `limit`, refused on `market`.</td>
    </tr>

    <tr>
      <td>`time_in_force`</td>
      <td>Optional</td>
      <td>`gtc` (rest until filled or cancelled), `ioc` (fill what it can and cancel the rest), or `fok` (fill in full or do nothing). Defaults to `gtc` for `limit` and `ioc` for `market`.</td>
    </tr>

    <tr>
      <td>`post_only`</td>
      <td>Optional</td>
      <td>When `true`, the order never takes liquidity. If it would cross, it is accepted then immediately cancelled with `cancel_reason: post_only_would_cross`.</td>
    </tr>

    <tr>
      <td>`client_order_id`</td>
      <td>Optional</td>
      <td>Your own reference (max 64 chars), unique among your live orders. Re-sending an identical request is safe and returns the existing order.</td>
    </tr>

    <tr>
      <td>`stp_mode`</td>
      <td>Optional</td>
      <td>Self-trade prevention: `cancel_taker` (default), `cancel_maker`, `cancel_both`, or `decrement`.</td>
    </tr>
  </tbody>
</table>

Sizing rules to remember:

* A `limit` order names `quantity` (base) and `price` (quote).
* A `market` `sell` names `quantity` only.
* A `market` `buy` names `quote_quantity` (the quote amount to spend) only — naming none is refused with `market_buy_needs_quote_quantity`.
* A `market` order of either side that names a `price` is refused. To bound the price of a take, place a `limit` order with `time_in_force: ioc`.

**2. Place a Limit Order**

**To place a resting limit order:**

1. Open your terminal or command prompt.

2. Construct a `POST` request to the `/v1/exchange/orders` endpoint.

3. Replace `YOUR_BASE_URL` with your chosen environment's URL and `YOUR_SECRET_TOKEN` with your actual key.

The example below places a post-only bid far below the market so that it rests without filling.

```bash theme={null}
$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/exchange/orders \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "market": "USDT-NGN",
    "side": "buy",
    "type": "limit",
    "quantity": "10",
    "price": "1000.00",
    "time_in_force": "gtc",
    "post_only": true,
    "client_order_id": "doc-test-1791295570"
  }'
```

**Expected Response:**

```json theme={null}
{
  "status": "success",
  "message": "Order placed",
  "data": {
    "id": "ord_hEJQAq4AVy5F",
    "client_order_id": "doc-test-1791295570",
    "market": "USDT-NGN",
    "side": "buy",
    "type": "limit",
    "time_in_force": "gtc",
    "post_only": true,
    "stp_mode": "cancel_taker",
    "status": "open",
    "price": "1000",
    "quantity": "10",
    "filled_quantity": "0",
    "filled_quote": "0",
    "remaining_quantity": "10",
    "average_price": null,
    "maker_fee_rate": "0",
    "taker_fee_rate": "0.002",
    "created_at": "2026-10-06T14:06:11.587079Z",
    "updated_at": "2026-10-06T14:06:11.587079Z",
    "expires_at": null
  }
}
```

Save the returned `id`. Re-sending the identical request under the same `client_order_id` is safe and returns the same order (`200` with `message: Order already exists`) rather than creating a duplicate.

**3. Place a Market Order**

A market order takes whatever the book offers. To buy at market, size your spend with `quote_quantity`:

```bash theme={null}
$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/exchange/orders \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "market": "USDT-NGN",
    "side": "buy",
    "type": "market",
    "quote_quantity": "1000000.00",
    "time_in_force": "ioc",
    "client_order_id": "taker-0442"
  }'
```

A market buy ends `filled` once it has spent the `quote_quantity` in whole `quantity_step`s; the remainder less than one step returns to your available balance. To sell at market, send `quantity` instead.

> [!NOTE]
>
> A market order never carries a `price`. If you want to limit how much you
> pay, use a `limit` order with `time_in_force: ioc`.

**4. List and Fetch Orders**

**To list your orders:**

```bash theme={null}
$ curl -i -X GET \
  "https://YOUR_BASE_URL/v1/exchange/orders?limit=2" \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

Orders come back most recent first. The `status` filter defaults to `open` (which includes `partially_filled`); `closed` returns `filled` and `cancelled`, and `all` returns every state. You can also filter by `market`, `asset`, `side`, `type`, `from`/`to`, or `client_order_id`.

**To fetch a single order by platform ID:**

```bash theme={null}
$ curl -i -X GET \
  https://YOUR_BASE_URL/v1/exchange/orders/ord_hEJQAq4AVy5F \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

An ID belonging to another profile is `not_found`, not `forbidden`.

**5. Cancel Orders**

**To cancel a single order:**

```bash theme={null}
$ curl -i -X DELETE \
  https://YOUR_BASE_URL/v1/exchange/orders/ord_hEJQAq4AVy5F \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

**Expected Response:**

```json theme={null}
{
  "status": "success",
  "message": "Order cancelled",
  "data": {
    "id": "ord_hEJQAq4AVy5F",
    "status": "cancelled",
    "cancel_reason": "user_requested"
  }
}
```

Cancellation is accepted, not necessarily applied — a fill already in flight still prints. Cancelling an order that has already reached `filled` or `cancelled` returns `order_not_cancellable`.

**To cancel every live order on one market** (the `market` query parameter is required):

```bash theme={null}
$ curl -i -X DELETE \
  "https://YOUR_BASE_URL/v1/exchange/orders?market=USDT-NGN" \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

**To arm the dead-man's switch**, which cancels all of your live orders if you stop calling before the timer fires:

```bash theme={null}
$ curl -i -X POST \
  https://YOUR_BASE_URL/v1/exchange/orders/cancel_all_after \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "timeout_seconds": 60
  }'
```

Re-arm on a cadence of about half the timeout (for example, every 15 to 30 seconds for a 60-second window). Set `timeout_seconds: 0` to disarm.

## Troubleshooting Common Issues

* **`duplicate_client_order_id`:** You reused a live `client_order_id` with a different payload. Use a fresh ID, or replay the identical body to safely retry after a network timeout.

* **`market_buy_needs_quote_quantity`:** You placed a `market` `buy` without `quote_quantity`. Add the quote amount to spend, and do not send a `price`.

* **`price_off_tick` or `quantity_off_step`:** Your `price` or `quantity` does not conform to the market's rules. Re-read `GET /v1/exchange/markets/{symbol}` and round accordingly.

* **`post_only_would_cross`:** Not an error — the order was accepted and immediately cancelled. Adjust your price to rest instead.

* **`order_not_cancellable`:** The order has already reached `filled` or `cancelled`.

* **`401 Unauthorized` or `403`:** Your key lacks the `exchange:trade` (or `api:write`) scope.

## What's Next?

Now that you can place and manage orders, reconcile what they actually executed:

* [Fills and Fee Rates](https://docs.busha.io/guides/exchange/fills-and-fees.md)

* [Reading Market Data](https://docs.busha.io/guides/exchange/market-data.md)


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