Your first test order

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

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.

Place the order

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"}'

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"])

201 Created

{
  "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.

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"}'

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"])

200 OK (Idempotent-Replayed: true)

{
  "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:

curl

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"}'

422 Unprocessable Entity

{
  "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.

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"

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"]])

200 OK

{
  "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

curl -s https://api.bullionwale.com/api/trading/test/v1/positions \
  -H "X-API-Key: $BULLIONWALE_API_KEY"

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())

200 OK

{
  "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.

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. No key. Every call needs the X-API-Key header.

curl

curl -s https://api.bullionwale.com/api/trading/test/v1/me

401 Unauthorized

{
  "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):

curl

curl -s https://api.bullionwale.com/api/trading/test/v1/me \
  -H "X-API-Key: $BULLIONWALE_API_KEY"

401 Unauthorized

{
  "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:

curl

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}'

400 Bad Request

{
  "detail": {
    "code": "idempotency_key_required",
    "message": "Send an Idempotency-Key header (1-64 characters)."
  }
}

An Idempotency-Key longer than 64 characters:

curl

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}'

422 Unprocessable Entity

{
  "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:

curl

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}'

403 Forbidden

{
  "detail": {
    "code": "insufficient_scope",
    "message": "This API key does not have the 'orders:write' permission."
  }
}

An unknown symbol:

curl

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}'

404 Not Found

{
  "detail": {
    "code": "unknown_symbol",
    "message": "Unknown symbol"
  }
}

More than your free weight allocation:

curl

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}'

400 Bad Request

{
  "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:

curl

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}'

422 Unprocessable Entity

{
  "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):

curl

curl -s https://api.bullionwale.com/api/trading/test/v1/orders/00000000-0000-4000-8000-000000000000 \
  -H "X-API-Key: $BULLIONWALE_API_KEY"

404 Not Found

{
  "detail": {
    "code": "order_not_found",
    "message": "Order not found."
  }
}

Get started

Trading

Operating your integration

Resources

The order request

Place the order

Send it again with the same key

List your orders

Read your test positions

Try the common errors

​The order request

​Place the order

​Send it again with the same key

​List your orders

​Read your test positions

​Try the common errors

The order request

Place the order

Send it again with the same key

List your orders

Read your test positions

Try the common errors