---
sidebar_position: 44
---

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

# `lium topup`

Top up your Lium balance with a **stablecoin** (e.g. USDT). Unlike [`lium fund`](./fund.md) — which transfers TAO from a Bittensor wallet — `topup` creates a payment invoice and hands you a **deposit address** plus the exact crypto amount to send. You make the transfer from your own wallet; the balance is credited automatically once the network confirms it.

This is the recommended path for **AI agents that self-fund**: every subcommand supports `--json`, so an agent can create an invoice, read the deposit address, send the funds, then poll `lium balance` until the credit lands — no human in the loop.

```bash
lium topup COMMAND [OPTIONS]
```

## Subcommands

| Command | Purpose |
|---------|---------|
| `lium topup currencies` | List supported stablecoins and networks |
| `lium topup create` | Create an invoice and print the deposit address + amount |

## `lium topup currencies`

List the stablecoins and networks you can pay with.

```bash
lium topup currencies [--refresh] [--json]
```

| Flag | Effect |
|------|--------|
| `--refresh` | Bypass the cache and re-fetch from the provider |
| `--json` | Print machine-readable JSON |

```bash
lium topup currencies
lium topup currencies --json
```

## `lium topup create`

Create a top-up invoice and print the deposit address plus the exact amount to send.

```bash
lium topup create -a AMOUNT -c CURRENCY -n NETWORK [--json]
```

| Flag | Effect |
|------|--------|
| `--amount, -a FLOAT` | Top-up amount in **USD** (required) |
| `--currency, -c CODE` | Stablecoin code, e.g. `USDT` (required) |
| `--network, -n NAME` | Network the coin is sent on, e.g. `tron` (required) |
| `--json` | Print machine-readable JSON |

```bash
lium topup create -a 20 -c USDT -n tron
lium topup create -a 20 -c USDT -n tron --json
```

The response includes everything needed to pay:

| Field | Meaning |
|-------|---------|
| `invoice_id` | Provider invoice identifier |
| `deposit_address` | **Send the funds here** |
| `crypto_amount` | Exact amount of `crypto_currency` to send |
| `crypto_currency` / `crypto_network` | Coin and network to send on |
| `fiat_amount` / `fiat_currency` | USD value being credited |
| `expires_at` | Invoice expiry — send before this (invoices live ~30 min) |
| `hosted_invoice_url` | Browser-payable page for the same invoice |

:::warning Send the exact amount, on the right network, before expiry
Underpaying credits only what is received. Sending on the wrong network, or after `expires_at`, can lose the funds. Always read `crypto_amount` and `crypto_network` back from the invoice rather than assuming them.
:::

## Agent self-funding loop

A shell agent with wallet access can top itself up end-to-end:

```bash
# 1. Discover a supported coin/network
lium topup currencies --json

# 2. Create a $20 invoice and capture the deposit address + amount
INVOICE=$(lium topup create -a 20 -c USDT -n tron --json)
ADDRESS=$(echo "$INVOICE" | jq -r .deposit_address)
AMOUNT=$(echo "$INVOICE"  | jq -r .crypto_amount)

# 3. Send exactly $AMOUNT USDT (TRON) to $ADDRESS from your own wallet.
#    This transfer happens in your wallet — Lium does not move your funds.

# 4. Poll until the balance is credited
lium balance --json
```

The transfer in step 3 is yours to make — Lium only issues the invoice and credits the balance once the provider confirms the on-chain payment.

## See also

- [`lium fund`](./fund.md) — fund with TAO from a Bittensor wallet instead
- [`lium balance`](./index.md) — check the credited balance
- [AI Agents](../../agents.md) — full agent integration guide