Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.formance.com/llms.txt

Use this file to discover all available pages before exploring further.

Hardcoded values are great for quick prototyping and iteration, but chances are that you will at some point need to inject some variables into your Numscript files. Here is an example using definitions of all the supported variable types: 
vars {
  monetary $price
  account $trade
  portion $commission
  asset $pair
  number $id
  string $reference
}

send $price (
  source = @world
  destination = {
    $commission to @platform
    remaining to $trade
  }
)

set_tx_meta("asset", $asset)
set_tx_meta("id", $id)
set_tx_meta("reference", $reference)
Injections of variables can be done at execution, by using the POST /{ledger}/transactions endpoint. The script.vars field in the request body is used to inject variable values: 
{
    "script": {
        "vars": {
            "price": "USD/2 100",
            "trade": "trades:108391999",
            "commission": "15%",
            "pair": "EUR/2",
            "id": "108391999",
            "reference": "USD/EUR:108391999"
        }
    }
}
Variable names must be lowercase and start with at least one letter or _. They can contain letters, digits, and _.

​
Account type

This type represents account names. They must start with at least one letter or _. They can contain letters, digits, _, and :.

​
Asset type

This type represents asset names. They can contain uppercase letters, digits and /.

​
Monetary type

This type represents a positive integer amount associated with an asset. 
"USD/2 100"
It is possible to pull the balance of an account and inject it in a monetary variable by using the balance(_account_, _asset_) statement. The balance pulled needs to be non-negative, or the script will fail to execute. Here is an example: 
vars {
    monetary $initial = balance(@A, USD/2)
}

send [USD/2 100] (
    source = {
        @A
        @C
    }
    destination = {
        max $initial to @B
        remaining to @D
    }
)

​
Portion type

This type represents portions of monetary values. They can be expressed in 2 different ways:
  • As a percentage: 15%
  • As a fraction: 15/100
Their computed values must be between 0 and 1 (inclusive).
Variables can also be pulled from account metadata, as per described in the metadata section.