Overview 🗺️

The FOMO Treasury API is how your platform holds money, receives it, converts it between currencies or crypto assets, and pays it out - across bank rails and blockchains. This page gives you the high-level picture; the full API reference covers field-level detail.

The building blocks

Resource	What it is
Account	A container that holds one or more Balances, each in a specific currency or crypto asset (e.g. SGD, USD, USDT). This is your working treasury.
Balance	The actual funds inside an Account for one asset - available amount, total amount, and overdraft limit if applicable.
Virtual Account	A dedicated sending / receiving account (its own bank details or crypto address) that routes incoming funds from / into one of your Accounts. Used for POBO and COBO flows.
Account Holder	The verified legal owner behind an Account and Virtual Account - established through a KYC/KYB check before funds can move.
Beneficiary	A payee: an individual or business you intend to send money to.
Beneficiary Account	The actual destination for a payment to a Beneficiary - a bank account, crypto address, or payment proxy (PayNow, FPS ID, etc.). One Beneficiary can have several.
Quote	A locked-in exchange rate for converting one asset to another (fiat↔fiat, fiat↔crypto, crypto↔crypto).
Trade	A conversion that's actually been executed against a Quote. The converted asset isn't automatically deposited into a Balance - it sits as trade proceeds until you move it out via an Outgoing Transfer (to an external Beneficiary Account) or an Internal Transfer (into one of your own Balances).
Incoming Transfer	A record of funds that arrived - typically via a Virtual Account - and landed in one of your Balances.
Outgoing Transfer	Send money from your account to a Beneficiary Account, optionally over a specific payment rail.

How money typically moves

Receiving money:

A Virtual Account is issued to you (customer) or your customer (client). Funds sent to it land automatically in the linked Account's Balance, and each one shows up as an Incoming Transfer you can look up or list.

Sending money:

If the payout currency differs from your Balance's currency, get a Quote and execute a Trade to convert funds first.

Create an Outgoing Transfer, specifying the source Balance (or Trade proceeds), the Beneficiary Account, and the payment rail to use.

The "intent" pattern

Nothing is created directly. Every action that touches money or account details - opening a Virtual Account, adding a Beneficiary, sending an Outgoing Transfer, executing a Trade - goes through a two-step intent:

Create the intent with the details you want to submit.

Confirm the intent to actually execute it.

Between those two steps, an intent may sit in one of these states:

pending-requirements - waiting on more information (see the intent's requirements and optional_requirements list)

pending-approval - waiting on internal sign-off

pending-result - submitted, waiting on the outcome

completed - finished, successfully or not (check the result field)

This separation exists deliberately: it gives you a checkpoint to validate details - especially payee and payment information - before money actually moves, and it means every change to sensitive account or payment configuration is auditable as a discrete, confirmable step rather than an instant side effect.

The building blocks#

How money typically moves#

The "intent" pattern#

The building blocks

How money typically moves

The "intent" pattern