Quick Start - Formance Documentation

Get from zero to your first transactions in 5 minutes. By the end, you'll have funded an account, split a payment, and checked balances — all using Numscript.

This guide assumes you have fctl installed and a sandbox running. If not, start with the Platform Quick Start.

Your First Transaction#

Create a ledger

fctl ledger create main

POST/api/ledger/v2/main

This creates a ledger named main. All accounts and transactions will live here.

Fund a user account

Send $100 from @world (an infinite funding source) to a user account:

numscript

send [USD/2 10000] (
  source = @world
  destination = @user:alice
)

fctl ledger transactions num - --confirm --ledger main <<< 'send [USD/2 10000] ( source = @world destination = @user:alice )'

POST/api/ledger/v2/main/transactions

USD/2 means US dollars with 2 decimal places. 10000 = $100.00. Accounts are created automatically on first use.

Split a payment

Alice buys something for $30. The merchant gets 90%, the platform takes 10% as a fee:

numscript

send [USD/2 3000] (
  source = @user:alice
  destination = {
    90% to @merchant:bob
    remaining to @platform:fees
  }
)

fctl ledger transactions num - --confirm --ledger main <<< 'send [USD/2 3000] ( source = @user:alice destination = { 90% to @merchant:bob remaining to @platform:fees } )'

POST/api/ledger/v2/main/transactions

The ledger enforces that Alice has sufficient funds. If she doesn't, the transaction is rejected — no partial execution, no overdraft.

Check balances

fctl ledger accounts list --ledger=main

GET/api/ledger/v2/main/accounts

You should see:

Account	Balance (USD/2)	Meaning
`user:alice`	7000	$70.00 remaining
`merchant:bob`	2700	$27.00 (90% of $30)
`platform:fees`	300	$3.00 (10% of $30)

Every cent is accounted for. The sum of all non-world balances equals the total funded.

What Just Happened#

Double-entry: every send creates balanced movements — what leaves one account enters another
@world: a special infinite source/sink for money entering and exiting the ledger
USD/2: Universal Monetary Notation — the asset type and precision, no floating-point
Splits: Numscript natively handles percentage splits with remaining catching rounding
Scarcity: the ledger rejects transactions when the source account has insufficient funds

Your First Transaction#

Create a ledger

fctl ledger create main

POST/api/ledger/v2/main

This creates a ledger named main. All accounts and transactions will live here.

Fund a user account

Send $100 from @world (an infinite funding source) to a user account:

numscript

send [USD/2 10000] (
  source = @world
  destination = @user:alice
)

fctl ledger transactions num - --confirm --ledger main <<< 'send [USD/2 10000] ( source = @world destination = @user:alice )'

POST/api/ledger/v2/main/transactions

USD/2 means US dollars with 2 decimal places. 10000 = $100.00. Accounts are created automatically on first use.

Split a payment

Alice buys something for $30. The merchant gets 90%, the platform takes 10% as a fee:

numscript

send [USD/2 3000] (
  source = @user:alice
  destination = {
    90% to @merchant:bob
    remaining to @platform:fees
  }
)

fctl ledger transactions num - --confirm --ledger main <<< 'send [USD/2 3000] ( source = @user:alice destination = { 90% to @merchant:bob remaining to @platform:fees } )'

POST/api/ledger/v2/main/transactions

The ledger enforces that Alice has sufficient funds. If she doesn't, the transaction is rejected — no partial execution, no overdraft.

Check balances

fctl ledger accounts list --ledger=main

GET/api/ledger/v2/main/accounts

You should see:

Account	Balance (USD/2)	Meaning
`user:alice`	7000	$70.00 remaining
`merchant:bob`	2700	$27.00 (90% of $30)
`platform:fees`	300	$3.00 (10% of $30)

Every cent is accounted for. The sum of all non-world balances equals the total funded.

What Just Happened#

Double-entry: every send creates balanced movements — what leaves one account enters another

@world: a special infinite source/sink for money entering and exiting the ledger

USD/2: Universal Monetary Notation — the asset type and precision, no floating-point

Splits: Numscript natively handles percentage splits with remaining catching rounding

Scarcity: the ledger rejects transactions when the source account has insufficient funds