{ "components": { "schemas": { "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" }, "Me": { "properties": { "environment": { "description": "`test` or `production`.", "title": "Environment", "type": "string" }, "firm_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Firm Name" }, "key_id": { "title": "Key Id", "type": "string" }, "key_name": { "title": "Key Name", "type": "string" }, "login_id": { "title": "Login Id", "type": "string" }, "production_trading_available": { "description": "Whether this account can place production orders right now: Bullionwale's production switches are on, your account's API access is on and production trading is enabled for your account. The same answer on the test and production APIs. It is a hint, not a promise: every order is checked again, in full, when it is placed.", "title": "Production Trading Available", "type": "boolean" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" } }, "required": [ "login_id", "environment", "key_id", "key_name", "scopes", "production_trading_available" ], "title": "Me", "type": "object" }, "MetalPosition": { "properties": { "free": { "title": "Free", "type": "string" }, "limit": { "title": "Limit", "type": "string" }, "net": { "title": "Net", "type": "string" }, "unit": { "description": "`g` for gold, `kg` for silver.", "title": "Unit", "type": "string" }, "used": { "title": "Used", "type": "string" } }, "required": [ "net", "limit", "used", "free", "unit" ], "title": "MetalPosition", "type": "object" }, "ProductionOrder": { "properties": { "client_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Order Id" }, "close_price": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Close Price" }, "closed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Closed At" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "deal_no": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The desk's deal number.", "title": "Deal No" }, "environment": { "default": "production", "title": "Environment", "type": "string" }, "id": { "title": "Id", "type": "string" }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Rupees, 2 decimals, as a string.", "title": "Price" }, "quantity": { "title": "Quantity", "type": "string" }, "realized_pnl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Realized Pnl" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Channel: web, mobile, api, ...", "title": "Source" }, "status": { "description": "pending, open, closing, closed, rejected or deleted.", "title": "Status", "type": "string" }, "status_detail": { "description": "The desk's raw status.", "title": "Status Detail", "type": "string" }, "symbol_code": { "title": "Symbol Code", "type": "string" }, "total": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total" }, "trade_type": { "title": "Trade Type", "type": "string" }, "unit": { "description": "`g` or `kg`.", "title": "Unit", "type": "string" } }, "required": [ "id", "symbol_code", "trade_type", "quantity", "unit", "status", "status_detail" ], "title": "ProductionOrder", "type": "object" }, "ProductionOrderIn": { "description": "Same fields and bounds as a test order.", "properties": { "client_order_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Client Order Id" }, "expected_price": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Expected Price" }, "quantity": { "exclusiveMinimum": 0.0, "maximum": 1000000.0, "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": "ProductionOrderIn", "type": "object" }, "ProductionOrderList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ProductionOrder" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total" ], "title": "ProductionOrderList", "type": "object" }, "ProductionPositions": { "properties": { "gold": { "$ref": "#/components/schemas/MetalPosition" }, "silver": { "$ref": "#/components/schemas/MetalPosition" }, "symbols": { "items": { "$ref": "#/components/schemas/SymbolPosition" }, "title": "Symbols", "type": "array" } }, "required": [ "gold", "silver", "symbols" ], "title": "ProductionPositions", "type": "object" }, "SymbolPosition": { "properties": { "buy": { "title": "Buy", "type": "string" }, "metal": { "title": "Metal", "type": "string" }, "net": { "title": "Net", "type": "string" }, "sell": { "title": "Sell", "type": "string" }, "symbol_code": { "title": "Symbol Code", "type": "string" }, "unit": { "title": "Unit", "type": "string" } }, "required": [ "symbol_code", "metal", "buy", "sell", "net", "unit" ], "title": "SymbolPosition", "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-`; 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" }, "TestOrderIn": { "properties": { "client_order_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Client Order Id" }, "expected_price": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Expected Price" }, "quantity": { "exclusiveMinimum": 0.0, "maximum": 1000000.0, "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" }, "TestOrderList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TestOrder" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total" ], "title": "TestOrderList", "type": "object" }, "TestPositions": { "properties": { "gold": { "$ref": "#/components/schemas/MetalPosition" }, "silver": { "$ref": "#/components/schemas/MetalPosition" } }, "required": [ "gold", "silver" ], "title": "TestPositions", "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "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" }, "openapi": "3.1.0", "paths": { "/api/trading/test/v1/me": { "get": { "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.\n\nThe account and key behind `X-API-Key`.", "operationId": "me_test_api_trading_test_v1_me_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`missing_credential`: No X-API-Key header.\n`malformed_credential`: The key is not shaped like an API key.\n`wrong_tenant`: The key belongs to a different broker.\n`wrong_environment`: A test key on the production API, or the reverse.\n`invalid_credential`: Unknown key or wrong secret.\n`credential_revoked`: The key was revoked.\n`credential_rotated`: The key was replaced and its overlap period ended.\n`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.\n`account_inactive`: The account is not active.\n`insufficient_scope`: The key lacks the scope this route needs." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`invalid_request`: The request body or parameters are invalid; see `detail.errors`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`auth_throttled`: Too many failed authentications from this address; see Retry-After.\n`rate_limited`: This key (or, for orders, this account) exhausted its budget; see Retry-After." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Who am I (test)", "tags": [ "Test environment" ] } }, "/api/trading/test/v1/orders": { "get": { "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.\n\nNewest first.", "operationId": "list_test_orders_api_trading_test_v1_orders_get", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "query", "name": "symbol_code", "required": false, "schema": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "title": "Symbol Code" } }, { "in": "query", "name": "trade_type", "required": false, "schema": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "title": "Trade Type" } }, { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestOrderList" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`missing_credential`: No X-API-Key header.\n`malformed_credential`: The key is not shaped like an API key.\n`wrong_tenant`: The key belongs to a different broker.\n`wrong_environment`: A test key on the production API, or the reverse.\n`invalid_credential`: Unknown key or wrong secret.\n`credential_revoked`: The key was revoked.\n`credential_rotated`: The key was replaced and its overlap period ended.\n`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.\n`account_inactive`: The account is not active.\n`insufficient_scope`: The key lacks the scope this route needs." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`invalid_request`: The request body or parameters are invalid; see `detail.errors`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`auth_throttled`: Too many failed authentications from this address; see Retry-After.\n`rate_limited`: This key (or, for orders, this account) exhausted its budget; see Retry-After." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List simulated orders (test)", "tags": [ "Test environment" ] }, "post": { "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.\n\nA 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.\n`symbol_not_trading`: Trading is disabled for the symbol.\n`invalid_side`: trade_type must be buy or sell.\n`no_live_price`: The symbol has no live price.\n`unpriced`: The symbol could not be priced.\n`symbol_frozen`: The symbol's price feed is frozen.\n`quantity_rule`: The quantity breaks the symbol's size rule.\n`group_quantity_rule`: The quantity breaks the group's size terms.\n`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.\n`malformed_credential`: The key is not shaped like an API key.\n`wrong_tenant`: The key belongs to a different broker.\n`wrong_environment`: A test key on the production API, or the reverse.\n`invalid_credential`: Unknown key or wrong secret.\n`credential_revoked`: The key was revoked.\n`credential_rotated`: The key was replaced and its overlap period ended.\n`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.\n`account_inactive`: The account is not active.\n`insufficient_scope`: The key lacks the scope this route needs.\n`side_not_offered`: This broker does not offer that side.\n`trading_halted`: The desk halted trading.\n`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`.\n`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.\n`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.\n`rates_not_ready`: Rates are not loaded yet.\n`stale_rate`: The rate is stale.\n`pricing_unavailable`: The group price could not be computed." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Place a simulated order (test)", "tags": [ "Test environment" ] } }, "/api/trading/test/v1/orders/{order_id}": { "get": { "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.\n\nOne simulated order (test)", "operationId": "get_test_order_api_trading_test_v1_orders__order_id__get", "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "title": "Order Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestOrder" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`missing_credential`: No X-API-Key header.\n`malformed_credential`: The key is not shaped like an API key.\n`wrong_tenant`: The key belongs to a different broker.\n`wrong_environment`: A test key on the production API, or the reverse.\n`invalid_credential`: Unknown key or wrong secret.\n`credential_revoked`: The key was revoked.\n`credential_rotated`: The key was replaced and its overlap period ended.\n`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.\n`account_inactive`: The account is not active.\n`insufficient_scope`: The key lacks the scope this route needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`order_not_found`: No such order on this account." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`invalid_request`: The request body or parameters are invalid; see `detail.errors`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`auth_throttled`: Too many failed authentications from this address; see Retry-After.\n`rate_limited`: This key (or, for orders, this account) exhausted its budget; see Retry-After." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "One simulated order (test)", "tags": [ "Test environment" ] } }, "/api/trading/test/v1/positions": { "get": { "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.\n\nThe client's TEST book per metal, in the metal's display unit (g gold, kg silver).", "operationId": "test_positions_api_trading_test_v1_positions_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestPositions" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`missing_credential`: No X-API-Key header.\n`malformed_credential`: The key is not shaped like an API key.\n`wrong_tenant`: The key belongs to a different broker.\n`wrong_environment`: A test key on the production API, or the reverse.\n`invalid_credential`: Unknown key or wrong secret.\n`credential_revoked`: The key was revoked.\n`credential_rotated`: The key was replaced and its overlap period ended.\n`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.\n`account_inactive`: The account is not active.\n`insufficient_scope`: The key lacks the scope this route needs." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`invalid_request`: The request body or parameters are invalid; see `detail.errors`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`auth_throttled`: Too many failed authentications from this address; see Retry-After.\n`rate_limited`: This key (or, for orders, this account) exhausted its budget; see Retry-After." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Test positions", "tags": [ "Test environment" ] } }, "/api/trading/v1/me": { "get": { "description": "**Switched off.** Production trading is implemented but not available: orders are refused with `403 production_trading_disabled`. Once it opens, Bullionwale enables production access per account (see Production access requirements).\n\nThe account and key behind `X-API-Key`.", "operationId": "me_live_api_trading_v1_me_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`missing_credential`: No X-API-Key header.\n`malformed_credential`: The key is not shaped like an API key.\n`wrong_tenant`: The key belongs to a different broker.\n`wrong_environment`: A test key on the production API, or the reverse.\n`invalid_credential`: Unknown key or wrong secret.\n`credential_revoked`: The key was revoked.\n`credential_rotated`: The key was replaced and its overlap period ended.\n`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.\n`account_inactive`: The account is not active.\n`insufficient_scope`: The key lacks the scope this route needs." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`invalid_request`: The request body or parameters are invalid; see `detail.errors`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`auth_throttled`: Too many failed authentications from this address; see Retry-After.\n`rate_limited`: This key (or, for orders, this account) exhausted its budget; see Retry-After." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Who am I (production)", "tags": [ "Production environment" ] } }, "/api/trading/v1/orders": { "get": { "description": "**Switched off.** Production trading is implemented but not available: orders are refused with `403 production_trading_disabled`. Once it opens, Bullionwale enables production access per account (see Production access requirements).\n\nEvery order of the account (web, mobile and API alike), newest first. `all` leaves\nout orders the desk deleted; `status=deleted` lists only those. `pending` and `rejected`\norders appear only when placed through the API (the web never lists either).", "operationId": "list_live_orders_api_trading_v1_orders_get", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "default": "all", "pattern": "^(pending|open|closing|closed|rejected|deleted|all)$", "title": "Status", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "query", "name": "symbol_code", "required": false, "schema": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "title": "Symbol Code" } }, { "in": "query", "name": "trade_type", "required": false, "schema": { "anyOf": [ { "maxLength": 8, "type": "string" }, { "type": "null" } ], "title": "Trade Type" } }, { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionOrderList" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`missing_credential`: No X-API-Key header.\n`malformed_credential`: The key is not shaped like an API key.\n`wrong_tenant`: The key belongs to a different broker.\n`wrong_environment`: A test key on the production API, or the reverse.\n`invalid_credential`: Unknown key or wrong secret.\n`credential_revoked`: The key was revoked.\n`credential_rotated`: The key was replaced and its overlap period ended.\n`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.\n`account_inactive`: The account is not active.\n`insufficient_scope`: The key lacks the scope this route needs." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`invalid_request`: The request body or parameters are invalid; see `detail.errors`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`auth_throttled`: Too many failed authentications from this address; see Retry-After.\n`rate_limited`: This key (or, for orders, this account) exhausted its budget; see Retry-After." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List orders (production)", "tags": [ "Production environment" ] }, "post": { "description": "**Switched off.** Production trading is implemented but not available: orders are refused with `403 production_trading_disabled`. Once it opens, Bullionwale enables production access per account (see Production access requirements).\n\nA REAL order, booked through the same path as the web. `Idempotency-Key` is required (1-64 characters) and is per ACCOUNT, so it survives key rotation. 201 = open; 202 = pending (hedge confirming: poll `GET /orders/{id}`); 200 + `Idempotent-Replayed: true` = replay of the same key and body; 409 `order_rejected` = the hedge refused it (a replay answers 409 again); 422 `idempotency_key_reused` = same key, different body. If the booking fails after submission the answer is what was committed: the order (201/202/409), or 503 `booking_not_completed` (nothing was booked yet) or `booking_outcome_unknown`; retry either 503 with the same key for the definitive outcome.", "operationId": "place_order_api_trading_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/ProductionOrderIn" } } }, "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_no": 240117, "environment": "production", "id": "3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10", "price": "141250.00", "quantity": "10", "source": "api", "status": "open", "status_detail": "fixed", "symbol_code": "GOLD_TRADE_999", "total": "141250.00", "trade_type": "buy", "unit": "g" } } }, "schema": { "$ref": "#/components/schemas/ProductionOrder" } } }, "description": "Replay of an earlier order.", "headers": { "Idempotent-Replayed": { "description": "`true`.", "schema": { "type": "string" } } } }, "201": { "content": { "application/json": { "examples": { "open": { "summary": "Booked and open", "value": { "client_order_id": "bot-42", "created_at": "2026-10-14T09:31:05.120000+00:00", "deal_no": 240117, "environment": "production", "id": "3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10", "price": "141250.00", "quantity": "10", "source": "api", "status": "open", "status_detail": "fixed", "symbol_code": "GOLD_TRADE_999", "total": "141250.00", "trade_type": "buy", "unit": "g" } } }, "schema": { "$ref": "#/components/schemas/ProductionOrder" } } }, "description": "Booked, open." }, "202": { "content": { "application/json": { "examples": { "pending": { "summary": "The hedge is confirming: poll GET /orders/{id}", "value": { "client_order_id": "bot-42", "created_at": "2026-10-14T09:31:05.120000+00:00", "deal_no": 240117, "environment": "production", "id": "3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10", "price": "141250.00", "quantity": "10", "source": "api", "status": "pending", "status_detail": "placing", "symbol_code": "GOLD_TRADE_999", "total": "141250.00", "trade_type": "buy", "unit": "g" } } }, "schema": { "$ref": "#/components/schemas/ProductionOrder" } } }, "description": "Pending: the hedge is confirming. Poll the order." }, "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.\n`symbol_not_trading`: Trading is disabled for the symbol.\n`invalid_side`: trade_type must be buy or sell.\n`no_live_price`: The symbol has no live price.\n`unpriced`: The symbol could not be priced.\n`symbol_frozen`: The symbol's price feed is frozen.\n`quantity_rule`: The quantity breaks the symbol's size rule.\n`group_quantity_rule`: The quantity breaks the group's size terms.\n`limit_exceeded`: The order would exceed the account's weight limit.\n`out_of_stock`: Not enough stock for a buy." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`missing_credential`: No X-API-Key header.\n`malformed_credential`: The key is not shaped like an API key.\n`wrong_tenant`: The key belongs to a different broker.\n`wrong_environment`: A test key on the production API, or the reverse.\n`invalid_credential`: Unknown key or wrong secret.\n`credential_revoked`: The key was revoked.\n`credential_rotated`: The key was replaced and its overlap period ended.\n`credential_expired`: The key expired." }, "403": { "content": { "application/json": { "examples": { "production_trading_disabled": { "summary": "A switch is off", "value": { "detail": { "code": "production_trading_disabled", "message": "Trading through the production API is not available.", "reason": "global" } } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`api_access_disabled`: API access is switched off for this account.\n`account_inactive`: The account is not active.\n`insufficient_scope`: The key lacks the scope this route needs.\n`side_not_offered`: This broker does not offer that side.\n`trading_halted`: The desk halted trading.\n`group_trading_disabled`: Trading is disabled for the account's group.\n`production_trading_disabled`: Production trading is not available to your account right now; `detail.reason` is `deploy`, `global` or `account`." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`unknown_symbol`: No such symbol." }, "409": { "content": { "application/json": { "examples": { "order_rejected": { "summary": "The hedge refused the order", "value": { "detail": { "code": "order_rejected", "message": "The order could not be confirmed. Please try again.", "order": { "client_order_id": "bot-42", "created_at": "2026-10-14T09:31:05.120000+00:00", "deal_no": 240117, "environment": "production", "id": "3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10", "price": "141250.00", "quantity": "10", "source": "api", "status": "rejected", "status_detail": "rejected", "symbol_code": "GOLD_TRADE_999", "total": "141250.00", "trade_type": "buy", "unit": "g" }, "order_id": "3f0c6a52-8a3e-4b8e-9a52-6d2f1c7e9b10" } } }, "price_moved": { "summary": "The price moved beyond the tolerance from expected_price", "value": { "detail": { "code": "price_moved", "message": "Price moved from ₹141250.00 to ₹141980.00 since you saw it. Please review the new price and submit again." } } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`price_moved`: The price moved beyond the tolerance from expected_price.\n`booking_conflict`: A concurrent booking conflicted; retry with the same key.\n`order_rejected`: The hedge refused the order; `detail.order_id` names it and `detail.order` shows it. A replay of the same key answers 409 again, with the same fields." }, "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`.\n`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.\n`rate_limited`: This key (or, for orders, this account) exhausted its budget; see Retry-After." }, "503": { "content": { "application/json": { "examples": { "booking_not_completed": { "summary": "Failed, and no committed order was found (Retry-After)", "value": { "detail": { "code": "booking_not_completed", "message": "Nothing was booked yet. Retry with the same Idempotency-Key for the definitive outcome." } } }, "booking_outcome_unknown": { "summary": "Failed, and the outcome could not be read (Retry-After)", "value": { "detail": { "code": "booking_outcome_unknown", "message": "The outcome is unknown. Retry with the same Idempotency-Key to get it." } } } }, "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.\n`rates_not_ready`: Rates are not loaded yet.\n`stale_rate`: The rate is stale.\n`tradeability_unverified`: The symbol's tradeability could not be verified.\n`symbol_unavailable`: The symbol is unavailable.\n`pricing_unavailable`: The group price could not be computed.\n`production_prerequisites_unmet`: Production trading is paused by Bullionwale. Nothing was booked. Retry later; there is nothing to change on your side.\n`booking_unavailable`: The order could not be recorded, so nothing was booked; retry with the same key.\n`booking_busy`: The booking waited too long behind the account's other bookings, so nothing was booked; retry with the same key after Retry-After.\n`booking_not_completed`: The booking failed and no committed order was found: nothing was booked yet; retry with the same key after Retry-After for the definitive outcome.\n`booking_outcome_unknown`: The booking failed and its outcome could not be read; retry with the same key after Retry-After to get it." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Place a REAL market order (production)", "tags": [ "Production environment" ] } }, "/api/trading/v1/orders/{order_id}": { "get": { "description": "**Switched off.** Production trading is implemented but not available: orders are refused with `403 production_trading_disabled`. Once it opens, Bullionwale enables production access per account (see Production access requirements).\n\nOne of the account's own orders (a deleted one reads `deleted`). A `pending` or\n`rejected` order not placed through the API is 404, as it is hidden on the web.", "operationId": "get_live_order_api_trading_v1_orders__order_id__get", "parameters": [ { "in": "path", "name": "order_id", "required": true, "schema": { "title": "Order Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionOrder" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`missing_credential`: No X-API-Key header.\n`malformed_credential`: The key is not shaped like an API key.\n`wrong_tenant`: The key belongs to a different broker.\n`wrong_environment`: A test key on the production API, or the reverse.\n`invalid_credential`: Unknown key or wrong secret.\n`credential_revoked`: The key was revoked.\n`credential_rotated`: The key was replaced and its overlap period ended.\n`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.\n`account_inactive`: The account is not active.\n`insufficient_scope`: The key lacks the scope this route needs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`order_not_found`: No such order on this account." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`invalid_request`: The request body or parameters are invalid; see `detail.errors`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`auth_throttled`: Too many failed authentications from this address; see Retry-After.\n`rate_limited`: This key (or, for orders, this account) exhausted its budget; see Retry-After." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "One order (production)", "tags": [ "Production environment" ] } }, "/api/trading/v1/positions": { "get": { "description": "**Switched off.** Production trading is implemented but not available: orders are refused with `403 production_trading_disabled`. Once it opens, Bullionwale enables production access per account (see Production access requirements).\n\nThe client's REAL book per metal (display unit: g gold, kg silver) + per symbol.", "operationId": "live_positions_api_trading_v1_positions_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductionPositions" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`missing_credential`: No X-API-Key header.\n`malformed_credential`: The key is not shaped like an API key.\n`wrong_tenant`: The key belongs to a different broker.\n`wrong_environment`: A test key on the production API, or the reverse.\n`invalid_credential`: Unknown key or wrong secret.\n`credential_revoked`: The key was revoked.\n`credential_rotated`: The key was replaced and its overlap period ended.\n`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.\n`account_inactive`: The account is not active.\n`insufficient_scope`: The key lacks the scope this route needs." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`invalid_request`: The request body or parameters are invalid; see `detail.errors`." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "`auth_throttled`: Too many failed authentications from this address; see Retry-After.\n`rate_limited`: This key (or, for orders, this account) exhausted its budget; see Retry-After." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Production positions", "tags": [ "Production environment" ] } } }, "servers": [ { "description": "Once the API is available", "url": "https://api.bullionwale.com" } ], "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" } ] }