# Billing (/reference/billing)

## Your plan and operational balance

`GET /v1/billing`

Every fee on the rate card is drawn from a prepaid OPERATIONAL BALANCE in USD cents. You fund it by sending USDT or USDC (credited at par) or a chain's native coin (credited at spot) to one of your funding addresses (`GET /v1/billing/funding`).

`live.ok` says whether live invoices are accepted right now; `activation` says how much more the balance needs before the plan you chose switches on. The balance stays yours: it is refundable on request.

### Responses

- `200` — Plan and balance.
  - `object` (required, string)
  - `plan` (required, string, one of: drift, current, jetstream, stratos)
  - `plan_name` (required, string)
  - `plan_status` (required, string, one of: pending, active) — `pending` = chosen but not yet funded to the plan's operational balance.
  - `plan_activated_at` (optional, string | null (date-time))
  - `requested_plan` (optional, string | null) — A plan waiting on funding, if any. The stable identifier — match on this.
  - `requested_plan_name` (required, string | null) — That plan's display name, as the pricing page shows it. Print this; the key and the name are allowed to differ.
  - `balance_cents` (required, string) — Prepaid operational balance, USD cents, signed. At or below zero, live invoices are refused.
  - `onboarding_paid_cents` (optional, string)
  - `live` (required, object)
    - `ok` (required, boolean)
    - `reason` (optional, string | null, one of: plan_not_active, billing_balance_exhausted, null)
  - `low_balance` (required, object) — The low-balance alert: `billing.balance_low` fires once when the balance falls under `line_cents`, `billing.balance_exhausted` once when it reaches zero; a top-up over the line re-arms both. Set your own line with `PUT /v1/billing/low_balance`.
    - `line_cents` (required, string) — The line in force, USD cents.
    - `source` (required, string, one of: custom, automatic)
    - `automatic_cents` (required, string) — About 7 days of your recent fees, never under $20.
    - `alerted_at` (required, string | null (date-time)) — When the balance went under the line, while it still is.
    - `exhausted_at` (required, string | null (date-time)) — When it ran out, while it still is.
  - `auto_topup` (required, object) — Auto top-up: when the balance reaches zero it is refilled back to the alert line from your `source` wallet first, the other second — only coins that are free (not promised to a conversion, refund or withdrawal) and that can be priced. On by default. Each refill is a `funding` line (`ref_type: auto_topup`) and a `billing.auto_topup` event. Change it with `PUT /v1/billing/auto_topup`.
    - `enabled` (required, boolean)
    - `source` (required, string, one of: service, own) — Drawn first; the other wallet is the fallback.
    - `last_attempt_at` (required, string | null (date-time)) — The last refill attempt, successful or not. One with nothing to draw is retried hourly.
  - `onboarding` (required, object) — The getting-started checklist. It is guidance, not a gate — `live.ok` above is the only thing that decides whether invoices are accepted.
    - `steps` (required, array) — 🔴 ONLY `plan` IS RESOLVED FROM A FACT ON THIS ROUTE. The other three are reported `done: false` unless bypassed, because deciding them means counting addresses, deposits and invoices — reads a console makes anyway, and three joins we will not run to draw a tick. Derive them yourself and treat `bypassed` as the override.
      - `step` (required, string, one of: plan, address, payment, live)
      - `done` (required, boolean) — The underlying fact holds.
      - `bypassed` (required, boolean) — MolnPay support marked it satisfied instead.
      - `complete` (required, boolean) — `done || bypassed` — what to render.
    - `bypassed` (required, array, of string, one of: address, payment, live) — Steps MolnPay support ticked off for this account.
    - `skipped_at` (required, string | null (date-time)) — When the checklist was dismissed. Null while it still shows.
    - `can_skip` (required, boolean) — Whether it may be dismissed yet — the plan has to be active first.
    - `remaining` (required, integer) — Steps still outstanding once overrides are applied.
  - `activation` (optional, object | null) — What the balance needs before the pending/requested plan activates. Null when nothing is pending.
    - `plan` (required, string)
    - `plan_name` (required, string) — The display name of the plan waiting to activate.
    - `onboarding_due_cents` (required, string)
    - `balance_required_cents` (required, string)
    - `shortfall_cents` (required, string) — Send at least this much (in USD terms) to activate.
  - `fees` (required, object) — What a new invoice is charged today: your plan, with any negotiated override.
    - `rate_bps` (optional, integer)
    - `fixed_cents` (optional, string)
    - `cap_cents` (optional, string | null)
    - `address_fee_cents` (optional, string)
    - `min_monthly_cents` (optional, string)
    - `history_days` (optional, integer | null) — How far back your lists reach, in days. `null` = no window. A staff override, if any, is folded in.
    - `chains_included` (optional, integer | null) — Chains included in your plan; `null` = every chain.
    - `extra_chain_cents` (optional, string | null) — Monthly price of a chain beyond the included count; `null` = none can be added.
    - `webhooks` (optional, boolean) — Signed webhooks are included (otherwise poll `GET /v1/changes`).
    - `auto_conversion` (optional, boolean) — Settling payments to one coin is included.
    - `statements` (optional, boolean) — Monthly statements and CSV exports are included.
  - `plans` (required, array) — The rate card, for a plan picker.
    - `key` (optional, string)
    - `name` (optional, string)
    - `onboarding_fee_cents` (optional, string)
    - `min_monthly_cents` (optional, string)
    - `operational_balance_cents` (optional, string)
    - `rate_bps` (optional, integer)
    - `fixed_cents` (optional, string)
    - `cap_cents` (optional, string)
    - `negotiated` (optional, boolean)
  - `billing_account` (optional, object) — WHO PAYS: the billing account this merchant draws on and every merchant drawing on it — one balance, one plan, one set of funding addresses between them. `shared` is false for a merchant created with billing of its own.
    - `id` (required, string (uuid))
    - `shared` (required, boolean)
    - `merchants` (required, array)
      - `id` (required, string (uuid)) — The merchant's public id.
      - `display_name` (required, string)
      - `current` (required, boolean) — The merchant this key or session belongs to.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — `merchant_not_found`.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Choose or change your plan

