> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmo.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Money & precision

> Every monetary value is a full-precision decimal string. Here's why, and how to handle it.

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.

```json theme={null}
{ "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).

<Note>
  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.
</Note>

## Sending money

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

<CodeGroup>
  ```json Good theme={null}
  { "amountUsd": "12.50" }
  ```

  ```json Bad — number theme={null}
  { "amountUsd": 12.5 }
  ```

  ```json Bad — raw base units theme={null}
  { "amountUsd": "12500000" }
  ```
</CodeGroup>

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.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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"
  ```

  ```python Python theme={null}
  from decimal import Decimal

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

## 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:

```python theme={null}
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`:

```json theme={null}
{
  "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"`).

<Check>
  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.
</Check>