> ## 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.

# Your first test order

> Place a simulated order, replay it safely, list your orders, read your positions and see the common errors.

All examples on this page use the **test environment**, so nothing is booked. They assume your test key is in the `BULLIONWALE_API_KEY` environment variable (see the [quickstart](/quickstart)).

## The order request

`POST /orders` places a market order at the current price. The body:

| Field | Type | Required | Meaning |
| - | - | - | - |
| `symbol_code` | string | yes | The symbol to trade, for example `GOLD_TRADE_999`. Up to 32 characters. |
| `trade_type` | string | yes | `buy` or `sell`. |
| `quantity` | number | yes | A **weight** in the symbol's measure: grams for gram-quoted symbols, kilograms for kilogram-quoted ones. Greater than 0, at most 4 decimal places. |
| `expected_price` | number | no | The price you showed or expect. If the live price has moved beyond Bullionwale's tolerance from it, the order is refused with `409 price_moved` instead of being booked. |
| `client_order_id` | string | no | Your own reference, up to 64 characters. It is echoed back on the order. Always send one: it is how you find an order whose response you never received. |

Send `quantity` and `expected_price` as JSON numbers. Responses return them, and every other amount, as strings.

The `Idempotency-Key` header is required: 1 to 64 characters, a new UUID per order. A missing or empty header is `400 idempotency_key_required`; one longer than 64 characters is `422 invalid_request`. See [Idempotency and safe retries](/idempotency).

## Place the order

<CodeGroup>
  ```bash curl theme={null}
  curl -s -X POST https://api.bullionwale.com/api/trading/test/v1/orders \
    -H "X-API-Key: $BULLIONWALE_API_KEY" \
    -H "Idempotency-Key: 6f1d2b3c-4a5e-4f60-8b7a-9c0d1e2f3a4b" \
    -H "Content-Type: application/json" \
    -d '{"symbol_code": "GOLD_TRADE_999", "trade_type": "buy", "quantity": 10, "client_order_id": "bot-42"}'
  ```

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

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

  idempotency_key = str(uuid.uuid4())  # save it with your order record before sending
  r = requests.post(
      f"{BASE}/orders",
      headers={**HEADERS, "Idempotency-Key": idempotency_key},
      json={"symbol_code": "GOLD_TRADE_999", "trade_type": "buy",
            "quantity": 10, "client_order_id": "bot-42"},
      timeout=10,
  )
  order = r.json()
  print(r.status_code, order["id"], order["status"])
  ```
</CodeGroup>

```json 201 Created theme={null}
{
  "id": "b7d1e0f4-2c9a-4f63-8e1d-0a5c3b2f9e71",
  "deal_label": "T-12",
  "environment": "test",
  "symbol_code": "GOLD_TRADE_999",
  "trade_type": "buy",
  "quantity": "10.0000",
  "unit": "g",
  "price": "141250.00",
  "total": "141250.00",
  "status": "filled",
  "client_order_id": "bot-42",
  "created_at": "2026-10-14T15:01:05.120000+05:30"
}
```

## Send it again with the same key

Sending the same request with the same `Idempotency-Key` does not place a second order. You get the existing order back with status `200` and the response header `Idempotent-Replayed: true`. This is what makes a retry after a timeout safe.

<CodeGroup>
  ```bash curl theme={null}
  curl -s -X POST https://api.bullionwale.com/api/trading/test/v1/orders \
    -H "X-API-Key: $BULLIONWALE_API_KEY" \
    -H "Idempotency-Key: 6f1d2b3c-4a5e-4f60-8b7a-9c0d1e2f3a4b" \
    -H "Content-Type: application/json" \
    -d '{"symbol_code": "GOLD_TRADE_999", "trade_type": "buy", "quantity": 10, "client_order_id": "bot-42"}'
  ```

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

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

  idempotency_key = "6f1d2b3c-4a5e-4f60-8b7a-9c0d1e2f3a4b"  # the key the first attempt used
  r = requests.post(
      f"{BASE}/orders",
      headers={**HEADERS, "Idempotency-Key": idempotency_key},
      json={"symbol_code": "GOLD_TRADE_999", "trade_type": "buy",
            "quantity": 10, "client_order_id": "bot-42"},
      timeout=10,
  )
  print(r.status_code, r.headers.get("Idempotent-Replayed"), r.json()["id"])
  ```
