How to Set Transaction Timestamps in Formance

When working with Formance, you may need to set specific timestamps for transactions. This article explains the different methods available for setting transaction timestamps, depending on your use case.

Using the API

When sending a script via the API, you can specify the timestamp in the request body:

{
  "timestamp": "2024-09-07T00:00:00.000Z",
  "script": {
    "vars": {...},
    "plain": "send $my_amount (
      source = $my_account allowing unbounded overdraft
      destination = @world
    )"
  }
}

This method is suitable for programmatic transaction creation.

Using fctl for Manual Transactions

For manual transactions or maintenance tasks, you can use the fctl command-line tool. To set a timestamp when creating a numscript transaction, use the --timestamp flag:

fctl ledger transactions num -|<filename> --timestamp "2024-09-07T00:00:00.000Z"

The timestamp should be in RFC3339 format.

Usage:
  fctl ledger transactions num -|<filename> [flags]

Flags:
      --account-var strings   Pass a variable of type 'account'
      --amount-var strings    Pass a variable of type 'amount'
      --confirm               Confirm action
  -h, --help                  help for num
      --metadata strings      Metadata to use
      --portion-var strings   Pass a variable of type 'portion'
      --reference string      Reference to add to the generated transaction
      --timestamp string      Timestamp to use (format RFC3339)

Limitations in Numscript

Currently, it's not possible to set the transaction timestamp directly within a Numscript. While you can set transaction metadata using set_tx_meta(key, value), there's no equivalent function for setting the timestamp in the script itself.

Best Practices

• For automated processes, use the API method to set timestamps.

• For manual corrections or maintenance, utilize the fctl tool with the --timestamp flag.

• Always ensure the timestamp is in the correct RFC3339 format.

By understanding these methods, you can effectively manage transaction timestamps in various scenarios when working with Formance.