Balance API

GET /v1/balance returns the signed-in account balance plus optional low-balance alert configuration. Use it for dashboards, billing widgets, and automated spend guards.

Authentication: Required — send your API key as a Bearer token.

Endpoint

GET https://api.lunos.tech/v1/balance

Headers

Header	Type	Required	Description
Authorization	string	Yes	`Bearer YOUR_SECRET_KEY`

Example

curl -X GET "https://api.lunos.tech/v1/balance" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"

Success response

{
  "success": true,
  "message": "Balance retrieved successfully",
  "data": {
    "balance": 10.5,
    "email": "user@example.com",
    "alertBalance": 1.0,
    "enableAlert": 1,
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "isAlertEnabled": true,
    "isBalanceLow": false
  }
}

Fields

Field	Type	Description
success	boolean	Whether the call succeeded
message	string	Human-readable status
data.balance	number	Current balance
data.email	string	Account email
data.alertBalance	number	Threshold for alerts
data.enableAlert	number	Legacy flag (1 enabled, 0 disabled)
data.updatedAt	string	ISO timestamp
data.isAlertEnabled	boolean	Derived alert toggle
data.isBalanceLow	boolean	Below threshold flag

Error examples

401 — missing or invalid key

{
  "success": false,
  "message": "Missing or invalid secret key",
  "error": "UNAUTHORIZED"
}

401 — expired key

{
  "success": false,
  "message": "Secret key expired",
  "error": "UNAUTHORIZED"
}

500

{
  "success": false,
  "message": "Internal server error",
  "error": "INTERNAL_ERROR"
}

Code samples

JavaScript

const response = await fetch("https://api.lunos.tech/v1/balance", {
  method: "GET",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
});
const data = await response.json();
console.log("Current balance:", data.data.balance);

Python

import requests

r = requests.get(
    "https://api.lunos.tech/v1/balance",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
data = r.json()
print(f"Current balance: {data['data']['balance']}")

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.lunos.tech/v1/balance');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_SECRET_KEY',
    'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo "Current balance: " . $data['data']['balance'];

Note: If no wallet row exists yet, the API may initialize one with zero balance.