> ## Documentation Index
> Fetch the complete documentation index at: https://mintfax.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# balance.topup

> Sent when funds are added to an environment.

<Warning>
  This event is part of the published catalog but is not yet emitted by mintfax. The schema on this page is the target so you can build against it now. Subscribing to `balance.topup` today will not return an error, but no deliveries will arrive until the producer ships.
</Warning>

## When it will fire

When credit is added to an environment, whether the addition is manual (someone clicked Top Up in the dashboard or an admin called the API) or automatic (auto-top-up triggered against the low-balance threshold).

One event fires per credit addition. A single top-up that brings the balance well above the threshold produces one event, not several.

## What your handler should do

* Update any internal accounting that tracks mintfax credits.
* For auto-top-up flows, this is the confirmation that the charge succeeded against your billing source and credit was added.
* For manual top-ups, this is mainly a notification - useful for audit and for finance dashboards that want to reconcile mintfax balance against expected spend.


## OpenAPI

````yaml openapi.json webhook balance.topup
openapi: 3.1.0
info:
  title: mintfax API
  version: '1.0'
  description: >-
    Developer-first fax API. Send faxes with a single API call.


    ## Authentication


    Most endpoints require a Bearer token in the `Authorization` header.


    - **Account keys** (`mfx_acct_...`) access account-level endpoints
    (`/account`, `/account/balance`, `/account/transactions`, `/account/keys`).

    - **Environment keys** (`mfx_test_...` for test, `mfx_live_...` for live)
    access operational endpoints (`/environment`, `/faxes`, `/webhooks`,
    `/events`).

    - Registration endpoints (`POST /account/register` and `POST
    /account/register/verify`) do not require authentication.


    ## Base URL


    All API requests use `https://api.mintfax.com/v1` as the base URL.
  contact:
    name: mintfax Support
    email: support@mintfax.com
    url: https://mintfax.com/docs
servers:
  - url: https://api.mintfax.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: >-
      Account-level resources: registration, account info, balances, and API
      keys.
  - name: Environment
    description: >-
      Test and live environment configuration shared across all operational
      requests.
  - name: Fax
    description: Send, list, retrieve, resend, and purge faxes.
  - name: Events
    description: >-
      Read the immutable event log for everything that has happened in the
      environment.
  - name: Webhooks
    description: >-
      Manage webhook endpoints and inspect or replay individual delivery
      attempts.
paths: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      description: |-
        API key as Bearer token. Use an account key (`mfx_acct_...`) for
        `/account/*` endpoints, and an environment key (`mfx_test_...` for
        sandbox, `mfx_live_...` for live) for `/environment/*`, `/faxes`,
        `/webhooks`, and `/events`.
      scheme: bearer

````