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

# Place a simulated order (test)

> **Available on request.** Ask the Bullionwale desk to turn on API access for your account and issue a test key. Test orders are simulated; nothing is booked.

A SIMULATED market order: nothing reaches the desk. `Idempotency-Key` is required (1-64 characters). 201 on first placement; 200 with `Idempotent-Replayed: true` on a replay of the same key and body.



## OpenAPI

````yaml /openapi.json post /api/trading/test/v1/orders
openapi: 3.1.0
info:
  description: >-
    Place and read bullion orders with an API key. The test environment
    (`/api/trading/test/v1`) simulates orders; the production environment
    (`/api/trading/v1`) books real orders. **Test: available on request.
    Production: switched off.** See the availability notice in the
    documentation.
  title: Bullionwale API
  version: 1.0.0
servers:
  - description: Once the API is available
    url: https://api.bullionwale.com
security: []
tags:
  - description: >-
      Simulated orders for building and testing your integration. Nothing is
      booked. Available on request through the Bullionwale desk.
    name: Test environment
  - description: >-
      Real orders. Switched off: production trading is not available yet and,
      once it opens, is enabled per account by Bullionwale.
    name: Production environment
paths:
  /api/trading/test/v1/orders:
    post:
      tags:
        - Test environment
      summary: Place a simulated order (test)
      description: >-
        **Available on request.** Ask the Bullionwale desk to turn on API access
        for your account and issue a test key. Test orders are simulated;
        nothing is booked.


        A SIMULATED market order: nothing reaches the desk. `Idempotency-Key` is
        required (1-64 characters). 201 on first placement; 200 with
        `Idempotent-Replayed: true` on a replay of the same key and body.
      operationId: place_test_order_api_trading_test_v1_orders_post
      parameters:
        - description: >-
            Required, 1-64 characters. Per account: the same key with the same
            body replays the order.
          in: header
          name: Idempotency-Key
          required: true
          schema:
            anyOf:
              - maxLength: 64
                type: string
              - type: 'null'
            title: Idempotency-Key
      requestBody:
        content:
          application/json:
            examples:
              market_buy:
                summary: A market buy, 10 g
                value:
                  client_order_id: bot-42
                  quantity: 10
                  symbol_code: GOLD_TRADE_999
                  trade_type: buy
              with_expected_price:
                summary: >-
                  A sell with expected_price (409 price_moved past the
                  tolerance)
                value:
                  expected_price: 141250
                  quantity: 5
                  symbol_code: GOLD_TRADE_999
                  trade_type: sell
            schema:
              $ref: '#/components/schemas/TestOrderIn'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                replay:
                  summary: 'Replay of the same key and body (Idempotent-Replayed: true)'
                  value:
                    client_order_id: bot-42
                    created_at: '2026-10-14T09:31:05.120000+00:00'
                    deal_label: T-12
                    environment: test
                    id: b7d1e0f4-2c9a-4f63-8e1d-0a5c3b2f9e71
                    price: '141250.00'
                    quantity: '10.0000'
                    status: filled
                    symbol_code: GOLD_TRADE_999
                    total: '141250.00'
                    trade_type: buy
                    unit: g
              schema:
                $ref: '#/components/schemas/TestOrder'
          description: Replay of an earlier order.
          headers:
            Idempotent-Replayed:
              description: '`true`.'
              schema:
                type: string
        '201':
          content:
            application/json:
              examples:
                filled:
                  summary: Simulated and filled
                  value:
                    client_order_id: bot-42
                    created_at: '2026-10-14T09:31:05.120000+00:00'
                    deal_label: T-12
                    environment: test
                    id: b7d1e0f4-2c9a-4f63-8e1d-0a5c3b2f9e71
                    price: '141250.00'
                    quantity: '10.0000'
                    status: filled
                    symbol_code: GOLD_TRADE_999
                    total: '141250.00'
                    trade_type: buy
                    unit: g
              schema:
                $ref: '#/components/schemas/TestOrder'
          description: Successful Response
        '400':
          content:
            application/json:
              examples:
                limit_exceeded:
                  summary: Over the account's weight limit
                  value:
                    detail:
                      code: limit_exceeded
                      message: Exceeds your gold limit — 40 g free of 1000 g.
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            `idempotency_key_required`: POST /orders needs an Idempotency-Key
            header.

            `symbol_not_trading`: Trading is disabled for the symbol.

            `invalid_side`: trade_type must be buy or sell.

            `no_live_price`: The symbol has no live price.

            `unpriced`: The symbol could not be priced.

            `symbol_frozen`: The symbol's price feed is frozen.

            `quantity_rule`: The quantity breaks the symbol's size rule.

            `group_quantity_rule`: The quantity breaks the group's size terms.

            `limit_exceeded`: The order would exceed the account's weight limit.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            `missing_credential`: No X-API-Key header.

            `malformed_credential`: The key is not shaped like an API key.

            `wrong_tenant`: The key belongs to a different broker.

            `wrong_environment`: A test key on the production API, or the
            reverse.

            `invalid_credential`: Unknown key or wrong secret.

            `credential_revoked`: The key was revoked.

            `credential_rotated`: The key was replaced and its overlap period
            ended.

            `credential_expired`: The key expired.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            `api_access_disabled`: API access is switched off for this account.

            `account_inactive`: The account is not active.

            `insufficient_scope`: The key lacks the scope this route needs.

            `side_not_offered`: This broker does not offer that side.

            `trading_halted`: The desk halted trading.

            `group_trading_disabled`: Trading is disabled for the account's
            group.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: '`unknown_symbol`: No such symbol.'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            `price_moved`: The price moved beyond the tolerance from
            expected_price.
        '422':
          content:
            application/json:
              examples:
                idempotency_key_reused:
                  summary: Same key, different body
                  value:
                    detail:
                      code: idempotency_key_reused
                      message: >-
                        This Idempotency-Key was already used for a different
                        order.
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            `invalid_request`: The request body or parameters are invalid; see
            `detail.errors`.

            `idempotency_key_reused`: The Idempotency-Key was used for a
            different order.
        '429':
          content:
            application/json:
              examples:
                rate_limited:
                  summary: Over the order budget; see Retry-After
                  value:
                    detail:
                      code: rate_limited
                      message: >-
                        API rate limit exceeded for this key or account. Retry
                        later.
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            `auth_throttled`: Too many failed authentications from this address;
            see Retry-After.

            `rate_limited`: This key (or, for orders, this account) exhausted
            its budget; see Retry-After.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: >-
            `rate_limiter_unavailable`: Order rate limiting is temporarily
            unavailable, so orders are refused (reads keep working). Retry after
            `Retry-After` seconds.

            `rates_not_ready`: Rates are not loaded yet.

            `stale_rate`: The rate is stale.

            `pricing_unavailable`: The group price could not be computed.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    TestOrderIn:
      properties:
        client_order_id:
          anyOf:
            - maxLength: 64
              type: string
            - type: 'null'
          title: Client Order Id
        expected_price:
          anyOf:
            - exclusiveMinimum: 0
              type: number
            - type: 'null'
          title: Expected Price
        quantity:
          exclusiveMinimum: 0
          maximum: 1000000
          title: Quantity
          type: number
        symbol_code:
          maxLength: 32
          title: Symbol Code
          type: string
        trade_type:
          title: Trade Type
          type: string
      required:
        - symbol_code
        - trade_type
        - quantity
      title: TestOrderIn
      type: object
    TestOrder:
      properties:
        client_order_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Order Id
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        deal_label:
          description: '`T-<seq>`; a test order has no deal number.'
          title: Deal Label
          type: string
        environment:
          default: test
          title: Environment
          type: string
        id:
          title: Id
          type: string
        price:
          title: Price
          type: string
        quantity:
          title: Quantity
          type: string
        status:
          description: Always `filled`.
          title: Status
          type: string
        symbol_code:
          title: Symbol Code
          type: string
        total:
          title: Total
          type: string
        trade_type:
          title: Trade Type
          type: string
        unit:
          description: '`g` or `kg`.'
          title: Unit
          type: string
      required:
        - id
        - deal_label
        - symbol_code
        - trade_type
        - quantity
        - unit
        - price
        - total
        - status
      title: TestOrder
      type: object
    ApiError:
      description: Every refusal on the trading API.
      properties:
        detail:
          $ref: '#/components/schemas/ApiErrorDetail'
      required:
        - detail
      title: ApiError
      type: object
    ApiErrorDetail:
      additionalProperties: true
      properties:
        code:
          description: Stable machine code; branch on this, not on `message`.
          title: Code
          type: string
        message:
          description: Human-readable text; may change.
          title: Message
          type: string
      required:
        - code
        - message
      title: ApiErrorDetail
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey

````

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