Platform Quick Start - Formance Documentation

This guide gets you up and running with Formance as fast as possible. By the end, you’ll have moved money in a Formance Cloud sandbox using the the command line.

Install the CLI

Install fctl, the Formance command-line tool:

Homebrew (macOS/Linux)
Debian/Ubuntu
Binary (Linux/macOS/Windows)

brew install formancehq/tap/fctl

# Add the Formance repository
echo "deb [trusted=yes] https://apt.fury.io/formance/ /" | sudo tee /etc/apt/sources.list.d/formance.list

# Install fctl
sudo apt update && sudo apt install fctl

Download the latest release from GitHub Releases.

# Linux/macOS example (amd64)
ARCH="amd64"
curl -L -o fctl.tar.gz "https://github.com/formancehq/stack/releases/download/v2.0.0-rc.25/fctl_$(uname -s | tr '[:upper:]' '[:lower:]')-$ARCH.tar.gz" \
  && tar -xvf fctl.tar.gz \
  && sudo mv fctl /usr/local/bin \
  && rm fctl.tar.gz

Verify the installation:

fctl version

Authenticate with Formance Cloud (this opens a browser):

fctl login

Create a free sandbox environment:

fctl stack create playground

When prompted, select a region ending with -sandbox for a free development environment.

The sandbox provisions in about 30 seconds. It includes Ledger, Payments, Auth, and Gateway modules ready to use.

Verify your sandbox is ready and get your stack ID:

fctl stack show --name=playground

Look for the ID field in the output:

# Information
ID               | ecwj       |   ← This is your stack ID
Name             | playground |
Region           | eu-sandbox |
Status           | ACTIVE     |

You’ll need this stack ID for the next commands.

Send Your First Transaction

Send $1.00 from world to alice:

fctl ledger send world alice 100 USD/2 --ledger=quickstart --stack=<STACK_ID>

world is a built-in account that can go negative. This is useful for creating funds out of thin air to get started quickly. In production, you’d fund accounts through actual payment flows instead.

USD/2 means USD with 2 decimal places, so 100 represents $1.00. This is how Formance handles monetary precision without floating-point errors.

Check the balances:

fctl ledger volumes list --ledger=quickstart --stack=<STACK_ID>

You should see world with a negative balance (-100) and alice with a positive balance (100). That’s double-entry bookkeeping in action!Congratulations! 🎉 You just executed your first transaction on a programmable ledger.

What’s Next?

Connect Your App

Use the SDK to send transactions from your code.

Learn Numscript

Write complex multi-party transactions with Formance’s scripting language.

Clean Up Your Sandbox

When you’re done experimenting, delete your sandbox to free up resources. Each account is limited to one active sandbox.

fctl stack delete --name=playground

Sandboxes are automatically disabled after 15 days and deleted after 30 days. Data persistence is not guaranteed.

Getting Started

​What’s Next?

Connect Your App

Learn Numscript

What’s Next?