`POST /v1/billing/plan`

Activates immediately when the balance already covers the plan's onboarding fee (an upgrade pays only the difference) plus its operational balance; otherwise the plan is recorded as requested and activates on the funding credit that closes the gap. Enterprise is agreed with us and cannot be self-selected.

### Request body (required)

- `plan` (required, string, one of: drift, current, jetstream, stratos)

### Responses

- `200` — Plan and balance after the request.
  - `object` (required, string)
  - `plan` (required, string, one of: drift, current, jetstream, stratos)
  - `plan_name` (required, string)
  - `plan_status` (required, string, one of: pending, active) — `pending` = chosen but not yet funded to the plan's operational balance.
  - `plan_activated_at` (optional, string | null (date-time))
  - `requested_plan` (optional, string | null) — A plan waiting on funding, if any. The stable identifier — match on this.
  - `requested_plan_name` (required, string | null) — That plan's display name, as the pricing page shows it. Print this; the key and the name are allowed to differ.
  - `balance_cents` (required, string) — Prepaid operational balance, USD cents, signed. At or below zero, live invoices are refused.
  - `onboarding_paid_cents` (optional, string)
  - `live` (required, object)
    - `ok` (required, boolean)
    - `reason` (optional, string | null, one of: plan_not_active, billing_balance_exhausted, null)
  - `low_balance` (required, object) — The low-balance alert: `billing.balance_low` fires once when the balance falls under `line_cents`, `billing.balance_exhausted` once when it reaches zero; a top-up over the line re-arms both. Set your own line with `PUT /v1/billing/low_balance`.
    - `line_cents` (required, string) — The line in force, USD cents.
    - `source` (required, string, one of: custom, automatic)
    - `automatic_cents` (required, string) — About 7 days of your recent fees, never under $20.
    - `alerted_at` (required, string | null (date-time)) — When the balance went under the line, while it still is.
    - `exhausted_at` (required, string | null (date-time)) — When it ran out, while it still is.
  - `auto_topup` (required, object) — Auto top-up: when the balance reaches zero it is refilled back to the alert line from your `source` wallet first, the other second — only coins that are free (not promised to a conversion, refund or withdrawal) and that can be priced. On by default. Each refill is a `funding` line (`ref_type: auto_topup`) and a `billing.auto_topup` event. Change it with `PUT /v1/billing/auto_topup`.
    - `enabled` (required, boolean)
    - `source` (required, string, one of: service, own) — Drawn first; the other wallet is the fallback.
    - `last_attempt_at` (required, string | null (date-time)) — The last refill attempt, successful or not. One with nothing to draw is retried hourly.
  - `onboarding` (required, object) — The getting-started checklist. It is guidance, not a gate — `live.ok` above is the only thing that decides whether invoices are accepted.
    - `steps` (required, array) — 🔴 ONLY `plan` IS RESOLVED FROM A FACT ON THIS ROUTE. The other three are reported `done: false` unless bypassed, because deciding them means counting addresses, deposits and invoices — reads a console makes anyway, and three joins we will not run to draw a tick. Derive them yourself and treat `bypassed` as the override.
      - `step` (required, string, one of: plan, address, payment, live)
      - `done` (required, boolean) — The underlying fact holds.
      - `bypassed` (required, boolean) — MolnPay support marked it satisfied instead.
      - `complete` (required, boolean) — `done || bypassed` — what to render.
    - `bypassed` (required, array, of string, one of: address, payment, live) — Steps MolnPay support ticked off for this account.
    - `skipped_at` (required, string | null (date-time)) — When the checklist was dismissed. Null while it still shows.
    - `can_skip` (required, boolean) — Whether it may be dismissed yet — the plan has to be active first.
    - `remaining` (required, integer) — Steps still outstanding once overrides are applied.
  - `activation` (optional, object | null) — What the balance needs before the pending/requested plan activates. Null when nothing is pending.
    - `plan` (required, string)
    - `plan_name` (required, string) — The display name of the plan waiting to activate.
    - `onboarding_due_cents` (required, string)
    - `balance_required_cents` (required, string)
    - `shortfall_cents` (required, string) — Send at least this much (in USD terms) to activate.
  - `fees` (required, object) — What a new invoice is charged today: your plan, with any negotiated override.
    - `rate_bps` (optional, integer)
    - `fixed_cents` (optional, string)
    - `cap_cents` (optional, string | null)
    - `address_fee_cents` (optional, string)
    - `min_monthly_cents` (optional, string)
    - `history_days` (optional, integer | null) — How far back your lists reach, in days. `null` = no window. A staff override, if any, is folded in.
    - `chains_included` (optional, integer | null) — Chains included in your plan; `null` = every chain.
    - `extra_chain_cents` (optional, string | null) — Monthly price of a chain beyond the included count; `null` = none can be added.
    - `webhooks` (optional, boolean) — Signed webhooks are included (otherwise poll `GET /v1/changes`).
    - `auto_conversion` (optional, boolean) — Settling payments to one coin is included.
    - `statements` (optional, boolean) — Monthly statements and CSV exports are included.
  - `plans` (required, array) — The rate card, for a plan picker.
    - `key` (optional, string)
    - `name` (optional, string)
    - `onboarding_fee_cents` (optional, string)
    - `min_monthly_cents` (optional, string)
    - `operational_balance_cents` (optional, string)
    - `rate_bps` (optional, integer)
    - `fixed_cents` (optional, string)
    - `cap_cents` (optional, string)
    - `negotiated` (optional, boolean)
  - `billing_account` (optional, object) — WHO PAYS: the billing account this merchant draws on and every merchant drawing on it — one balance, one plan, one set of funding addresses between them. `shared` is false for a merchant created with billing of its own.
    - `id` (required, string (uuid))
    - `shared` (required, boolean)
    - `merchants` (required, array)
      - `id` (required, string (uuid)) — The merchant's public id.
      - `display_name` (required, string)
      - `current` (required, boolean) — The merchant this key or session belongs to.
