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

# Quickstart

> From a test key to your first simulated order.

<Warning>
  **Availability, as of 2026-10-19: test environment available on request; production trading switched off.**

  | Environment | Status |
  | - | - |
  | Test (`/api/trading/test/v1`) | **Available on request.** Ask the Bullionwale desk to turn on API access for your account and issue a test key. Test orders are simulated and nothing is booked. |
  | Production (`/api/trading/v1`) | **Switched off.** Implemented, but production orders are refused (`403 production_trading_disabled`). Bullionwale will enable it per account once it opens; it is not available today. |

  `https://api.bullionwale.com` serves the API. Without a valid key, every call answers `401`. Your Bullionwale relationship manager will tell you when production trading opens.
</Warning>

This walk-through uses the **test environment**, where orders are simulated and nothing is booked. The examples use `curl` and Python with the [`requests`](https://pypi.org/project/requests/) library.

<Steps>
  <Step title="Get a test key">
    Ask your Bullionwale relationship manager or the Bullionwale desk to turn on API access for your account and to issue a **test** key with the `orders:write` scope. See [Getting access](/getting-access).

    The key is shown to you **once**. Store it in a secret manager, then make it available to your program as an environment variable:

    ```bash theme={null}
    export BULLIONWALE_API_KEY='bwk_test.<broker>.<key id>.<secret>'
    ```
  </Step>

  <Step title="Check the key">
    Call `GET /me`. It confirms which account and key you are using.

    <CodeGroup>
      ```bash curl theme={null}
      curl -s https://api.bullionwale.com/api/trading/test/v1/me \
        -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}/me", headers=HEADERS, timeout=10)
      print(r.status_code, r.json())
      ```
    </CodeGroup>

    ```json 200 theme={null}
    {
      "login_id": "your-login",
      "firm_name": "Your Firm",
      "environment": "test",
      "key_id": "3c1f0a9b7d2e4c6a8b10",
      "key_name": "order-bot",
      "scopes": ["account:read", "orders:read", "orders:write"],
      "production_trading_available": false
    }
    ```
  </Step>

  <Step title="Place a simulated order">
    Send `POST /orders` with an `Idempotency-Key` header. Use a new UUID for each order, and keep it: if the request times out, you resend it with the **same** key. See [Idempotency and safe retries](/idempotency).

    <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: 0b6f3a8e-5d2c-4c1a-9e7f-2a4b6c8d0e1f" \
        -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())  # store it with the order; reuse it on every retry
      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.json())
      ```
    </CodeGroup>

    A test order is filled at once and answers `201 Created`:

    ```json 201 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"
    }
    ```

    `quantity` is a weight in `unit` (here 10 grams). `price` is the rate per the symbol's quoted measure (for this gold symbol, per 10 grams) and `total` is the order's value in rupees.
  </Step>

  <Step title="Read it back">
    Use the `id` from the response.

    <CodeGroup>
      ```bash curl theme={null}
      curl -s https://api.bullionwale.com/api/trading/test/v1/orders/b7d1e0f4-2c9a-4f63-8e1d-0a5c3b2f9e71 \
        -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"]}

      order_id = "b7d1e0f4-2c9a-4f63-8e1d-0a5c3b2f9e71"  # the id from the order you placed
      r = requests.get(f"{BASE}/orders/{order_id}", headers=HEADERS, timeout=10)
      print(r.status_code, r.json())
      ```
    </CodeGroup>

    ```json 200 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"
    }
    ```
  </Step>
</Steps>

## Next steps

* [Your first test order](/first-test-order) goes further: replays, listing, positions and the common errors.
* [Test and production](/environments) explains what changes when you move to real orders.
* [Production access requirements](/production-access) lists what must be in place before you can place a real order.


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