> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Custody Balance

> Read a wallet’s balance inside the commodity custody contract

Returns what one wallet holds of one token inside a custody contract, split into what is free and what is committed to resting orders.

Amounts are on-chain base units in the token's own decimals, not order book units. Convert before comparing against an order's `quantity` or `price`.

The contract is read live. If the read fails, the endpoint answers with zeros rather than an error, so a zero balance and an unreachable node look alike. Treat a sudden zero as suspect if the wallet was funded.

## Path Parameters

<ParamField path="custodyContract" type="string" required>
  Custody contract address, resolved from your instance's network.
</ParamField>

<ParamField path="userAddress" type="string" required>Wallet to read.</ParamField>

<ParamField path="tokenAddress" type="string" required>Token to read. Either side of a pair.</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="total" type="string">Everything the wallet holds in custody, in the token's base units.</ResponseField>
    <ResponseField name="locked" type="string">Amount committed to resting orders and pending settlements.</ResponseField>
    <ResponseField name="available" type="string">Free balance, `total` minus `locked`. This is what a new order can draw on.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.trusset.org/orderbooks/commodities/api/custody/0xf3dac9cf19da1c95a80de890e200bc86e0c6f2da/balance/0xabc7f1093d5e26b804a1c3f78de025916b47c0d3/0xd8f3ba9de5b7b83f66d1a7b1ad96c1a64b811ff9" \
    -H "X-API-Key: trusset_your_key_here"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.trusset.org/orderbooks/commodities/api/custody/${custody}/balance/${user}/${token}`,
    { headers: { 'X-API-Key': 'trusset_your_key_here' } }
  );
  const { data } = await res.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "total": "12000000000000000000",
      "locked": "2000000000000000000",
      "available": "10000000000000000000"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                  | HTTP  | Cause                                               |
| --------------------- | ----- | --------------------------------------------------- |
| `VALIDATION_ERROR`    | `400` | One of the three path addresses is malformed        |
| `SERVICE_NOT_ENABLED` | `403` | The Trading service is not enabled on this instance |