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

# Trading Orders API — place and manage orders

> Place limit and market orders, list and filter your order history, retrieve a single order, cancel open orders, and view executed trade history.

The orders API lets you interact with the Dubu trading engine. You can place limit or market orders for any supported trading pair, track their lifecycle from open through to filled or cancelled, and view the individual trades that make up each fill. All endpoints require authentication via API key or JWT bearer token.

## Order statuses

| Status             | Description                                                               |
| ------------------ | ------------------------------------------------------------------------- |
| `OPEN`             | Order is resting in the orderbook, awaiting a match.                      |
| `PARTIALLY_FILLED` | Part of the order quantity has been matched; the remainder is still open. |
| `FILLED`           | The full order quantity has been matched.                                 |
| `CANCELLED`        | The order was cancelled before it could be fully filled.                  |

***

## Place an order

```
POST /trading/orders
```

Submit a new buy or sell order. For `limit` orders you must provide a `price`. For `market` orders the price field is ignored and the order executes at the best available price.

### Request body

<ParamField body="symbol" type="string" required>
  The trading pair symbol. Supported values: `USDT-NGN`, `USDC-NGN`, `USD-NGN`.
</ParamField>

<ParamField body="side" type="string" required>
  Order direction. One of `buy` or `sell`.
</ParamField>

<ParamField body="type" type="string" required>
  Order type. One of `limit` or `market`.
</ParamField>

<ParamField body="quantity" type="string" required>
  The quantity of the base asset to buy or sell. Provided as a decimal string, e.g. `"100.00"`.
</ParamField>

<ParamField body="price" type="string">
  The limit price per unit of the base asset. Required when `type` is `limit`. Omit for `market` orders.
</ParamField>

### Example

```bash theme={null}
curl -X POST https://api.dubupay.com/api/v1/trading/orders \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "USDT-NGN",
    "side": "buy",
    "type": "limit",
    "quantity": "50.00",
    "price": "1580.00"
  }'
```

### Response

Returns `201 Created` with the new order object.

<ResponseField name="id" type="string">
  Unique order identifier (UUID).
</ResponseField>

<ResponseField name="symbol" type="string">
  The trading pair, e.g. `USDT-NGN`.
</ResponseField>

<ResponseField name="side" type="string">
  `buy` or `sell`.
</ResponseField>

<ResponseField name="type" type="string">
  `limit` or `market`.
</ResponseField>

<ResponseField name="quantity" type="string">
  The original requested quantity.
</ResponseField>

<ResponseField name="filled_quantity" type="string">
  How much of the quantity has been matched so far.
</ResponseField>

<ResponseField name="price" type="string">
  The limit price. `null` for market orders.
</ResponseField>

<ResponseField name="status" type="string">
  Current order status: `OPEN`, `PARTIALLY_FILLED`, `FILLED`, or `CANCELLED`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the order was placed.
</ResponseField>

***

## List orders

```
GET /trading/orders
```

Returns a paginated list of your orders, optionally filtered by status, symbol, or side.

### Query parameters

<ParamField query="symbol" type="string">
  Filter to a specific trading pair, e.g. `USDT-NGN`.
</ParamField>

<ParamField query="status" type="string">
  Filter by order status. One of `OPEN`, `PARTIALLY_FILLED`, `FILLED`, or `CANCELLED`.
</ParamField>

<ParamField query="side" type="string">
  Filter by side. One of `buy` or `sell`.
</ParamField>

<ParamField query="page" type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField query="limit" type="number">
  Number of results per page. Maximum `100`. Defaults to `20`.
</ParamField>

### Example

```bash theme={null}
curl "https://api.dubupay.com/api/v1/trading/orders?symbol=USDT-NGN&status=OPEN" \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```

***

## Get an order

```
GET /trading/orders/:id
```

Retrieve a single order by its ID.

### Path parameters

<ParamField path="id" type="string" required>
  The UUID of the order to retrieve.
</ParamField>

### Example

```bash theme={null}
curl https://api.dubupay.com/api/v1/trading/orders/ord_abc123 \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```

***

## Cancel an order

```
DELETE /trading/orders/:id
```

Cancel an open or partially-filled order. You cannot cancel a fully `FILLED` order.

### Path parameters

<ParamField path="id" type="string" required>
  The UUID of the order to cancel.
</ParamField>

### Example

```bash theme={null}
curl -X DELETE https://api.dubupay.com/api/v1/trading/orders/ord_abc123 \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```

***

## List trade history

```
GET /trading/trades
```

Returns a paginated list of all executed trades — the individual fills that result from matched orders. Each trade record represents one match event with a quantity and execution price.

### Example

```bash theme={null}
curl https://api.dubupay.com/api/v1/trading/trades \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```

### Response fields

<ResponseField name="id" type="string">
  Unique trade identifier.
</ResponseField>

<ResponseField name="order_id" type="string">
  The order this trade belongs to.
</ResponseField>

<ResponseField name="symbol" type="string">
  Trading pair, e.g. `USDT-NGN`.
</ResponseField>

<ResponseField name="side" type="string">
  `buy` or `sell`.
</ResponseField>

<ResponseField name="quantity" type="string">
  Quantity filled in this trade.
</ResponseField>

<ResponseField name="price" type="string">
  Execution price for this fill.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the trade was executed.
</ResponseField>