# Checking Your Client Balance

Retrieve available, pending, and total balances for your Movmint Client Balance accounts.

## Checking Your Client Balance

The `GET /client/balance` endpoint returns the current balance state for all Client Balance accounts belonging to your organization. You can optionally filter by asset to retrieve the balance for a specific currency.

### Request

```
GET /client/balance
Authorization: Bearer <your-token>
```

#### Query Parameters

| Parameter | Type   | Required | Description                                                                                                           |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `asset`   | string | No       | If provided, returns balances only for the specified asset (e.g. `USDC`). Otherwise, all asset balances are returned. |

### Code Examples

#### Go

```go
package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
)

const baseURL = "https://sandbox.api.movmint.com/v1"

func main() {
	req, err := http.NewRequest(http.MethodGet, baseURL+"/client/balance", nil)
	if err != nil {
		log.Fatalf("creating request: %v", err)
	}
	req.Header.Set("Authorization", "Bearer <your-token>")

	// Optionally filter by asset
	q := req.URL.Query()
	q.Add("asset", "USDC")
	req.URL.RawQuery = q.Encode()

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatalf("sending request: %v", err)
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatalf("reading response: %v", err)
	}

	if resp.StatusCode != http.StatusOK {
		log.Fatalf("unexpected status %d: %s", resp.StatusCode, body)
	}

	fmt.Println(string(body))
}
```

#### TypeScript

```typescript
const BASE_URL = "https://sandbox.api.movmint.com/v1";

async function getClientBalance(asset?: string): Promise<void> {
  const url = new URL(`${BASE_URL}/client/balance`);
  if (asset) {
    url.searchParams.set("asset", asset);
  }

  const response = await fetch(url.toString(), {
    method: "GET",
    headers: {
      Authorization: "Bearer <your-token>",
    },
  });

  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }

  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));
}

getClientBalance("USDC");
```

#### Java

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class GetBalanceExample {

    private static final String BASE_URL = "https://sandbox.api.movmint.com/v1";

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        // Optionally append ?asset=USDC to filter by asset
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/client/balance?asset=USDC"))
                .header("Authorization", "Bearer <your-token>")
                .GET()
                .build();

        HttpResponse<String> response = client.send(
                request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            System.err.printf("Unexpected status %d: %s%n",
                    response.statusCode(), response.body());
            System.exit(1);
        }

        System.out.println(response.body());
    }
}
```

#### Rust

```rust
use reqwest::header::AUTHORIZATION;

const BASE_URL: &str = "https://sandbox.api.movmint.com/v1";

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let response = client
        .get(format!("{BASE_URL}/client/balance"))
        .query(&[("asset", "USDC")])
        .header(AUTHORIZATION, "Bearer <your-token>")
        .send()
        .await?;

    if !response.status().is_success() {
        let status = response.status();
        let text = response.text().await?;
        eprintln!("Unexpected status {status}: {text}");
        std::process::exit(1);
    }

    let data: serde_json::Value = response.json().await?;
    println!("{}", serde_json::to_string_pretty(&data)?);

    Ok(())
}
```

### Example Response

A successful `GET /client/balance` returns HTTP `200` with a list of balance accounts:

```json
{
  "data": [
    {
      "client_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization_id": "org-uuid-here",
      "asset": "USDC",
      "ledger_account": "cl_acmecorp_funds_USDC",
      "available_balance": 10000,
      "pending_balance": 500,
      "total_balance": 10500,
      "created_at": "2025-01-10T09:00:00Z",
      "updated_at": "2025-06-15T12:05:00Z"
    }
  ]
}
```

### Response Fields

#### ClientBalanceList

| Field  | Description                       |
| ------ | --------------------------------- |
| `data` | Array of `ClientBalance` objects. |

#### ClientBalance

| Field               | Description                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| `client_account_id` | Unique identifier for this balance account. Use this as the path parameter for the transactions endpoint. |
| `organization_id`   | Your organization's UUID.                                                                                 |
| `asset`             | The asset this account holds (e.g. `USDC`).                                                               |
| `ledger_account`    | The internal ledger account name (`cl_{CLIENTNAME}_funds_{ASSET}`).                                       |
| `available_balance` | Funds immediately usable as `source_type=CLIENT_BALANCE` in a Quote/Capture request.                      |
| `pending_balance`   | Deposits detected on-chain but not yet fully settled or compliance-cleared.                               |
| `total_balance`     | Sum of `available_balance` and `pending_balance`.                                                         |
| `created_at`        | Timestamp when the account was created.                                                                   |
| `updated_at`        | Timestamp of the most recent balance change.                                                              |

### Error Responses

| HTTP Status | Cause                                                                     |
| ----------- | ------------------------------------------------------------------------- |
| `500`       | An internal error occurred. Retry the request or contact Movmint support. |

### Next Steps

* **[Funding Your Client Balance](./client-account-1.md)** — Add funds to your balance by requesting a deposit address.
* **[Viewing Transactions](./client-account-3.md)** — Review the detailed transaction history for a specific balance account.