GET
/
user
/
wallet-balance
curl --request GET \
  --url https://api.magebank.ai/user/wallet-balance \
  --header 'x-api-key: <x-api-key>'
{
  "success": true,
  "balance": "100.50",
  "asset": "USDC"
}

Retrieves the user’s wallet balance from the blockchain using their wallet address. The endpoint follows a fallback strategy, first attempting to fetch USDC balance, then ETH, and finally any other non-zero balance.

​
Request Headers

​
x-api-key
string
required

Your API key for authentication

​
Response

​
success
boolean

Whether the balance retrieval was successful

​
balance
string

Current wallet balance formatted as a string to preserve precision

​
asset
string

Asset type (USDC, ETH, or other cryptocurrency)

​
message
string

Additional information about the balance retrieval (appears when balance fetching methods fail)

{
  "success": true,
  "balance": "100.50",
  "asset": "USDC"
}

​
Status Codes

Status CodeDescription
200Wallet balance retrieved successfully
400Bad Request - Invalid wallet address format
401Unauthorized - Invalid or missing API key
500Unexpected error

​
Notes

  • Requires authentication with a valid API key.
  • The endpoint uses a fallback strategy: first checks USDC, then ETH, and finally any other non-zero balance.
  • Balance is returned as a string to preserve precision for financial calculations.
  • If all balance fetching methods fail, the API will return a successful response with a zero balance and an explanatory message.