- `400` — `invalid_plan`.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `422` — `plan_negotiated`.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Set the low-balance alert line

`PUT /v1/billing/low_balance`

Your own line for `billing.balance_low`, in USD cents as a string, or `null` for the automatic one (about 7 days of your recent fees, never under $20). On a shared balance it is the account's line: every merchant sharing it is alerted by the same one. A new line that puts the current balance under it alerts at once.

### Request body (required)

- `line_cents` (required, string | null)

### Responses

- `200` — Plan and balance, with `low_balance` as set.
  - `object` (required, string)
  - `plan` (required, string, one of: drift, current, jetstream, stratos)
  - `plan_name` (required, string)
  - `plan_status` (required, string, one of: pending, active) — `pending` = chosen but not yet funded to the plan's operational balance.
  - `plan_activated_at` (optional, string | null (date-time))
  - `requested_plan` (optional, string | null) — A plan waiting on funding, if any. The stable identifier — match on this.
  - `requested_plan_name` (required, string | null) — That plan's display name, as the pricing page shows it. Print this; the key and the name are allowed to differ.
  - `balance_cents` (required, string) — Prepaid operational balance, USD cents, signed. At or below zero, live invoices are refused.
  - `onboarding_paid_cents` (optional, string)
  - `live` (required, object)
    - `ok` (required, boolean)
    - `reason` (optional, string | null, one of: plan_not_active, billing_balance_exhausted, null)
  - `low_balance` (required, object) — The low-balance alert: `billing.balance_low` fires once when the balance falls under `line_cents`, `billing.balance_exhausted` once when it reaches zero; a top-up over the line re-arms both. Set your own line with `PUT /v1/billing/low_balance`.
    - `line_cents` (required, string) — The line in force, USD cents.
    - `source` (required, string, one of: custom, automatic)
    - `automatic_cents` (required, string) — About 7 days of your recent fees, never under $20.
    - `alerted_at` (required, string | null (date-time)) — When the balance went under the line, while it still is.
    - `exhausted_at` (required, string | null (date-time)) — When it ran out, while it still is.
  - `auto_topup` (required, object) — Auto top-up: when the balance reaches zero it is refilled back to the alert line from your `source` wallet first, the other second — only coins that are free (not promised to a conversion, refund or withdrawal) and that can be priced. On by default. Each refill is a `funding` line (`ref_type: auto_topup`) and a `billing.auto_topup` event. Change it with `PUT /v1/billing/auto_topup`.
    - `enabled` (required, boolean)
    - `source` (required, string, one of: service, own) — Drawn first; the other wallet is the fallback.
    - `last_attempt_at` (required, string | null (date-time)) — The last refill attempt, successful or not. One with nothing to draw is retried hourly.
  - `onboarding` (required, object) — The getting-started checklist. It is guidance, not a gate — `live.ok` above is the only thing that decides whether invoices are accepted.
    - `steps` (required, array) — 🔴 ONLY `plan` IS RESOLVED FROM A FACT ON THIS ROUTE. The other three are reported `done: false` unless bypassed, because deciding them means counting addresses, deposits and invoices — reads a console makes anyway, and three joins we will not run to draw a tick. Derive them yourself and treat `bypassed` as the override.
      - `step` (required, string, one of: plan, address, payment, live)
      - `done` (required, boolean) — The underlying fact holds.
      - `bypassed` (required, boolean) — MolnPay support marked it satisfied instead.
      - `complete` (required, boolean) — `done || bypassed` — what to render.
    - `bypassed` (required, array, of string, one of: address, payment, live) — Steps MolnPay support ticked off for this account.
    - `skipped_at` (required, string | null (date-time)) — When the checklist was dismissed. Null while it still shows.
    - `can_skip` (required, boolean) — Whether it may be dismissed yet — the plan has to be active first.
    - `remaining` (required, integer) — Steps still outstanding once overrides are applied.
  - `activation` (optional, object | null) — What the balance needs before the pending/requested plan activates. Null when nothing is pending.
    - `plan` (required, string)
    - `plan_name` (required, string) — The display name of the plan waiting to activate.
    - `onboarding_due_cents` (required, string)
    - `balance_required_cents` (required, string)
    - `shortfall_cents` (required, string) — Send at least this much (in USD terms) to activate.
  - `fees` (required, object) — What a new invoice is charged today: your plan, with any negotiated override.
    - `rate_bps` (optional, integer)
    - `fixed_cents` (optional, string)
    - `cap_cents` (optional, string | null)
    - `address_fee_cents` (optional, string)
    - `min_monthly_cents` (optional, string)
    - `history_days` (optional, integer | null) — How far back your lists reach, in days. `null` = no window. A staff override, if any, is folded in.
    - `chains_included` (optional, integer | null) — Chains included in your plan; `null` = every chain.
    - `extra_chain_cents` (optional, string | null) — Monthly price of a chain beyond the included count; `null` = none can be added.
    - `webhooks` (optional, boolean) — Signed webhooks are included (otherwise poll `GET /v1/changes`).
    - `auto_conversion` (optional, boolean) — Settling payments to one coin is included.
    - `statements` (optional, boolean) — Monthly statements and CSV exports are included.
  - `plans` (required, array) — The rate card, for a plan picker.
    - `key` (optional, string)
    - `name` (optional, string)
    - `onboarding_fee_cents` (optional, string)
    - `min_monthly_cents` (optional, string)
    - `operational_balance_cents` (optional, string)
    - `rate_bps` (optional, integer)
    - `fixed_cents` (optional, string)
    - `cap_cents` (optional, string)
    - `negotiated` (optional, boolean)
  - `billing_account` (optional, object) — WHO PAYS: the billing account this merchant draws on and every merchant drawing on it — one balance, one plan, one set of funding addresses between them. `shared` is false for a merchant created with billing of its own.
    - `id` (required, string (uuid))
    - `shared` (required, boolean)
    - `merchants` (required, array)
      - `id` (required, string (uuid)) — The merchant's public id.
      - `display_name` (required, string)
      - `current` (required, boolean) — The merchant this key or session belongs to.
