Migrating from 0.5.x to 1.0.0

This guide covers the breaking changes introduced in v1.0.0 and how to update your code.

`create_invoice()` signature change

The asset parameter is no longer the first positional argument and is now optional. amount is the first positional argument.

Before (0.5.x):

invoice = client.create_invoice(Asset.TON, 1.5)

# or with keyword arguments
invoice = client.create_invoice(asset=Asset.TON, amount=1.5)

After (1.0.0):

invoice = client.create_invoice(1.5, asset=Asset.TON)

# keyword-only style still works, but asset must come after amount
invoice = client.create_invoice(amount=1.5, asset=Asset.TON)

If you were already using asset= and amount= as keyword arguments, the only change is that asset is now optional (required only for crypto invoices).

Fiat invoices

The signature change enables the new fiat invoice support. To create a fiat invoice, omit asset and pass currency_type, fiat, and accepted_assets instead:

invoice = client.create_invoice(
    amount=10.00,
    currency_type="fiat",
    fiat="USD",
    accepted_assets="USDT,TON,BTC",
)

`ExchangeRate.source` is now a `str`

ExchangeRate.source changed from the Asset enum to a plain str because the API can return fiat currency codes that are not members of Asset.

Before (0.5.x):

rates = client.get_exchange_rates()
btc_usd = next(r for r in rates if r.source == Asset.BTC and r.target == "USD")

After (1.0.0):

rates = client.get_exchange_rates()
btc_usd = next(r for r in rates if r.source == "BTC" and r.target == "USD")

Validation error messages

Internal validation was generalized to support checks and transfers. If your code matches on exception messages from create_invoice or get_invoices, update accordingly:

0.5.x message	1.0.0 message
`"invoice_ids string cannot be empty"`	`"ids string cannot be empty"`
`"invoice_ids list cannot be empty"`	`"ids list cannot be empty"`
`"invoice_ids string must contain positive integer IDs"`	`"ids string must contain positive integer IDs"`
`"invoice_ids list must contain positive integers"`	`"ids list must contain positive integers"`
`"invoice_ids must be a comma-separated string or list of integers"`	`"ids must be a comma-separated string or list of integers"`

New endpoints

These are additive and do not break existing code, but are worth noting:

delete_invoice(invoice_id)
create_check(asset, amount, ...) / delete_check(check_id)
get_checks(...) with iter_checks() and iter_check_pages() pagination
get_transfers(...) with iter_transfers() and iter_transfer_pages() pagination
get_stats(start_at, end_at)
fiat filter parameter on get_invoices()

All new endpoints are available on both CryptoBotClient and AsyncCryptoBotClient.