Using overdraft() to check negative account balances in NumScript

When working with asset accounts in Formance that have negative balances, you can use the experimental overdraft() function to safely check balances and perform transactions atomically.

Overview of overdraft()

The overdraft() function returns the positive amount of overdraft when an account's balance is negative, or 0 if the balance is positive. This is particularly useful when working with asset accounts, which by design have negative balances in Formance.

Using overdraft() in NumScript

Here's how to use the overdraft function:

vars {
    monetary $acc_overdraft = overdraft(@account, USD/2)
}

// Use $acc_overdraft in your transaction logic
send $acc_overdraft (
    source = @world
    destination = @account
)

Enabling the experimental feature

To use overdraft(), you need to enable two experimental features:

1. The experimental rewrite feature

2. The experimental-overdraft-function flag

You can find instructions for enabling these features in the NumScript embedding documentation.

Alternative: Using balance()

If you cannot use the experimental features, note that the standard balance() function only works with non-negative balances and will fail if the account balance is negative.