Jump to Content

Getting Transactions

Retrieve the transaction history for a Client Balance account — funding deposits, capture debits, and capture credits — with pagination and filtering, via GET /client/balance/{client_account_id}/transactions.

Overview

GET /client/balance/{client_account_id}/transactions returns the ledger activity for a single Client Balance account: funding deposits, debits from captures that used the balance as source, and credits from captures that used it as target. Results are paginated with an opaque cursor.

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

Parameter	In	Required	Description
`client_account_id`	path	yes	The balance account to query (from funding or Get Balances).
`type`	query	no	Filter by type: `FUNDING`, `CAPTURE_DEBIT`, `CAPTURE_CREDIT`, or `ADJUSTMENT`.
`from`	query	no	Return transactions created at or after this `date-time` (inclusive).
`to`	query	no	Return transactions created at or before this `date-time` (inclusive).
`limit`	query	no	Page size, 1–200 (default 50).
`cursor`	query	no	Opaque cursor from a previous response's `next_cursor`.
`x-idempotency-key`	header	yes	A UUID you generate.

Transaction types

Type	Direction	Meaning
`FUNDING`	CREDIT	A settled funding deposit.
`CAPTURE_DEBIT`	DEBIT	Debit from a Quote/Capture that used this account as `source_type=CLIENT_BALANCE`.
`CAPTURE_CREDIT`	CREDIT	Credit from a Quote/Capture that used this account as `target_type=CLIENT_BALANCE`.
`ADJUSTMENT`	CREDIT/DEBIT	Manual adjustment posted by Movmint operations.

Code examples

cURL

curl "https://api.sandbox.movmint.io/client/balance/9f1c2d3e-4b5a-6789-abcd-ef0123456789/transactions?type=FUNDING&limit=50" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-idempotency-key: $(uuidgen)"

Go

package main

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

	"github.com/google/uuid"
)

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

func main() {
	token := "<access_token>"
	accountID := "9f1c2d3e-4b5a-6789-abcd-ef0123456789"

	q := url.Values{}
	q.Set("type", "FUNDING")
	q.Set("limit", "50")

	endpoint := fmt.Sprintf("%s/client/balance/%s/transactions?%s", baseURL, accountID, q.Encode())
	req, _ := http.NewRequest(http.MethodGet, endpoint, 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 transactions failed (%d): %s", resp.StatusCode, body)
	}
	fmt.Println(string(body))
}

TypeScript

import { randomUUID } from "crypto";

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

async function getTransactions(token: string, accountId: string) {
  const url = new URL(`${BASE_URL}/client/balance/${accountId}/transactions`);
  url.searchParams.set("type", "FUNDING");
  url.searchParams.set("limit", "50");

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

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

console.log(await getTransactions("<access_token>", "9f1c2d3e-4b5a-6789-abcd-ef0123456789"));

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

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

    public static void main(String[] args) throws Exception {
        String token = "<access_token>";
        String accountId = "9f1c2d3e-4b5a-6789-abcd-ef0123456789";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/client/balance/" + accountId
                        + "/transactions?type=FUNDING&limit=50"))
                .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 transactions failed (" + response.statusCode()
                    + "): " + response.body());
        }
        System.out.println(response.body());
    }
}

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 account_id = "9f1c2d3e-4b5a-6789-abcd-ef0123456789";

    let client = reqwest::Client::new();
    let resp = client
        .get(format!("{BASE_URL}/client/balance/{account_id}/transactions"))
        .query(&[("type", "FUNDING"), ("limit", "50")])
        .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 transactions failed ({status}): {}", resp.text().await?).into());
    }

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

Python

import uuid
import requests

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


def get_transactions(token: str, account_id: str, **filters) -> dict:
    resp = requests.get(
        f"{BASE_URL}/client/balance/{account_id}/transactions",
        headers={
            "Authorization": f"Bearer {token}",
            "x-idempotency-key": str(uuid.uuid4()),
        },
        params={"type": "FUNDING", "limit": 50, **filters},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()


print(get_transactions("<access_token>", "9f1c2d3e-4b5a-6789-abcd-ef0123456789"))

Example response (`200`)

{
  "data": [
    {
      "transaction_id": "7c9e6a4b-2f10-4d3c-8a1b-0e2f3a4b5c6d",
      "client_account_id": "9f1c2d3e-4b5a-6789-abcd-ef0123456789",
      "type": "FUNDING",
      "direction": "CREDIT",
      "asset": "USDC",
      "amount": 1000.00,
      "balance_after": 10000.00,
      "related_deposit_tx_id": "0xdeadbeef...",
      "related_quote_id": null,
      "related_transaction_id": null,
      "created_at": "2026-06-20T15:32:00Z"
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}

Field	Description
`type` / `direction`	The transaction type and whether it credited or debited the account.
`amount`	Absolute amount in `asset`.
`balance_after`	`available_balance` after this transaction posted.
`related_quote_id` / `related_transaction_id`	Set for `CAPTURE_DEBIT` / `CAPTURE_CREDIT`, linking back to the Quote/Capture.
`related_deposit_tx_id`	Set for `FUNDING`, the on-chain deposit transaction.
`next_cursor`	Pass as `cursor` to fetch the next page. `null` when there are no more results.

Pagination

Request a page, then keep passing next_cursor until it is null:

def all_transactions(token, account_id):
    cursor = None
    while True:
        page = get_transactions(token, account_id, cursor=cursor) if cursor \
            else get_transactions(token, account_id)
        yield from page["data"]
        cursor = page.get("next_cursor")
        if not cursor:
            break

Error responses

HTTP	Cause
`404`	The account does not exist or is not owned by your organization.
`500`	Internal server error — retry with backoff.

Updated 2 months ago

Did this page help you?