Back to the reference

Balance

Informed USDT balance and its statement.

The balance is an informed amount from collections and payouts recorded in Clobepay; it does not represent custody of funds. Credited collections that have not settled appear as pending settlement and do not add to the available amount.

GET

Retrieve the balance

/api/v1/balance

Available and pending settlement, in USDT.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Responses

  • HTTP 200Informed balance.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
GET/balance
curl -X GET "$CLOBEPAY_API_BASE/balance" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
{
  "sellerId": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
  "asset": "USDT",
  "available": "1250.00",
  "held": "0.00",
  "heldCount": 0,
  "pendingSettlement": "50.00",
  "pendingSettlementCount": 1,
  "informational": true,
  "custody": false,
  "asOf": "2026-11-19T18:00:00.000Z",
  "note": "Saldo informado; no representa custodia de fondos."
}

GET

Balance statement

/api/v1/balance/statement

Movements of the informed balance, in USDT.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

period
query
stringOptional

today, 7d, 30d or month. For a custom range use from and to.

today · 7d · 30d · month

from
query
stringOptional

YYYY-MM-DD (UTC), together with to.

to
query
stringOptional

YYYY-MM-DD (UTC), together with from.

Responses

  • HTTP 200Statement in camelCase (openingBalance, closingBalance, inflows, outflows).

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 400invalid_periodInvalid period, from or to.
GET/balance/statement
curl -X GET "$CLOBEPAY_API_BASE/balance/statement?period=7d" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
{
  "sellerId": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
  "asset": "USDT",
  "period": "7d",
  "from": "2026-11-12",
  "to": "2026-11-19",
  "openingBalance": "1000.00",
  "inflows": "300.00",
  "outflows": "50.00",
  "closingBalance": "1250.00",
  "balanced": true
}