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

# Order status, history and positions

> What an order looks like, how its status changes, which orders you see, and how positions relate to your weight allocation.

The production examples on this page use a live key and the production paths. Check the availability notice on [Production access requirements](/production-access) before you use them.

## The order object

Both environments return these fields:

| Field | Meaning |
| - | - |
| `id` | The order's id (a UUID). Use it with `GET /orders/{order_id}`. |
| `environment` | `test` or `production`. |
| `symbol_code`, `trade_type` | What you sent. |
| `quantity` | The weight, as a string, in `unit`. |
| `unit` | `g` or `kg`: the symbol's measure. |
| `price` | The booked rate per the symbol's quoted measure (for example per 10 grams for gold, per kilogram for silver), in rupees, as a string. |
| `total` | The order's value in rupees, as a string. |
| `status` | See [Order statuses](#order-statuses). |
| `client_order_id` | Your reference, if you sent one. |
| `created_at` | When the order was created, as an ISO 8601 time with its UTC offset. |

Test orders add `deal_label` (`T-<n>`). Production orders add:

| Field | Meaning |
| - | - |
| `deal_no` | Bullionwale's deal number. |
| `status_detail` | Bullionwale's internal status name, for support conversations. Branch on `status`, not on this. |
| `source` | The channel the order came from: `api` for yours, or `web`, `mobile` and others for orders placed elsewhere. |
| `close_price` | The closing rate, once the order is closed. Otherwise `null`. |
| `realized_pnl` | The realized profit or loss in rupees, once the order is closed. Otherwise `null`. |
| `closed_at` | When the order was closed. Otherwise `null`. |

## Order statuses

A **test** order is always `filled`.

A **production** order has one of these statuses:

| `status` | Meaning |
| - | - |
| `pending` | Accepted, waiting for Bullionwale's hedge to confirm. Not a deal yet. |
| `open` | Booked at `price`. |
| `closing` | Bullionwale is closing it. |
| `closed` | Closed. `close_price`, `realized_pnl` and `closed_at` are set. |
| `rejected` | The hedge refused it. Nothing was booked. |
| `deleted` | Bullionwale removed it. |

A production order normally moves `pending` → `open` → `closing` → `closed`, or `pending` → `rejected`. Closing is done by Bullionwale; the API does not close or cancel orders.

## Read one order

<CodeGroup>
  ```bash curl theme={null}
  curl -s https://api.bullionwale.com/api/trading/v1/orders/3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10 \
    -H "X-API-Key: $BULLIONWALE_API_KEY"
  ```

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

  BASE = "https://api.bullionwale.com/api/trading/v1"
  HEADERS = {"X-API-Key": os.environ["BULLIONWALE_API_KEY"]}

  order_id = "3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10"
  r = requests.get(f"{BASE}/orders/{order_id}", headers=HEADERS, timeout=10)
  print(r.status_code, r.json()["status"])
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "id": "3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10",
  "deal_no": 240117,
  "environment": "production",
  "symbol_code": "GOLD_TRADE_999",
  "trade_type": "buy",
  "quantity": "10",
  "unit": "g",
  "price": "141250.00",
  "total": "141250.00",
  "status": "open",
  "status_detail": "fixed",
  "source": "api",
  "client_order_id": "bot-42",
  "close_price": null,
  "realized_pnl": null,
  "created_at": "2026-10-14T15:01:05.120000+05:30",
  "closed_at": null
}
```

An order that is not on your account answers `404 order_not_found`.

## Follow a pending order

In production, `POST /orders` can answer `202 Accepted` with the order `pending` while Bullionwale's hedge confirms it. Then:

1. Call `GET /orders/{order_id}` every 1 to 2 seconds.
2. Stop when `status` is no longer `pending`: `open` means booked, `rejected` means nothing was booked, and, rarely, `deleted`.
3. Give up polling after about 30 seconds and check again later. Reads do not use your order budget.

**Never place the order again with a new `Idempotency-Key`** while you are waiting: that would be a second order. See [Idempotency and safe retries](/idempotency).

## List your orders

`GET /orders` takes `limit` (1 to 200, default 50), `offset`, `symbol_code`, `trade_type` and `since` (ISO 8601; a time without a zone is UTC), and returns `items` newest first plus `total`, the number of matching orders.

In production it also takes `status`: `pending`, `open`, `closing`, `closed`, `rejected`, `deleted` or `all` (the default). `all` leaves out deleted orders; ask for `status=deleted` to list those.

<CodeGroup>
  ```bash curl theme={null}
  curl -s "https://api.bullionwale.com/api/trading/v1/orders?status=open&limit=1" \
    -H "X-API-Key: $BULLIONWALE_API_KEY"
  ```

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

  BASE = "https://api.bullionwale.com/api/trading/v1"
  HEADERS = {"X-API-Key": os.environ["BULLIONWALE_API_KEY"]}

  r = requests.get(f"{BASE}/orders", headers=HEADERS,
                   params={"status": "open", "limit": 1}, timeout=10)
  page = r.json()
  print(r.status_code, page["total"], [o["deal_no"] for o in page["items"]])
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "items": [
    {
      "id": "3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10",
      "deal_no": 240117,
      "environment": "production",
      "symbol_code": "GOLD_TRADE_999",
      "trade_type": "buy",
      "quantity": "10",
      "unit": "g",
      "price": "141250.00",
      "total": "141250.00",
      "status": "open",
      "status_detail": "fixed",
      "source": "api",
      "client_order_id": "bot-42",
      "close_price": null,
      "realized_pnl": null,
      "created_at": "2026-10-14T15:01:05.120000+05:30",
      "closed_at": null
    }
  ],
  "total": 3
}
```