- `400` — `invalid_body`.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Switch auto top-up, or choose the wallet it draws from first

`PUT /v1/billing/auto_topup`

When your prepaid balance reaches zero, MolnPay refills it back to the alert line from your service wallet or your own wallet (`source` first, the other second). On by default. Top-ups are a non-refundable credit for MolnPay fees. On a shared balance this is the account's setting.

### Request body (required)

One of:



### Responses

- `200` — Plan and balance, with `auto_topup` as set.
  - `object` (required, string)
  - `plan` (required, string, one of: drift, current, jetstream, stratos)
  - `plan_name` (required, string)
  - `plan_status` (required, string, one of: pending, active) — `pending` = chosen but not yet funded to the plan's operational balance.
  - `plan_activated_at` (optional, string | null (date-time))
  - `requested_plan` (optional, string | null) — A plan waiting on funding, if any. The stable identifier — match on this.
  - `requested_plan_name` (required, string | null) — That plan's display name, as the pricing page shows it. Print this; the key and the name are allowed to differ.
  - `balance_cents` (required, string) — Prepaid operational balance, USD cents, signed. At or below zero, live invoices are refused.
  - `onboarding_paid_cents` (optional, string)
  - `live` (required, object)
    - `ok` (required, boolean)
    - `reason` (optional, string | null, one of: plan_not_active, billing_balance_exhausted, null)
  - `low_balance` (required, object) — The low-balance alert: `billing.balance_low` fires once when the balance falls under `line_cents`, `billing.balance_exhausted` once when it reaches zero; a top-up over the line re-arms both. Set your own line with `PUT /v1/billing/low_balance`.
    - `line_cents` (required, string) — The line in force, USD cents.
    - `source` (required, string, one of: custom, automatic)
    - `automatic_cents` (required, string) — About 7 days of your recent fees, never under $20.
    - `alerted_at` (required, string | null (date-time)) — When the balance went under the line, while it still is.
    - `exhausted_at` (required, string | null (date-time)) — When it ran out, while it still is.
  - `auto_topup` (required, object) — Auto top-up: when the balance reaches zero it is refilled back to the alert line from your `source` wallet first, the other second — only coins that are free (not promised to a conversion, refund or withdrawal) and that can be priced. On by default. Each refill is a `funding` line (`ref_type: auto_topup`) and a `billing.auto_topup` event. Change it with `PUT /v1/billing/auto_topup`.
    - `enabled` (required, boolean)
    - `source` (required, string, one of: service, own) — Drawn first; the other wallet is the fallback.
    - `last_attempt_at` (required, string | null (date-time)) — The last refill attempt, successful or not. One with nothing to draw is retried hourly.
  - `onboarding` (required, object) — The getting-started checklist. It is guidance, not a gate — `live.ok` above is the only thing that decides whether invoices are accepted.
    - `steps` (required, array) — 🔴 ONLY `plan` IS RESOLVED FROM A FACT ON THIS ROUTE. The other three are reported `done: false` unless bypassed, because deciding them means counting addresses, deposits and invoices — reads a console makes anyway, and three joins we will not run to draw a tick. Derive them yourself and treat `bypassed` as the override.
      - `step` (required, string, one of: plan, address, payment, live)
      - `done` (required, boolean) — The underlying fact holds.
      - `bypassed` (required, boolean) — MolnPay support marked it satisfied instead.
      - `complete` (required, boolean) — `done || bypassed` — what to render.
    - `bypassed` (required, array, of string, one of: address, payment, live) — Steps MolnPay support ticked off for this account.
    - `skipped_at` (required, string | null (date-time)) — When the checklist was dismissed. Null while it still shows.
    - `can_skip` (required, boolean) — Whether it may be dismissed yet — the plan has to be active first.
    - `remaining` (required, integer) — Steps still outstanding once overrides are applied.
  - `activation` (optional, object | null) — What the balance needs before the pending/requested plan activates. Null when nothing is pending.
    - `plan` (required, string)
    - `plan_name` (required, string) — The display name of the plan waiting to activate.
    - `onboarding_due_cents` (required, string)
    - `balance_required_cents` (required, string)
    - `shortfall_cents` (required, string) — Send at least this much (in USD terms) to activate.
  - `fees` (required, object) — What a new invoice is charged today: your plan, with any negotiated override.
    - `rate_bps` (optional, integer)
    - `fixed_cents` (optional, string)
    - `cap_cents` (optional, string | null)
    - `address_fee_cents` (optional, string)
    - `min_monthly_cents` (optional, string)
    - `history_days` (optional, integer | null) — How far back your lists reach, in days. `null` = no window. A staff override, if any, is folded in.
    - `chains_included` (optional, integer | null) — Chains included in your plan; `null` = every chain.
    - `extra_chain_cents` (optional, string | null) — Monthly price of a chain beyond the included count; `null` = none can be added.
    - `webhooks` (optional, boolean) — Signed webhooks are included (otherwise poll `GET /v1/changes`).
    - `auto_conversion` (optional, boolean) — Settling payments to one coin is included.
    - `statements` (optional, boolean) — Monthly statements and CSV exports are included.
  - `plans` (required, array) — The rate card, for a plan picker.
    - `key` (optional, string)
    - `name` (optional, string)
    - `onboarding_fee_cents` (optional, string)
    - `min_monthly_cents` (optional, string)
    - `operational_balance_cents` (optional, string)
    - `rate_bps` (optional, integer)
    - `fixed_cents` (optional, string)
    - `cap_cents` (optional, string)
    - `negotiated` (optional, boolean)
  - `billing_account` (optional, object) — WHO PAYS: the billing account this merchant draws on and every merchant drawing on it — one balance, one plan, one set of funding addresses between them. `shared` is false for a merchant created with billing of its own.
    - `id` (required, string (uuid))
    - `shared` (required, boolean)
    - `merchants` (required, array)
      - `id` (required, string (uuid)) — The merchant's public id.
      - `display_name` (required, string)
      - `current` (required, boolean) — The merchant this key or session belongs to.
