Money & precision

This is the single most important convention in the API. Get it right and a whole class of bugs disappears.

Everything is USDC

The simple part first: Murmo runs on USDC. Your balance is USDC, and every trade either spends it or returns it. Buy a token, you spend USDC; sell, you get USDC back. Predictions cost USDC and pay out in USDC. Perps post USDC as collateral and settle in USDC. You fund one thing only: USDC on your Solana address. The rest of this page is about the format those USD amounts take on the wire.

The rule

Every monetary value on the wire is a full-precision plain decimal string in USD.

That applies to responses and requests. A value is:

a string, e.g. "12.50" — never a JSON number,
in human USD, e.g. "5" means five dollars — never raw base units like "5000000",
plain decimal — never scientific notation like "5e-7",
full precision — never pre-rounded. Round only when you display.

{ "totalCostUsd": "5", "alphaFeeUsd": "0.05", "unrealizedPnlUsd": "-1.2345678" }

Why strings

JSON numbers are IEEE-754 doubles. 0.1 + 0.2 is 0.30000000000000004, and big integers silently lose precision past 2^53. For money that’s unacceptable. A decimal string carries the exact value with no rounding, and you parse it with a decimal library on your side. So $5 serializes as "5", not 5000000 (its raw base units) and not 5.0 (a float).

Token quantities that are genuinely in base units are the one exception, and they are always named with a Raw suffix (e.g. currentTokenAmountRaw, inputAmountRaw). Everything called ...Usd (or a price/PnL/percent) is a human decimal string.

Sending money

Send the same way: a decimal string. Don’t multiply by 1e6, don’t send a number.

{ "amountUsd": "12.50" }

{ "amountUsd": 12.5 }

{ "amountUsd": "12500000" }

Bad amounts are rejected with a clean 400 rather than being silently mis-scaled.

Parsing money

Use a decimal type, not a float, anywhere you do arithmetic.

// For display, Number() is fine:
const usd = Number(data.totalCostUsd); // 12.5

// For math, use a decimal library (decimal.js, big.js):
import Decimal from "decimal.js";
const cost = new Decimal(data.totalCostUsd);
const fee = new Decimal(data.alphaFeeUsd);
const net = cost.plus(fee).toFixed(2); // "12.55"

from decimal import Decimal

cost = Decimal(data["totalCostUsd"])
fee = Decimal(data["alphaFeeUsd"])
net = cost + fee            # exact
print(f"${net:.2f}")        # round only for display

Raw vs. human quantities

Two kinds of numbers show up, and the suffix tells you which:

Field style	Meaning	Example	How to use
`...Usd`, prices, PnL, percent	Human decimal string	`"12.50"`, `"-3.7"`	Parse as a decimal.
`...Raw`, `...BaseUnits`, `...BaseLots`	Integer base-unit quantity string	`"25000000"`	Humanize with the token’s `decimals`.
`tokenDecimals`, `decimals`, counts, indices	Structural integer	`6`, `9`	Plain JSON number.

To humanize a raw token quantity, divide by 10 ** decimals using a decimal type:

from decimal import Decimal

raw = Decimal("1380000000000")   # outputAmountRaw
decimals = 9                      # from GET /spot/tokens/{mint}
human = raw / (Decimal(10) ** decimals)   # Decimal('1380')

Percentages

Percentage fields (pnlPct, exitPnlPct, winRate, priceChange24hPct, …) are also full-precision decimal strings, expressed as a percent: "4.27" means 4.27%, and "-12.5" means −12.5%.

A worked example

A $5 spot buy comes back like this — note the human "5", not 5000000:

{
  "data": {
    "trade": {
      "tradeType": "BUY",
      "tokenAmount": "1380.5",
      "tokenDecimals": 9,
      "pricePerTokenUsd": "0.00362",
      "totalCostUsd": "5",
      "alphaFeeUsd": "0.01",
      "pnlUsd": null
    }
  }
}

totalCostUsd: "5" → five dollars.
tokenAmount: "1380.5" → already humanized for trade rows (uses tokenDecimals).
pricePerTokenUsd: "0.00362" → a small price, still a plain decimal (never "3.62e-3").

If you ever see a number where you expected a string, a value off by a factor of ~1,000,000, or an e-style exponent in a money field, that’s a bug — please report it. The API is built so these never reach the wire.

Get started

Example flows

Core concepts

Trading guides

Real-time (WebSockets)

Everything is USDC

The rule

Why strings

Sending money

Parsing money

Raw vs. human quantities

Percentages

A worked example

​Everything is USDC

​The rule

​Why strings

​Sending money

​Parsing money

​Raw vs. human quantities

​Percentages

​A worked example

Everything is USDC

The rule

Why strings

Sending money

Parsing money

Raw vs. human quantities

Percentages

A worked example