> ## 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 tradable balance, net of its own reservations

Returns what one wallet can actually trade of one token, in that token's base units.

Nothing is escrowed on this venue, so these are not custody holdings. For the security they describe the holder's own unfrozen balance; for the settlement asset they describe the lesser of balance and the allowance granted to the custody contract. Both are then reduced by everything this venue has reserved against the wallet's own resting orders.

That last subtraction is the point. The chain cannot see an off-chain reservation, so publishing the raw number would overstate inventory by exactly the trader's own quotes and then refuse their next order. This endpoint answers with the same figure the order gate uses.

## Path Parameters

<ParamField path="custodyContract" type="string" required>
  Custody contract address. Use the address from [Get Custody Contract](/endpoints/external-securities-trading/get-custody-contract).
</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">The wallet's balance as the contract reports it.</ResponseField>
    <ResponseField name="locked" type="string">The portion the contract reports as unavailable, such as frozen tokens.</ResponseField>
    <ResponseField name="onChainAvailable" type="string">What the contract reports as available, before this venue's reservations.</ResponseField>
    <ResponseField name="reserved" type="string">Committed to this wallet's resting orders on this venue.</ResponseField>
    <ResponseField name="available" type="string">`onChainAvailable` minus `reserved`. What a new order can draw on.</ResponseField>
  </Expandable>
</ResponseField>

<Note>
  A read that fails answers with zeros rather than an error. Treat an unexpected zero as suspect if the wallet is known to be funded, and use [Get Trade Readiness](/endpoints/external-securities-trading/get-trade-readiness), which surfaces a chain failure explicitly.
</Note>

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

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

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "total": "100000000000",
      "locked": "50000000000",
      "onChainAvailable": "50000000000",
      "reserved": "1042000000",
      "available": "48958000000"
    }
  }
  ```
</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 |