- `400` — `invalid_body`.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Dismiss the getting-started checklist

`POST /v1/billing/onboarding/skip`

Hides the four-step panel on your console overview. It is a display preference and grants nothing: the steps after the first — issue an address, take a test payment, go live — were never gates, and the only thing standing between your account and a live payment is an active plan with a positive balance.

Refused with `plan_not_active` until your plan is on, because until then the panel is the only thing explaining why live invoices are being declined. Idempotent: calling it twice does not move the recorded timestamp.

### Responses

- `200` — Plan and balance, with `onboarding.skipped_at` now set.
  - `object` (required, string)
  - `plan` (required, string, one of: drift, current, jetstream, stratos)
  - `plan_name` (required, string)
  - `plan_status` (required, string, one of: pending, active) — `pending` = chosen but not yet funded to the plan's operational balance.
  - `plan_activated_at` (optional, string | null (date-time))
  - `requested_plan` (optional, string | null) — A plan waiting on funding, if any. The stable identifier — match on this.
  - `requested_plan_name` (required, string | null) — That plan's display name, as the pricing page shows it. Print this; the key and the name are allowed to differ.
  - `balance_cents` (required, string) — Prepaid operational balance, USD cents, signed. At or below zero, live invoices are refused.
  - `onboarding_paid_cents` (optional, string)
  - `live` (required, object)
    - `ok` (required, boolean)
    - `reason` (optional, string | null, one of: plan_not_active, billing_balance_exhausted, null)
  - `low_balance` (required, object) — The low-balance alert: `billing.balance_low` fires once when the balance falls under `line_cents`, `billing.balance_exhausted` once when it reaches zero; a top-up over the line re-arms both. Set your own line with `PUT /v1/billing/low_balance`.
    - `line_cents` (required, string) — The line in force, USD cents.
    - `source` (required, string, one of: custom, automatic)
    - `automatic_cents` (required, string) — About 7 days of your recent fees, never under $20.
    - `alerted_at` (required, string | null (date-time)) — When the balance went under the line, while it still is.
    - `exhausted_at` (required, string | null (date-time)) — When it ran out, while it still is.
  - `auto_topup` (required, object) — Auto top-up: when the balance reaches zero it is refilled back to the alert line from your `source` wallet first, the other second — only coins that are free (not promised to a conversion, refund or withdrawal) and that can be priced. On by default. Each refill is a `funding` line (`ref_type: auto_topup`) and a `billing.auto_topup` event. Change it with `PUT /v1/billing/auto_topup`.
    - `enabled` (required, boolean)
    - `source` (required, string, one of: service, own) — Drawn first; the other wallet is the fallback.
    - `last_attempt_at` (required, string | null (date-time)) — The last refill attempt, successful or not. One with nothing to draw is retried hourly.
  - `onboarding` (required, object) — The getting-started checklist. It is guidance, not a gate — `live.ok` above is the only thing that decides whether invoices are accepted.
    - `steps` (required, array) — 🔴 ONLY `plan` IS RESOLVED FROM A FACT ON THIS ROUTE. The other three are reported `done: false` unless bypassed, because deciding them means counting addresses, deposits and invoices — reads a console makes anyway, and three joins we will not run to draw a tick. Derive them yourself and treat `bypassed` as the override.
      - `step` (required, string, one of: plan, address, payment, live)
      - `done` (required, boolean) — The underlying fact holds.
      - `bypassed` (required, boolean) — MolnPay support marked it satisfied instead.
      - `complete` (required, boolean) — `done || bypassed` — what to render.
    - `bypassed` (required, array, of string, one of: address, payment, live) — Steps MolnPay support ticked off for this account.
    - `skipped_at` (required, string | null (date-time)) — When the checklist was dismissed. Null while it still shows.
    - `can_skip` (required, boolean) — Whether it may be dismissed yet — the plan has to be active first.
    - `remaining` (required, integer) — Steps still outstanding once overrides are applied.
  - `activation` (optional, object | null) — What the balance needs before the pending/requested plan activates. Null when nothing is pending.
    - `plan` (required, string)
    - `plan_name` (required, string) — The display name of the plan waiting to activate.
    - `onboarding_due_cents` (required, string)
    - `balance_required_cents` (required, string)
    - `shortfall_cents` (required, string) — Send at least this much (in USD terms) to activate.
  - `fees` (required, object) — What a new invoice is charged today: your plan, with any negotiated override.
    - `rate_bps` (optional, integer)
    - `fixed_cents` (optional, string)
    - `cap_cents` (optional, string | null)
    - `address_fee_cents` (optional, string)
    - `min_monthly_cents` (optional, string)
    - `history_days` (optional, integer | null) — How far back your lists reach, in days. `null` = no window. A staff override, if any, is folded in.
    - `chains_included` (optional, integer | null) — Chains included in your plan; `null` = every chain.
    - `extra_chain_cents` (optional, string | null) — Monthly price of a chain beyond the included count; `null` = none can be added.
    - `webhooks` (optional, boolean) — Signed webhooks are included (otherwise poll `GET /v1/changes`).
    - `auto_conversion` (optional, boolean) — Settling payments to one coin is included.
    - `statements` (optional, boolean) — Monthly statements and CSV exports are included.
  - `plans` (required, array) — The rate card, for a plan picker.
    - `key` (optional, string)
    - `name` (optional, string)
    - `onboarding_fee_cents` (optional, string)
    - `min_monthly_cents` (optional, string)
    - `operational_balance_cents` (optional, string)
    - `rate_bps` (optional, integer)
    - `fixed_cents` (optional, string)
    - `cap_cents` (optional, string)
    - `negotiated` (optional, boolean)
  - `billing_account` (optional, object) — WHO PAYS: the billing account this merchant draws on and every merchant drawing on it — one balance, one plan, one set of funding addresses between them. `shared` is false for a merchant created with billing of its own.
    - `id` (required, string (uuid))
    - `shared` (required, boolean)
    - `merchants` (required, array)
      - `id` (required, string (uuid)) — The merchant's public id.
      - `display_name` (required, string)
      - `current` (required, boolean) — The merchant this key or session belongs to.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — `merchant_not_found`.
