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

ParameterTypeRequiredDescription
assetstringNoIf provided, returns balances only for the specified asset (e.g. USDC). Otherwise, all asset balances are returned.

Code Examples

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

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

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

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:

{
  "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

FieldDescription
dataArray of ClientBalance objects.

ClientBalance

FieldDescription
client_account_idUnique identifier for this balance account. Use this as the path parameter for the transactions endpoint.
organization_idYour organization's UUID.
assetThe asset this account holds (e.g. USDC).
ledger_accountThe internal ledger account name (cl_{CLIENTNAME}_funds_{ASSET}).
available_balanceFunds immediately usable as source_type=CLIENT_BALANCE in a Quote/Capture request.
pending_balanceDeposits detected on-chain but not yet fully settled or compliance-cleared.
total_balanceSum of available_balance and pending_balance.
created_atTimestamp when the account was created.
updated_atTimestamp of the most recent balance change.

Error Responses

HTTP StatusCause
500An internal error occurred. Retry the request or contact Movmint support.

Next Steps