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

# Place Order

> Place a new order on the Pro platform

## Overview

Place a new limit or market order on the Pro platform. This endpoint requires authentication with an API key that has **Trade** scope.

## Authentication

<ParamField header="X-Api-Key" type="string" required>
  Your API key with Trade scope

  ```
  X-Api-Key: daya_sk_YOUR_API_KEY
  ```
</ParamField>

## Request Body

<ParamField body="symbol" type="string" required>
  Trading pair symbol. All symbols map to a unified USD balance.

  **Example:** `USDT-NGN` (recommended)

  **Allowed values:** `USDT-NGN`, `USDC-NGN`, `USD-NGN`
</ParamField>

<ParamField body="side" type="string" required>
  Order side

  **Allowed values:** `buy`, `sell`
</ParamField>

<ParamField body="type" type="string" required>
  Order type

  **Allowed values:** `limit`, `market`
</ParamField>

<ParamField body="price" type="string">
  Order price (required for limit orders)

  **Example:** `1545.00`

  <Note>
    Required when `type` is `limit`. Not allowed for market orders.
  </Note>
</ParamField>

<ParamField body="quantity" type="string" required>
  Order quantity in base asset

  **Example:** `100.00`
</ParamField>

## Request Examples

<CodeGroup>
  ```json Limit Order theme={null}
  {
    "symbol": "USDT-NGN",
    "side": "buy",
    "type": "limit",
    "price": "1545.00",
    "quantity": "100.00"
  }
  ```

  ```json Market Order theme={null}
  {
    "symbol": "USDT-NGN",
    "side": "buy",
    "type": "market",
    "quantity": "100.00"
  }
  ```

  ```bash cURL - Limit Order theme={null}
  curl --request POST \
    --url https://api.pro.daya.co/public/v1/orders \
    --header 'X-Api-Key: daya_sk_YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "symbol": "USDT-NGN",
      "side": "buy",
      "type": "limit",
      "price": "1545.00",
      "quantity": "100.00"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.pro.daya.co/public/v1/orders', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'daya_sk_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      symbol: 'USDT-NGN',
      side: 'buy',
      type: 'limit',
      price: '1545.00',
      quantity: '100.00'
    })
  });

  const order = await response.json();
  console.log('Order placed:', order.data.order_id);
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'X-Api-Key': 'daya_sk_YOUR_API_KEY',
      'Content-Type': 'application/json'
  }

  data = {
      'symbol': 'USDT-NGN',
      'side': 'buy',
      'type': 'limit',
      'price': '1545.00',
      'quantity': '100.00'
  }

  response = requests.post(
      'https://api.pro.daya.co/public/v1/orders',
      headers=headers,
      json=data
  )

  order = response.json()
  print(f"Order placed: {order['data']['order_id']}")
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      order := map[string]string{
          "symbol": "USDT-NGN",
          "side":   "buy",
          "type":   "limit",
          "price":  "1545.00",
          "quantity": "100.00",
      }
      body, _ := json.Marshal(order)

      req, _ := http.NewRequest("POST", "https://api.pro.daya.co/public/v1/orders", bytes.NewBuffer(body))
      req.Header.Set("X-Api-Key", "daya_sk_YOUR_API_KEY")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      var result map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&result)

      data := result["data"].(map[string]interface{})
      fmt.Println("Order placed:", data["order_id"])
  }
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates if the request was successful
</ResponseField>

<ResponseField name="message" type="string" required>
  Human-readable response message
</ResponseField>

<ResponseField name="data" type="object" required>
  Order placement response

  <Expandable title="data properties">
    <ResponseField name="order_id" type="string">
      Unique order identifier (UUID)

      **Example:** `550e8400-e29b-41d4-a716-446655440000`
    </ResponseField>

    <ResponseField name="status" type="string">
      Initial order status

      **Values:** `pending_settlement`, `new`, `open`
    </ResponseField>

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

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

    <ResponseField name="symbol" type="string">
      Trading pair symbol
    </ResponseField>

    <ResponseField name="requested_quantity" type="string">
      Requested order quantity
    </ResponseField>

    <ResponseField name="filled_quantity" type="string">
      Quantity filled so far
    </ResponseField>

    <ResponseField name="remaining_quantity" type="string">
      Remaining quantity to fill
    </ResponseField>

    <ResponseField name="avg_fill_price" type="string">
      Average fill price (empty if no fills yet)
    </ResponseField>

    <ResponseField name="total_fee_charged" type="string">
      Total fees charged (empty if no fills yet)
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 creation timestamp
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 last update timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp of the response
</ResponseField>

### Success Response

<ResponseExample>
  ```json 201 Created - Limit Order theme={null}
  {
    "success": true,
    "message": "Order placed successfully",
    "data": {
      "order_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending_settlement",
      "side": "buy",
      "type": "limit",
      "symbol": "USD-NGN",
      "requested_quantity": "100.00000000",
      "filled_quantity": "0.00000000",
      "remaining_quantity": "100.00000000",
      "avg_fill_price": "",
      "total_fee_charged": "",
      "created_at": "2024-01-15T10:35:00Z",
      "updated_at": "2024-01-15T10:35:00Z"
    },
    "timestamp": "2024-01-15T10:35:00Z"
  }
  ```

  ```json 201 Created - Market Order (Immediate Fill) theme={null}
  {
    "success": true,
    "message": "Order placed successfully",
    "data": {
      "order_id": "550e8400-e29b-41d4-a716-446655440001",
      "status": "filled",
      "side": "buy",
      "type": "market",
      "symbol": "USD-NGN",
      "requested_quantity": "100.00000000",
      "filled_quantity": "100.00000000",
      "remaining_quantity": "0.00000000",
      "avg_fill_price": "1545.50",
      "total_fee_charged": "0.15455000",
      "created_at": "2024-01-15T10:35:00Z",
      "updated_at": "2024-01-15T10:35:01Z"
    },
    "timestamp": "2024-01-15T10:35:01Z"
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Bad Request - Insufficient balance theme={null}
  {
    "success": false,
    "message": "Insufficient balance",
    "error": {
      "code": "INSUFFICIENT_BALANCE",
      "message": "Insufficient balance to place this order"
    },
    "timestamp": "2024-01-15T10:35:00Z"
  }
  ```

  ```json 400 Bad Request - Invalid order theme={null}
  {
    "success": false,
    "message": "Invalid order",
    "error": {
      "code": "INVALID_ORDER",
      "message": "Price is required for limit orders"
    },
    "timestamp": "2024-01-15T10:35:00Z"
  }
  ```

  ```json 403 Forbidden - Insufficient scope theme={null}
  {
    "success": false,
    "message": "Forbidden",
    "error": {
      "code": "API_KEY_INVALID_SCOPE",
      "message": "API key does not have the required Trade scope"
    },
    "timestamp": "2024-01-15T10:35:00Z"
  }
  ```

  ```json 404 Not Found - Invalid symbol theme={null}
  {
    "success": false,
    "message": "Symbol not found",
    "error": {
      "code": "SYMBOL_NOT_FOUND",
      "message": "The specified trading pair does not exist"
    },
    "timestamp": "2024-01-15T10:35:00Z"
  }
  ```
</ResponseExample>

## Order Types

| Type       | Description                                 | Required Fields     |
| ---------- | ------------------------------------------- | ------------------- |
| **limit**  | Execute at specified price or better        | `price`, `quantity` |
| **market** | Execute immediately at best available price | `quantity`          |

### Limit Orders

Limit orders are placed on the orderbook and wait for a matching order:

* **Buy limit**: Executes at the specified price or lower
* **Sell limit**: Executes at the specified price or higher
* Remains open until filled or cancelled

### Market Orders

Market orders execute immediately at the best available price:

* May experience slippage if orderbook depth is low
* Partially fills if insufficient liquidity

## Order Status Flow

```
pending_settlement → new → open → partially_filled → filled
                           ↓                          ↓
                      cancelled                  cancelled
                           ↓
                        failed
```

| Status               | Description                      |
| -------------------- | -------------------------------- |
| `pending_settlement` | Order is awaiting settlement     |
| `new`                | Order has been created           |
| `open`               | Order is active on the orderbook |
| `partially_filled`   | Order is partially executed      |
| `filled`             | Order is completely executed     |
| `cancelled`          | Order was cancelled by user      |
| `rejected`           | Order was rejected by the system |
| `failed`             | Order failed to execute          |

## Rate Limits

* **100 requests per minute** per API key

## Next Steps

<CardGroup cols={2}>
  <Card title="List Orders" icon="list" href="/pro/api-reference/list-orders">
    View your open orders
  </Card>

  <Card title="Cancel Order" icon="xmark" href="/pro/api-reference/cancel-order">
    Cancel an open order
  </Card>
</CardGroup>