Skip to main content
GET
/
v1
/
merchant
/
balance
Get Balances
curl --request GET \
  --url https://api.example.com/v1/merchant/balance \
  --header 'X-API-Key: <x-api-key>'
{
  "success": true,
  "data": {
    "merchantId": "<string>",
    "businessName": "<string>",
    "balances": {
      "BTC": {
        "availableBalance": 123,
        "totalEarned": 123,
        "totalWithdrawn": 123,
        "pendingBalance": 123,
        "limits": {
          "daily": {
            "limit": 123,
            "used": 123,
            "remaining": 123
          },
          "monthly": {}
        }
      },
      "ETH": {},
      "LTC": {},
      "USDT_ERC20": {},
      "USDT_BEP20": {}
    }
  },
  "message": "<string>",
  "statusCode": 123
}

​
Overview

This endpoint retrieves your account balances across all supported cryptocurrencies, including available balance, total earned, total withdrawn, and withdrawal limits. Use this endpoint to check your available funds before creating a withdrawal.

​
Authentication

​
X-API-Key
string
required
Your InventPay API key Example: cmfnz7jei0005p54eekx4e6mb

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Balance information object
​
message
string
Success message Example: "Balances retrieved successfully"
​
statusCode
number
HTTP status code Example: 200

​
Example Request

curl -X GET https://api.inventpay.io/v1/merchant/balance \
  -H "X-API-Key: YOUR_API_KEY"

​
Example Response

200 - Success
{
  "success": true,
  "data": {
    "merchantId": "cmf123abc456def",
    "businessName": "Your Business Name",
    "balances": {
      "BTC": {
        "availableBalance": 0.5,
        "totalEarned": 1.2,
        "totalWithdrawn": 0.7,
        "pendingBalance": 0.1,
        "limits": {
          "daily": {
            "limit": 10,
            "used": 0.5,
            "remaining": 9.5
          },
          "monthly": {
            "limit": 100,
            "used": 5.2,
            "remaining": 94.8
          }
        }
      },
      "ETH": {
        "availableBalance": 2.1,
        "totalEarned": 5.6,
        "totalWithdrawn": 3.5,
        "pendingBalance": 0.3,
        "limits": {
          "daily": {
            "limit": 50,
            "used": 2.1,
            "remaining": 47.9
          },
          "monthly": {
            "limit": 500,
            "used": 25.5,
            "remaining": 474.5
          }
        }
      },
      "USDT_BEP20": {
        "availableBalance": 1500.75,
        "totalEarned": 5000,
        "totalWithdrawn": 3499.25,
        "pendingBalance": 250.5,
        "limits": {
          "daily": {
            "limit": 10000,
            "used": 1500,
            "remaining": 8500
          },
          "monthly": {
            "limit": 100000,
            "used": 15000,
            "remaining": 85000
          }
        }
      }
    }
  },
  "message": "Balances retrieved successfully",
  "statusCode": 200
}
401 - Unauthorized
{
  "success": false,
  "error": "Invalid API key",
  "statusCode": 401
}

​
Understanding Balance Fields

FieldDescription
availableBalanceFunds available for immediate withdrawal
totalEarnedLifetime total of all payments received
totalWithdrawnLifetime total of all withdrawals made
pendingBalancePayments received but still awaiting confirmations
Only availableBalance can be withdrawn. Funds in pendingBalance will move to availableBalance once they receive the required confirmations.

​
Withdrawal Limits

Withdrawal limits are in place to ensure security:
  • Daily Limit: Resets every 24 hours
  • Monthly Limit: Resets on the 1st of each month
  • Custom Limits: Contact support to request higher limits
Attempting to withdraw more than your available limit will result in a validation error.

​
Error Codes

Status CodeDescription
200Balances retrieved successfully
401Invalid or missing API key
429Rate limit exceeded
500Internal server error