---
updatedAt: 2026-06-24T15:11:37.000Z
---

Fetch the complete documentation index at: https://docs.movmint.io/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Getting Balances

Retrieve current available, pending, and total balances for one or all of your Client Balance accounts with GET /client/balance.

## Overview

`GET /client/balance` returns the current balance(s) for your organization. Without a filter it returns every asset you hold; pass `asset` to return a single account.

```
GET https://api.sandbox.movmint.io/client/balance
Authorization: Bearer <access_token>
x-idempotency-key: <uuid>
```

| Parameter           | In     | Required | Description                                                                                        |
| ------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `asset`             | query  | no       | If provided, returns only the balance for that asset (e.g., `USDC`). Otherwise returns all assets. |
| `x-idempotency-key` | header | yes      | A UUID you generate.                                                                               |

## Code examples

### cURL

```bash
# All balances
curl https://api.sandbox.movmint.io/client/balance \
  -H "Authorization: Bearer <access_token>" \
  -H "x-idempotency-key: $(uuidgen)"

# A single asset
curl "https://api.sandbox.movmint.io/client/balance?asset=USDC" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-idempotency-key: $(uuidgen)"
```

### Go

```go
package main

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

	"github.com/google/uuid"
)

const baseURL = "https://api.sandbox.movmint.io"

func main() {
	token := "<access_token>"

	req, _ := http.NewRequest(http.MethodGet, baseURL+"/client/balance?asset=USDC", nil)
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("x-idempotency-key", uuid.NewString())

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("get balance failed (%d): %s", resp.StatusCode, body)
	}
	fmt.Println(string(body))
}
```

### TypeScript

```typescript
import { randomUUID } from "crypto";

const BASE_URL = "https://api.sandbox.movmint.io";

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

  const res = await fetch(url, {
    headers: {
      Authorization: `Bearer ${token}`,
      "x-idempotency-key": randomUUID(),
    },
  });

  if (!res.ok) {
    throw new Error(`Get balance failed (${res.status}): ${await res.text()}`);
  }
  return res.json();
}

console.log(await getBalances("<access_token>", "USDC"));
```

### Java

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

public class GetBalance {

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

    public static void main(String[] args) throws Exception {
        String token = "<access_token>";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/client/balance?asset=USDC"))
                .header("Authorization", "Bearer " + token)
                .header("x-idempotency-key", UUID.randomUUID().toString())
                .GET()
                .build();

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

        if (response.statusCode() != 200) {
            throw new RuntimeException("Get balance failed (" + response.statusCode()
                    + "): " + response.body());
        }
        System.out.println(response.body());
    }
}
```

### Rust

```rust
use uuid::Uuid;

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = "<access_token>";

    let client = reqwest::Client::new();
    let resp = client
        .get(format!("{BASE_URL}/client/balance"))
        .query(&[("asset", "USDC")])
        .bearer_auth(token)
        .header("x-idempotency-key", Uuid::new_v4().to_string())
        .send()
        .await?;

    if !resp.status().is_success() {
        let status = resp.status();
        return Err(format!("get balance failed ({status}): {}", resp.text().await?).into());
    }

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

### Python

```python
import uuid
import requests

BASE_URL = "https://api.sandbox.movmint.io"


def get_balances(token: str, asset: str | None = None) -> dict:
    params = {"asset": asset} if asset else {}
    resp = requests.get(
        f"{BASE_URL}/client/balance",
        headers={
            "Authorization": f"Bearer {token}",
            "x-idempotency-key": str(uuid.uuid4()),
        },
        params=params,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()


print(get_balances("<access_token>", "USDC"))
```

## Example response (`200`)

```json
{
  "data": [
    {
      "client_account_id": "9f1c2d3e-4b5a-6789-abcd-ef0123456789",
      "organization_id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
      "asset": "USDC",
      "ledger_account": "cl_acmecorp_funds_USDC",
      "available_balance": 10000.00,
      "pending_balance": 500.00,
      "total_balance": 10500.00,
      "created_at": "2026-06-01T09:00:00Z",
      "updated_at": "2026-06-24T12:04:55Z"
    }
  ]
}
```

The response is a list (`data`) of balance objects. Each carries `available_balance`, `pending_balance`, and `total_balance`. Only `available_balance` is usable as a `CLIENT_BALANCE` source on a Quote/Capture. If you hold no balances, `data` is an empty array.

## Error responses

| HTTP  | Cause                                       |
| ----- | ------------------------------------------- |
| `500` | Internal server error — retry with backoff. |

## Next steps

To see how a balance changed over time — funding deposits, capture debits, and capture credits — use **[Get Transactions](./get-transactions.md)**.