Money and currencies

Overview

Monetary amounts in the Trace Finance API are represented as decimal strings in the asset’s canonical scale, paired with an ISO 4217 currency code or stablecoin ticker. This single shape works uniformly for fiat (2 decimals) and stablecoins (6 decimals).

Always parse amounts with a decimal-precision library (BigDecimal, decimal.Decimal, Decimal.js). Never use JavaScript Number or any 64-bit float — values like 0.1 + 0.2 lose precision, and high-decimal tokens overflow the safe-integer range.

How it works

Amount object

Every amount in a response uses the same structure:

{
  "value": "0.11",
  "asset": "BRL",
  "decimals": 2
}

Field	Type	Description
`value`	string	Decimal amount in the asset’s canonical scale. Always a string to preserve precision.
`asset`	string	ISO 4217 currency code or stablecoin ticker.
`decimals`	integer	Number of decimal places for the asset.

In request bodies

Quote and operation requests take amounts as a decimal-string scalar paired with a separate asset field — not the full object:

{
  "sourceAmount": "500.00",
  "sourceAsset": "BRL"
}

The number of fractional digits must not exceed the asset’s precision (table below). Exceeding it returns INVALID_AMOUNT_PRECISION.

Decimal precision per asset

`asset`	`decimals`	Example `value`
`BRL`	2	`"5000.00"`
`USDT`	6	`"100.000000"`
`USDC`	6	`"1.500000"`

Examples

A deposit of R$ 1.250,00:

{
  "amount": {
    "value": "1250.00",
    "asset": "BRL",
    "decimals": 2
  }
}

A withdrawal of 500 USDT:

{
  "amount": {
    "value": "500.000000",
    "asset": "USDT",
    "decimals": 6
  }
}

Getting started

Compliance Requirements

API principles

Webhooks

Journeys

Overview

How it works

Amount object

In request bodies

Decimal precision per asset

Examples

​Overview

​How it works

​Amount object

​In request bodies

​Decimal precision per asset

​Examples

Overview

How it works

Amount object

In request bodies

Decimal precision per asset

Examples