getBusinessAccountStarBalance

Returns: StarAmountOfficial docs ↗

Returns the amount of Telegram Stars owned by a managed business account. Requires the can_view_gifts_and_stars business bot right. Returns StarAmount on success.

Parameters

business_connection_idStringRequired

Unique identifier of the business connection

Returns

On success, the StarAmount object is returned.

GramIO Usage

// Get the Star balance of a managed business account
const balance = await bot.api.getBusinessAccountStarBalance({
  business_connection_id: "bc_123",
});

console.log(`Star balance: ${balance.amount} ⭐`);

// nanostar_amount holds fractional stars (0–999_999_999)
if (balance.nanostar_amount) {
  console.log(`+ ${balance.nanostar_amount} nanostars`);
}

// Guard: check if the account has enough Stars before a transfer
async function hasEnoughStars(connectionId: string, required: number) {
  const balance = await bot.api.getBusinessAccountStarBalance({
    business_connection_id: connectionId,
  });
  return balance.amount >= required;
}

const canAfford = await hasEnoughStars("bc_123", 50);
console.log(`Can afford 50 Stars: ${canAfford}`);

// Log balance whenever a business connection is established
bot.on("business_connection", async (ctx) => {
  if (!ctx.isEnabled) return;

  const balance = await bot.api.getBusinessAccountStarBalance({
    business_connection_id: ctx.id,
  });

  console.log(
    `Connected account ${ctx.user.id} has ${balance.amount} Stars`
  );
});

Errors

Code	Error	Cause
400	Bad Request: business connection not found	The business_connection_id is invalid or the connection was revoked — re-verify with getBusinessConnection
400	Bad Request: not enough rights	The bot lacks the can_view_gifts_and_stars business bot right — check connection.rights before calling
429	Too Many Requests: retry after N	Rate limit hit — check retry_after, use auto-retry plugin

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

• Requires can_view_gifts_and_stars right. This is granted by the business account owner during setup — verify it from connection.rights?.can_view_gifts_and_stars before calling to avoid needless errors.
• StarAmount has two parts. amount is the integer Star balance. nanostar_amount (0–999,999,999) represents fractional precision — usually 0 in practice, but handle it if you display totals mathematically.
• The balance is a point-in-time snapshot. Re-fetch just before any Stars transfer operation rather than relying on a cached value — the balance can change between calls.
• This endpoint is read-only. You can't add or deduct Stars through this method. To transfer Stars, use the appropriate transfer endpoint.

See Also

• getBusinessConnection — verify the connection and check can_view_gifts_and_stars right
• getBusinessAccountGifts — get gifts owned by the same business account
• getMyStarBalance — get the bot's own Star balance
• StarAmount — the return type with amount and nanostar_amount fields
• BusinessConnection — the business connection object with rights info
• BusinessBotRights — business bot rights including can_view_gifts_and_stars