---
title: "Create a crypto top-up invoice"
method: POST
path: "/account/topup"
tags: ["Account"]
---

# Create a crypto top-up invoice

`POST /account/topup`

## Request

- Base URL: `https://api.imprezahost.com/v1`
- URL: `https://api.imprezahost.com/v1/account/topup`
- Auth: API key in header `X-API-Key` and API key in header `X-API-Secret`

Generates an `AddFunds` invoice routed to the `btcpayinline`
gateway. Open `payment_url` to complete payment with Bitcoin (BTC),
Monero (XMR), TRX, or USDT-TRC20. Once the gateway confirms payment,
the client account balance is credited automatically.

Use `GET /account/topup/{invoice_id}` to poll status.

## Request body

- object
  - `amount` number, float, required: Amount in the client's account currency.
  - `method` 'btc' | 'xmr' | 'trx' | 'usdt' | 'usdt_trc20': Optional preferred payment method. Forwarded to the gateway as a hint; the gateway may still display alternatives if the preferred method is unavailable.

## Response `201`

Top-up invoice created successfully

- object
  - `success` boolean
  - `data` object
    - `invoice_id` integer
    - `amount` number, float
    - `currency` string
    - `method` string, nullable
    - `status` 'pending' | 'paid' | 'cancelled' | 'refunded'
    - `payment_url` string, uri
    - `expires_at` string, date-time
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time

## Other responses

- `400`: Validation failed on the request body or query parameters
- `403`: IP not whitelisted or resource not owned
- `500`: Unexpected server-side error

---

[API](https://skmtc.dev/imprezahost/apis/impreza-host-public-api.md) · [All operations](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/revisions/db86511f604f?raw)