- `409` — `plan_not_active`.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Where to send money to top up

`GET /v1/billing/funding`

One address per chain, created on first call and stable forever. EVM chains on the MolnPay factory share one address; read the list rather than assuming. Send only the assets listed for that chain; anything else is not credited.

### Responses

- `200` — Funding addresses.
  - `object` (required, string)
  - `data` (required, array)
  - `has_more` (required, boolean)
  - `next_cursor` (optional, string | null) — Opaque. Pass as `cursor` for the next page. Do not construct or parse it.
  - `data` (optional, array)
    - `object` (required, string)
    - `chain` (required, string, one of: ethereum, bsc, polygon, arbitrum, base, avalanche, tron, solana, ton, bitcoin, dogecoin, optimism, linea, zksync, scroll)
    - `address` (required, string)
    - `memo` (optional, string | null) — Required on TON.
    - `account_kind` (required, string, one of: contract) — Always `contract`: funding addresses are keyless smart accounts on the factory chains only, and every EVM chain listed shares one address.
    - `assets` (required, array) — What may be sent here. `par` assets credit 1:1; others at spot when the deposit confirms.
      - `symbol` (optional, string)
      - `decimals` (optional, integer)
      - `par` (optional, boolean)
      - `logo_url` (optional, string | null) — Decoration; see `Asset.logo_url`.
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Your monthly statements

