Read your balance and holds

Find out how much you can withdraw right now in each currency, what is awaiting bank confirmation, how automatic settlement works, and how to reconcile your books with the movements list.

What you will do

Each currency (bolívares, USDT, USDC, pesos) has its own balance. Live bolívar payments wait for the bank to confirm them, then become available on their own — no action needed and no webhook when it happens. USDT and pesos are available at once. Only available money can be withdrawn, and in live mode available bolívares are settled to your verified payout account automatically every 15 minutes.

Steps

Read the bolívar balance
GET /v1/balance. availableVes is what you can withdraw now; unconfirmedVes is waiting for the bank; heldVes and nextReleaseAt apply only if your account has a hold; reserveVes is a buffer VEXPay may set for your account; settlement says whether automatic settlement is on.
Read stablecoins and pesos
GET /v1/crypto/balances (or GET /v1/crypto/balance?currency=USDC) returns available, held, nextReleaseAt and pendingPayout per coin. GET /v1/cop/balance returns availableCop, heldCop, nextReleaseAt and pendingPayoutCop.
Marketplaces: read seller balances
GET /v1/merchants/:id/balance returns the seller's pendingVes and availableVes (plus a cop block when they have peso activity). Platform totals are on GET /v1/balance.
Reconcile bolívares
Page through GET /v1/balance/transactions (limit up to 100, cursor from nextCursor). Each movement has a stable id, a signed amountVes, and availableAt while it is held. Automatic settlements are payouts with an externalRef starting with auto_settle_. Filter by type, paymentId, payoutId, from and to.

Balancesbash

curl "${API_URL}/v1/balance" --header "x-api-key: ${VEXPAY_API_KEY}"
curl "${API_URL}/v1/crypto/balances" --header "x-api-key: ${VEXPAY_API_KEY}"
curl "${API_URL}/v1/cop/balance" --header "x-api-key: ${VEXPAY_API_KEY}"

Movementsbash

curl "${API_URL}/v1/balance/transactions?limit=100&from=2026-11-01T00:00:00Z" \
  --header "x-api-key: ${VEXPAY_API_KEY}"
# Repeat with &cursor=<nextCursor> until nextCursor is null.

Check that it worked

Your books match when, over all pages, the sum of amountVes equals ledgerNetVes, and ledgerNetVes − reserveVes − heldVes − unconfirmedVes equals availableVes. The portal shows the same figures in Overview, Payouts, Balance movements, USDT and COP.

If something goes wrong

Symptom	Likely cause	What to do
Money shows but cannot be withdrawn	The bank has not confirmed the payment yet (`unconfirmedVes`)	Withdraw the available part now; the rest follows once the bank confirms it.
Automatic settlement does not run	No verified payout account, the amount is below the minimum, or it is off for your account	Read `settlement.status` on `GET /v1/balance`.
`availableVes` is negative	A card chargeback was larger than your available balance	New payments refill it; payouts and conversions wait until then.
Your books do not match	A movement was missed (chargeback, reversal, adjustment)	Page through the movements and match each by `id`.
403 `method_not_allowed` on USDC or COP balance	That currency is not enabled for you	Ask VEXPay.