Skip to content

Quickstart

Run Torment locally and move your first money in five minutes.

You need Go 1.26 and Docker.

Terminal window
make up # Postgres 17 and a single-replica TigerBeetle
make run # migrates the database and serves on :8080

Every example below is one HTTP request with a JSON body. To send one with curl:

Terminal window
curl -H 'Authorization: Bearer dev-key' -d '<body>' localhost:8080/<path>

dev-key is the development API key. Every route except /healthz and /readyz needs it.

Currencies are registered once. USD/2 means amounts are in cents.

POST /currencies
{ "code": "USD/2" }
201 Created
{ "name": "USD", "precision": 2 }

Every posting also has a kind, which says what it is. Register the two this guide uses, top_up and withdrawal:

POST /kinds
{ "name": "top_up" }
201 Created
{ "name": "top_up" }
POST /kinds
{ "name": "withdrawal" }

Every posting debits one account and credits another, so you need two. The first is your bank account, which is an asset because it’s money you own.

POST /accounts
{ "address": "bank:settlement", "type": "asset" }

The rider’s wallet is a liability, because it’s money you hold for the rider.

POST /accounts
{ "address": "rider:1:wallet", "type": "liability" }

The rider tops up $100. The money arrives in your bank, and you now owe it to the rider. A posting always debits one account and credits another. Debiting an asset raises it, and crediting a liability raises it, so this posting debits the bank and credits the rider. Debits and credits has the full table.

POST /transfers
{
"chains": [
[
{
"id": "00000000-0000-0000-0000-000000000001",
"debit": "bank:settlement",
"credit": "rider:1:wallet",
"currency": "USD",
"amount": "10000",
"kind": "top_up"
}
]
]
}
200 OK
{ "chains": [[{ "id": "00000000-0000-0000-0000-000000000001", "group_id": "00000000-0000-0000-0000-000000000001", "status": "created" }]] }

Each element of chains is a chain: a list of postings that all happen or none do. This request has one chain with one posting, and the response has the same shape.

GET /accounts/rider:1:wallet/balances
200 OK
{
"address": "rider:1:wallet",
"totals": [{ "type": "liability", "currency": "USD", "precision": 2, "amount": "10000" }],
"accounts": [
{
"address": "rider:1:wallet",
"type": "liability",
"balances": [{ "currency": "USD", "precision": 2, "amount": "10000" }]
}
]
}

A single account comes back in the same shape as a pattern, so totals here is just the rider’s balance.

Both balances went up: the bank holds $100, and you owe the rider $100. That’s double-entry: every posting debits one account and credits another by the same amount.

Send the same transfer from step 3 again. It isn’t applied twice:

200 OK
{ "chains": [[{ "id": "00000000-0000-0000-0000-000000000001", "group_id": "00000000-0000-0000-0000-000000000001", "status": "exists" }]] }

That’s what makes retries safe: if a request times out, send it again with the same ids.

The rider tries to withdraw $200 they don’t have. Money leaving goes the other way: debit the rider’s wallet to lower what you owe, and credit the bank to lower what it holds.

POST /transfers
{
"chains": [
[
{
"id": "00000000-0000-0000-0000-000000000002",
"debit": "rider:1:wallet",
"credit": "bank:settlement",
"currency": "USD",
"amount": "20000",
"kind": "withdrawal"
}
]
]
}
200 OK
{
"chains": [
[{ "id": "00000000-0000-0000-0000-000000000002", "group_id": "00000000-0000-0000-0000-000000000002", "status": "failed", "error": "insufficient_funds", "message": "..." }]
]
}

Nothing moved. To try again after a top-up, use a new id: a failed id can’t be reused.

  • Concepts explains accounts, debits and credits, postings, kinds and chains properly.
  • API lists every route.