Money and currencies

How monetary amounts are represented in the API.

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), stablecoins (6 decimals), and high-precision crypto (8+ 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"
USD	2	"10.50"
EUR	2	"10.50"
USDC	6	"1.500000"
USDT	6	"100.000000"
BTC	8	"1.00000000"

Examples

A deposit of R$ 1.250,00:

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

A withdrawal of $500.00:

{
  "amount": {
    "value": "500.00",
    "asset": "USD",
    "decimals": 2
  }
}