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

# OpenAPI spec and Postman collection

> Download the machine-readable API description and a ready-made Postman collection.

| Download | Contents |
| - | - |
| [OpenAPI spec](/openapi.json) | `openapi.json`: the OpenAPI 3.1 description of every endpoint, the same one the [API reference](/api-reference/overview) is built from. Use it to generate a client or to load the API into your tools. |
| [Postman collection](/postman/bullion-trading-api.postman_collection.json) | `bullion-trading-api.postman_collection.json`: every request, with the safety guards described below. |
| [Postman test environment](/postman/bullion-trading-test.postman_environment.json) | `bullion-trading-test.postman_environment.json`: the variables for the test API. |
| [Postman production environment](/postman/bullion-trading-production.postman_environment.json) | `bullion-trading-production.postman_environment.json`: the variables for the production API. |

Each link opens the JSON file in your browser; save it with the file name shown (in most browsers, right-click the link and choose *Save link as*).

Both environment files point `base_url` at `https://api.bullionwale.com` (check the availability notice on the [introduction](/index) first). Their key fields are empty: you fill them in.

## Using the Postman collection

1. Download the collection and both environment files, then import all three into Postman (**Import**, then select the files).
2. Pick the **test** environment and paste your test key into its `api_key` value. Keep the variable's type as *secret*, and never commit or share an environment file that contains a key.
3. Run the requests in the **Test environment** folder, starting with *Who am I*.

The **Errors**, **Limits** and **Rotation** folders demonstrate the refusals. Some of their requests use extra keys, which you fill into the test environment only if you have them: `wrong_env_api_key` (a live key), `read_only_api_key` (a test key without `orders:write`) and `new_api_key` (the replacement from a rotation). These folders run only against the test API.

<Note>
  If you cannot download the files, Postman can also build a collection from the spec: choose **Import**, then **Link**, and enter `https://docs.bullionwale.com/openapi.json`. A collection made that way has every request but **none of the safety guards** below, so use the collection from this page to place orders.
</Note>

## Safety guards

The collection is built so that it cannot place a real order by accident. Its collection-level script decides, before every request, whether that request may run, and skips it otherwise:

* **Test orders** run only when the environment's path is the test path and `api_key` is a `bwk_test.` key.
* **The production *Place order*** runs only when the path is the production path, `api_key` is a `bwk_live.` key, **and** a variable named `confirm_production_orders` is set to `I-UNDERSTAND-REAL-ORDERS`. That variable is in neither environment file on purpose: add it yourself, only when you mean to place a real order, and remove it afterwards.
* **Reads** run only when the key matches the folder, so running the whole collection under one environment skips the other environment's requests instead of failing.
* **Every request** is skipped unless `base_url` is just a scheme and a host (for example `https://api.bullionwale.com`), so a stray path in `base_url` cannot send a request somewhere else.

The production *Place order* also protects you on retries. It sends `Idempotency-Key: {{prod_idem_key}}`:

* the key is set to a fresh value only when it is empty;
* it is cleared only after a definitive answer (`200`, `201`, `202`, `409` other than `booking_conflict`, or `422`);
* after a `5xx`, a timeout or no answer it is **kept**, so sending again replays the same order instead of booking a second one.

To place a genuinely new order while a key is kept, first find out what happened to the previous one (see [Recovering an order](/idempotency#recovering-an-order-whose-outcome-you-do-not-know)), then clear `prod_idem_key` yourself.

<Warning>
  The guards need **Postman 10 or later**, or **newman 6.1 or later**. Older runners ignore the instruction to skip a request and would send it anyway. Never use an older runner with a live key.
</Warning>

## Running it with newman

To run the test folder from the command line (newman 6.1 or later), from the folder you saved the collection and the test environment file to:

```bash theme={null}
newman run bullion-trading-api.postman_collection.json \
  -e bullion-trading-test.postman_environment.json \
  --env-var "api_key=$BULLIONWALE_API_KEY" \
  --folder "Test environment"
```

Passing the key with `--env-var` keeps it out of the environment file.


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