</CodeGroup>

```json 200 OK (Idempotent-Replayed: true) theme={null}
{
  "id": "b7d1e0f4-2c9a-4f63-8e1d-0a5c3b2f9e71",
  "deal_label": "T-12",
  "environment": "test",
  "symbol_code": "GOLD_TRADE_999",
  "trade_type": "buy",
  "quantity": "10.0000",
  "unit": "g",
  "price": "141250.00",
  "total": "141250.00",
  "status": "filled",
  "client_order_id": "bot-42",
  "created_at": "2026-10-14T15:01:05.120000+05:30"
}
```

Reusing the key with a **different** body (another symbol, side, quantity, `expected_price` or `client_order_id`) books nothing and is refused:

```bash curl theme={null}
curl -s -X POST https://api.bullionwale.com/api/trading/test/v1/orders \
  -H "X-API-Key: $BULLIONWALE_API_KEY" \
  -H "Idempotency-Key: 6f1d2b3c-4a5e-4f60-8b7a-9c0d1e2f3a4b" \
  -H "Content-Type: application/json" \
  -d '{"symbol_code": "GOLD_TRADE_999", "trade_type": "buy", "quantity": 11, "client_order_id": "bot-42"}'
```

```json 422 Unprocessable Entity theme={null}
{
  "detail": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used for a different order."
  }
}
```

## List your orders

`GET /orders` returns your test orders, newest first, with the total number that match.

| Query parameter | Meaning |
| - | - |
| `limit` | 1 to 200. Default 50. |
| `offset` | How many to skip, for paging. Default 0. |
| `symbol_code` | Only this symbol. |
| `trade_type` | Only `buy` or only `sell`. |
| `since` | Only orders created at or after this ISO 8601 time. A time without a zone is read as UTC. |

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

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

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

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

```json 200 OK theme={null}
{
  "items": [
    {
      "id": "b7d1e0f4-2c9a-4f63-8e1d-0a5c3b2f9e71",
      "deal_label": "T-12",
      "environment": "test",
      "symbol_code": "GOLD_TRADE_999",
      "trade_type": "buy",
      "quantity": "10.0000",
      "unit": "g",
      "price": "141250.00",
      "total": "141250.00",
      "status": "filled",
      "client_order_id": "bot-42",
      "created_at": "2026-10-14T15:01:05.120000+05:30"
    }
  ],
  "total": 12
}
```

## Read your test positions

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

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

  BASE = "https://api.bullionwale.com/api/trading/test/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())
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "gold": {"net": "10", "limit": "1000", "used": "10", "free": "990", "unit": "g"},
  "silver": {"net": "0", "limit": "5", "used": "0", "free": "5", "unit": "kg"}
}
```

Gold is in grams and silver in kilograms. See [Positions and your weight allocation](/orders-and-positions#positions-and-your-weight-allocation).

## Try the common errors

Every refusal is an HTTP status with a JSON body whose `detail.code` you can branch on. The full list is in [Errors](/errors).

**No key.** Every call needs the `X-API-Key` header.

```bash curl theme={null}
curl -s https://api.bullionwale.com/api/trading/test/v1/me
```

```json 401 Unauthorized theme={null}
{
  "detail": {
    "code": "missing_credential",
    "message": "Send your API key in the X-API-Key header."
  }
}
```

**A live key on a test path** (or a test key on a production path):

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

```json 401 Unauthorized theme={null}
{
  "detail": {
    "code": "wrong_environment",
    "message": "This is a production key; it cannot be used on the test API."
  }
}
```

**No `Idempotency-Key` header** on an order:

```bash curl theme={null}
curl -s -X POST https://api.bullionwale.com/api/trading/test/v1/orders \
  -H "X-API-Key: $BULLIONWALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol_code": "GOLD_TRADE_999", "trade_type": "buy", "quantity": 1}'