### Which orders you see

In production, `GET /orders` returns your account's orders from **every** channel: the app, the web and the API. `source` says which. Orders you placed through the API also carry your `client_order_id`.

One exception: a `pending` or `rejected` order appears only if it was **placed through the API**. An order placed in the app that is still being confirmed, or that the hedge refused, is not shown in the app either, so the API answers `404 order_not_found` for it. It appears once it is confirmed, as `open`.

The test `GET /orders` lists only your test orders.

## Positions and your weight allocation

`GET /positions` shows, per metal, what your weight allocation sees:

| Field | Meaning |
| - | - |
| `net` | Your open net position: buys positive, sells negative. |
| `limit` | Your weight allocation for the metal, set by Bullionwale. |
| `used` | The size of your net position: `net` without its sign. |
| `free` | `limit - used`, never below 0. |
| `unit` | `g` for gold, `kg` for silver. |

<CodeGroup>
  ```bash curl theme={null}
  curl -s https://api.bullionwale.com/api/trading/v1/positions \
    -H "X-API-Key: $BULLIONWALE_API_KEY"
  ```

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

  BASE = "https://api.bullionwale.com/api/trading/v1"
  HEADERS = {"X-API-Key": os.environ["BULLIONWALE_API_KEY"]}

  r = requests.get(f"{BASE}/positions", headers=HEADERS, timeout=10)
  print(r.status_code, r.json()["gold"])
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "gold": {"net": "40", "limit": "1000", "used": "40", "free": "960", "unit": "g"},
  "silver": {"net": "-2", "limit": "5", "used": "2", "free": "3", "unit": "kg"},
  "symbols": [
    {"symbol_code": "GOLD_TRADE_999", "metal": "gold", "buy": "50", "sell": "10", "net": "40", "unit": "g"},
    {"symbol_code": "SILVER_999", "metal": "silver", "buy": "0", "sell": "2", "net": "-2", "unit": "kg"}
  ]
}
```

Production adds `symbols`: one row per symbol with an open position, with the open bought and sold weight and their net, in the metal's unit.

How the allocation works:

* **It is weight, not money.** It caps your open exposure in grams or kilograms per metal. A market order, from the API, the web or the app, runs no rupee margin check.
* **Buys and sells net off.** An offsetting trade frees allocation again. An order that would take `used` past `limit` is refused with `400 limit_exceeded`.
* **Reducing your exposure is always allowed**, even when `used` is already above `limit` (for example after Bullionwale lowered your allocation).
* **Pending orders count.** In production, an order still `pending` already counts towards `net`.
* On the test path, `GET /positions` shows your test book against your real allocation (see [Test and production](/environments#how-test-orders-use-your-weight-allocation)).


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