`GET /v1/billing/statements`

One row per CLOSED calendar month of the billing ledger with at least one line, oldest first: the balance it opened on, what was funded, what was charged, the balance it closed on. The current month is never listed — it has not closed. Included from the Growth plan up; the ledger itself (`GET /v1/billing/entries`) is on every plan.

### Responses

- `200` — Closed months.
  - `object` (required, string)
  - `data` (required, array)
  - `has_more` (required, boolean)
  - `next_cursor` (optional, string | null) — Opaque. Pass as `cursor` for the next page. Do not construct or parse it.
  - `data` (optional, array)
    - `object` (required, string)
    - `month` (required, string) — `YYYY-MM`.
    - `opening_cents` (required, string)
    - `closing_cents` (required, string)
    - `funded_cents` (required, string) — Top-ups credited in the month.
    - `charged_cents` (required, string) — Everything taken off the balance in the month.
    - `entries` (required, integer)
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — `merchant_not_found`.
- `422` — `statements_not_on_plan`.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## One month in full — JSON or CSV

`GET /v1/billing/statements/{month}`

The opening balance, every ledger line of the month in order, totals by kind, and the closing balance. `?format=csv` returns the same as a spreadsheet (`text/csv`, one row per line with a running balance) — what an accountant reconciles against. Not windowed by your plan's history: a statement always covers its whole month.

### Parameters

- `month` (path, required, string) — `YYYY-MM`, a month that has closed.
- `format` (query, optional, string, one of: json, csv)

### Responses

