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

# Positions

> Your open net position per metal, measured against the weight allocation Bullionwale sets for your account.

A position is your open **net weight** in a metal: buys count positive, sells negative. Bullionwale gives your account a weight allocation per metal, and every order is checked against it. `GET /positions` shows both, so your program can see how much room it has before it places an order.

| Call | Endpoint | Scope |
| - | - | - |
| [Positions](#read-your-positions) | `GET /positions` | `orders:read` |

The path sits under the test base path `/api/trading/test/v1` or the production base path `/api/trading/v1`. The test path shows the book of your **test** orders; the production path shows your real book. Both are measured against your real allocation (see [How test orders use your weight allocation](/environments#how-test-orders-use-your-weight-allocation)).

## The position object

The response has one entry per metal, `gold` and `silver`:

| Field | Meaning |
| - | - |
| `net` | Your open net position: buys positive, sells negative. |
| `limit` | Your weight allocation for the metal, set by Bullionwale. |
| `used` | The size of your net position: `net` without its sign. |
| `free` | `limit - used`, never below 0. |
| `unit` | `g` for gold, `kg` for silver. |

Production adds `symbols`: one row per symbol with an open position, with the open bought and sold weight (`buy`, `sell`) and their `net`, in the metal's unit.

Every weight is a decimal string. Parse it as a decimal, not a float.

## Read your positions

<CodeGroup>
  ```bash curl theme={null}
  curl -s https://api.bullionwale.com/api/trading/v1/positions \
    -H "X-API-Key: $BULLIONWALE_API_KEY"
  ```

  ```python Python theme={null}
  import os
  import requests

  BASE = "https://api.bullionwale.com/api/trading/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()["gold"])
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "gold": {"net": "40", "limit": "1000", "used": "40", "free": "960", "unit": "g"},
  "silver": {"net": "-2", "limit": "5", "used": "2", "free": "3", "unit": "kg"},
  "symbols": [
    {"symbol_code": "GOLD_TRADE_999", "metal": "gold", "buy": "50", "sell": "10", "net": "40", "unit": "g"},
    {"symbol_code": "SILVER_999", "metal": "silver", "buy": "0", "sell": "2", "net": "-2", "unit": "kg"}
  ]
}
```

## How the allocation works

* **It is weight, not money.** It caps your open exposure in grams or kilograms per metal. A market order, from the API, the web or the app, runs no rupee margin check.
* **Buys and sells net off.** An offsetting trade frees allocation again. An order that would take `used` past `limit` is refused with `400 limit_exceeded`.
* **Reducing your exposure is always allowed**, even when `used` is already above `limit` (for example after Bullionwale lowered your allocation).
* **Pending orders count.** In production, an order still `pending` already counts towards `net`.
* **A test order never moves your real position**, and a real order never moves your test position.

```json 400 Bad Request theme={null}
{
  "detail": {
    "code": "limit_exceeded",
    "message": "Exceeds your gold limit — 40.0000 g free of 1000.0000 g."
  }
}
```

To make room, place an order on the other side (it reduces `used`), or ask Bullionwale to change your allocation.


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