```

```json 400 Bad Request theme={null}
{
  "detail": {
    "code": "idempotency_key_required",
    "message": "Send an Idempotency-Key header (1-64 characters)."
  }
}
```

**An `Idempotency-Key` longer than 64 characters:**

```bash curl theme={null}
curl -s -X POST https://api.bullionwale.com/api/trading/test/v1/orders \
  -H "X-API-Key: $BULLIONWALE_API_KEY" \
  -H "Idempotency-Key: this-idempotency-key-is-longer-than-sixty-four-characters-so-it-is-refused" \
  -H "Content-Type: application/json" \
  -d '{"symbol_code": "GOLD_TRADE_999", "trade_type": "buy", "quantity": 1}'
```

```json 422 Unprocessable Entity theme={null}
{
  "detail": {
    "code": "invalid_request",
    "message": "The request is invalid; see `errors`.",
    "errors": [
      {
        "type": "string_too_long",
        "loc": ["header", "Idempotency-Key"],
        "msg": "String should have at most 64 characters",
        "input": "this-idempotency-key-is-longer-than-sixty-four-characters-so-it-is-refused",
        "ctx": {"max_length": 64}
      }
    ]
  }
}
```

**A key without `orders:write`** placing an order:

```bash curl theme={null}
curl -s -X POST https://api.bullionwale.com/api/trading/test/v1/orders \
  -H "X-API-Key: $BULLIONWALE_API_KEY" \
  -H "Idempotency-Key: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" \
  -H "Content-Type: application/json" \
  -d '{"symbol_code": "GOLD_TRADE_999", "trade_type": "buy", "quantity": 1}'
```

```json 403 Forbidden theme={null}
{
  "detail": {
    "code": "insufficient_scope",
    "message": "This API key does not have the 'orders:write' permission."
  }
}
```

**An unknown symbol:**

```bash curl theme={null}
curl -s -X POST https://api.bullionwale.com/api/trading/test/v1/orders \
  -H "X-API-Key: $BULLIONWALE_API_KEY" \
  -H "Idempotency-Key: 2d4f6a8c-0e1b-4c3d-9e5f-7a9b1c3d5e7f" \
  -H "Content-Type: application/json" \
  -d '{"symbol_code": "NO_SUCH_SYMBOL", "trade_type": "buy", "quantity": 1}'
```

```json 404 Not Found theme={null}
{
  "detail": {
    "code": "unknown_symbol",
    "message": "Unknown symbol"
  }
}
```

**More than your free weight allocation:**

```bash curl theme={null}
curl -s -X POST https://api.bullionwale.com/api/trading/test/v1/orders \
  -H "X-API-Key: $BULLIONWALE_API_KEY" \
  -H "Idempotency-Key: 5c7e9a1b-3d5f-4a7c-8e9f-0a1b2c3d4e5f" \
  -H "Content-Type: application/json" \
  -d '{"symbol_code": "GOLD_TRADE_999", "trade_type": "buy", "quantity": 1000000}'
```

```json 400 Bad Request theme={null}
{
  "detail": {
    "code": "limit_exceeded",
    "message": "Exceeds your gold limit — 990.0000 g free of 1000.0000 g."
  }
}
```

**An invalid body**, here a negative quantity. The `errors` list says which field is wrong:

```bash curl theme={null}
curl -s -X POST https://api.bullionwale.com/api/trading/test/v1/orders \
  -H "X-API-Key: $BULLIONWALE_API_KEY" \
  -H "Idempotency-Key: 8e0a2c4e-6a8c-4e0a-9c2e-4a6c8e0a2c4e" \
  -H "Content-Type: application/json" \
  -d '{"symbol_code": "GOLD_TRADE_999", "trade_type": "buy", "quantity": -1}'
```

```json 422 Unprocessable Entity theme={null}
{
  "detail": {
    "code": "invalid_request",
    "message": "The request is invalid; see `errors`.",
    "errors": [
      {
        "type": "greater_than",
        "loc": ["body", "quantity"],
        "msg": "Input should be greater than 0",
        "input": -1,
        "ctx": {"gt": 0.0}
      }
    ]
  }
}
```

**An order id that is not yours** (or does not exist):

```bash curl theme={null}
curl -s https://api.bullionwale.com/api/trading/test/v1/orders/00000000-0000-4000-8000-000000000000 \
  -H "X-API-Key: $BULLIONWALE_API_KEY"
```

```json 404 Not Found theme={null}
{
  "detail": {
    "code": "order_not_found",
    "message": "Order not found."
  }
}
```


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