- `200` — The statement.
  - `object` (required, string)
  - `month` (required, string)
  - `period_start` (required, string (date-time))
  - `period_end` (required, string (date-time)) — Exclusive.
  - `opening_cents` (required, string)
  - `closing_cents` (required, string)
  - `funded_cents` (required, string)
  - `charged_cents` (required, string)
  - `by_kind` (required, array)
    - `kind` (required, string)
    - `amount_cents` (required, string)
    - `entries` (required, integer)
  - `entries` (required, array) — Every line of the month, oldest first.
    - `object` (required, string)
    - `id` (required, string (uuid))
    - `merchant_id` (required, string | null (uuid)) — The PUBLIC id of the merchant this line came from, on a balance several merchants share. Null for the account's own lines: funding, the onboarding fee, the monthly minimum, a staff adjustment.
    - `merchant_name` (required, string | null) — That merchant's trading name.
    - `kind` (required, string, one of: funding, onboarding_fee, payment_fee, address_fee, payout_fee, withdrawal_fee, monthly_minimum, refund, adjustment, conversion_fee, release, bridge_fee, extra_chain, payout_network_fee, extra_seat, conversion_network_fee, bridge_network_fee, fee_rebate, network_markup, sweep_network_fee)
    - `amount_cents` (required, string) — Signed. Funding is positive; every fee is negative; a `fee_rebate` (a complimentary account's fee given back in the same moment) is positive, or negative when the fee it covered was returned.
    - `ref_type` (optional, string)
    - `ref_id` (optional, string)
    - `chain` (optional, string | null)
    - `asset` (optional, string | null)
    - `asset_logo_url` (optional, string | null) — Decoration; see `Asset.logo_url`.
    - `amount_atomic` (optional, string | null) — For `funding`: what arrived, atomic units.
    - `rate` (optional, string | null) — For `funding`: USD per whole unit at credit. `1.000000` at par.
    - `rate_source` (optional, string | null)
    - `note` (optional, string | null)
    - `created_at` (required, string (date-time))
    - `transfer` (optional, object | null) — For `funding`: the on-chain transfer that paid this line. Null on every other kind. On the ledger list only — a statement's lines omit it.
      - `amount_decimal` (required, string)
      - `tx_hash` (required, string)
      - `explorer_url` (required, string | null)
      - `from_address` (required, string | null)
      - `confirmations` (required, integer)
      - `required_confirmations` (required, integer | null)
      - `status` (required, string, one of: detected, confirmed, failed, orphaned)
      - `block_time` (required, string | null (date-time))
  - `generated_at` (required, string (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `404` — `statement_not_found` — not a month, not closed yet, or nothing happened in it. `merchant_not_found`.
- `422` — `statements_not_on_plan`.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.

## Your billing ledger, line by line

`GET /v1/billing/entries`

The BILLING ACCOUNT's ledger: when several of your merchants share one plan and balance, every one of them sees the same lines, each stamped with `merchant_id` / `merchant_name` for the merchant it came from. `merchant_id` (one of `billing_account.merchants` on `GET /v1/billing`) narrows to that merchant's lines.

### Parameters

- `limit` (query, optional, integer)
- `cursor` (query, optional, string) — Opaque cursor from the previous page's `next_cursor`.
- `kind` (query, optional, string, one of: funding, onboarding_fee, payment_fee, address_fee, payout_fee, withdrawal_fee, monthly_minimum, refund, adjustment, conversion_fee, release, bridge_fee, extra_chain, payout_network_fee, extra_seat, conversion_network_fee, bridge_network_fee, fee_rebate, network_markup, sweep_network_fee)
- `merchant_id` (query, optional, string (uuid)) — A merchant's public id on this billing account.

### Responses

- `200` — Entries, newest first.
  - `object` (required, string)
  - `data` (required, array)
  - `has_more` (required, boolean)
  - `next_cursor` (optional, string | null) — Opaque. Pass as `cursor` for the next page. Do not construct or parse it.
  - `data` (optional, array)
    - `object` (required, string)
    - `id` (required, string (uuid))
    - `merchant_id` (required, string | null (uuid)) — The PUBLIC id of the merchant this line came from, on a balance several merchants share. Null for the account's own lines: funding, the onboarding fee, the monthly minimum, a staff adjustment.
    - `merchant_name` (required, string | null) — That merchant's trading name.
    - `kind` (required, string, one of: funding, onboarding_fee, payment_fee, address_fee, payout_fee, withdrawal_fee, monthly_minimum, refund, adjustment, conversion_fee, release, bridge_fee, extra_chain, payout_network_fee, extra_seat, conversion_network_fee, bridge_network_fee, fee_rebate, network_markup, sweep_network_fee)
    - `amount_cents` (required, string) — Signed. Funding is positive; every fee is negative; a `fee_rebate` (a complimentary account's fee given back in the same moment) is positive, or negative when the fee it covered was returned.
    - `ref_type` (optional, string)
    - `ref_id` (optional, string)
    - `chain` (optional, string | null)
    - `asset` (optional, string | null)
    - `asset_logo_url` (optional, string | null) — Decoration; see `Asset.logo_url`.
    - `amount_atomic` (optional, string | null) — For `funding`: what arrived, atomic units.
    - `rate` (optional, string | null) — For `funding`: USD per whole unit at credit. `1.000000` at par.
    - `rate_source` (optional, string | null)
    - `note` (optional, string | null)
    - `created_at` (required, string (date-time))
    - `transfer` (optional, object | null) — For `funding`: the on-chain transfer that paid this line. Null on every other kind. On the ledger list only — a statement's lines omit it.
      - `amount_decimal` (required, string)
      - `tx_hash` (required, string)
      - `explorer_url` (required, string | null)
      - `from_address` (required, string | null)
      - `confirmations` (required, integer)
      - `required_confirmations` (required, integer | null)
      - `status` (required, string, one of: detected, confirmed, failed, orphaned)
      - `block_time` (required, string | null (date-time))
- `401` — Missing, malformed, expired or revoked API key.
- `403` — The key lacks the scope, its IP allowlist rejected the source, or signing is disabled.
- `429` — Rate limit or quota exceeded. Honour `Retry-After`.
- `500` — Unexpected error.
- `503` — A dependency is unavailable. Retryable with backoff.