> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bravadotrade.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Numeric and Timestamp Conventions in the Bravado API
> Bravado encodes all numeric values as JSON strings for precision. Learn price units, micro-USDC fields, timestamp formats, and parsing recommendations.
Bravado encodes all numeric fields, including prices, balances, PnL, volume, and share counts, as JSON strings rather than native JSON numbers. This is intentional: JavaScript's `Number` type (IEEE 754 double-precision float) loses precision on integers larger than 2⁵³ and on decimal values that cannot be represented exactly in binary floating point. By using strings, Bravado lets your application choose the right numeric type for its environment.
## Why strings?
Financial applications require exact arithmetic. A balance of `"1234567.890123"` USDC must round-trip without loss. Native JSON number parsing in JavaScript would silently corrupt values like this:
```javascript theme={null}
// ❌ Dangerous, precision lost
JSON.parse('{"balance": 1234567.890123}').balance
// => 1234567.8901230002 (IEEE 754 rounding error)
// ✅ Safe, parse as string, then use decimal library
import Decimal from "decimal.js";
const balance = new Decimal(response.balance); // exact
```
Always parse numeric string fields with a `Decimal` / `BigDecimal` type before performing any arithmetic.
## Request field units
The table below covers every numeric field you send in request bodies or query parameters. The "Common Mistake" column highlights the most frequent source of integration bugs.
Sending `price: 62` instead of `price: "0.62"` is the single most common integration error. Prices are decimal probabilities in the range 0–1, not cents.
| Field | Unit | Example value | Common mistake |
| ------------------------------- | ----------------------------------- | ---------------- | ---------------------- |
| `price` | Decimal probability `0.001`–`0.999` | `"0.62"` (= 62¢) | Sending `"62"` (cents) |
| `size` | Shares (string) | `"100"` | |
| `quote_amount` | US dollars | `"10"` | Sending micro-units |
| `budget_usdc` | US dollars | `"50"` | Sending micro-units |
| `price_floor` | Decimal probability `0`–`1` | `0.05` | Sending cents (`5`) |
| `price_ceiling` | Decimal probability `0`–`1` | `0.95` | Sending cents (`95`) |
| `offset_ticks` | CLOB ticks (1 tick = 0.1¢) | `0` | |
| `execution.trailing_offset_pct` | Percent `0`–`100` | `5` | |
| `execution.duration_sec` | Seconds | `3600` | |
| `execution.interval_sec` | Seconds (minimum 10) | `60` | |
| `notional_usd` (combo) | US dollars | `5` | |
### Price in depth
All market prices on Polymarket are expressed as decimal probabilities between 0 and 1. A YES share trading at 62 cents has a price of `0.62`. The API enforces the range `0.001`–`0.999`; values outside this range return a `400` with the message:
```
"price must be a decimal probability 0.001–0.999; received 72 — did you mean 0.72?"
```
If you see this error, check whether your price source is returning cents (0–100) and divide by 100 before sending.
## Response field units
Response fields follow a consistent naming convention that signals their unit.
| Field pattern | Unit | Example |
| -------------------------------------------------- | -------------------------- | ------------------------ |
| `realized_pnl`, `unrealized_pnl`, `volume`, `fees` | USDC (6-decimal string) | `"1234.567890"` |
| `balance_usdc`, `pusd` | USDC (6-decimal string) | `"500.000000"` |
| `payout_base_units` | pUSD integer (6 decimals) | `"1000000"` = 1.0 pUSD |
| `shares`, `size` | Share count (string) | `"250"` |
| Fields ending in `_uusdc` | Micro-USDC integer string | `"1234567"` = \$1.234567 |
| Fields ending in `_ushare` | Micro-share integer string | `"500000"` = 0.5 shares |
## Micro-USDC (uusdc)
Some Data API and PMWAS fields express values in **micro-USDC**, integers where 1 USDC = 1,000,000 units. These fields always end in `_uusdc` or `_ushare`.
```json theme={null}
{
"fees_uusdc": "1234567",
"volume_uusdc": "50000000"
}
```
To convert to display USDC, divide by `1,000,000`:
```python theme={null}
from decimal import Decimal
fees_uusdc = Decimal(response["fees_uusdc"])
fees_usdc = fees_uusdc / Decimal("1000000") # => Decimal("1.234567")
```
Standard PnL and balance fields on the trading endpoints (`/v2/trade/...`) are already in USDC with 6 decimal places, no conversion needed. Only fields explicitly suffixed `_uusdc` or `_ushare` require the ÷ 1,000,000 step.
## Timestamps
Bravado uses different timestamp formats depending on the field's purpose. You can identify the format from the field name:
| Field pattern | Format | Example |
| ------------------------------------------------------ | ------------------------------ | ---------------------------- |
| `block_timestamp`, `timestamp`, `created_at` (integer) | Unix seconds (integer) | `1720000000` |
| Fields ending in `_utc` | ISO-8601 / RFC 3339 UTC string | `"2024-07-03T12:00:00Z"` |
| Fields ending in `_iso` | ISO-8601 string | `"2024-07-03T12:00:00Z"` |
| `refreshed_at`, `fetched_at` | RFC 3339 UTC string | `"2024-07-03T12:00:00.000Z"` |
| `expires_at` (combo quotes) | ISO-8601 instant | `"2024-07-03T12:00:08.500Z"` |
| `date_acquired`, `date_sold` | ISO-8601 date | `"2024-07-03"` |
**Converting a Unix-seconds timestamp in Python:**
```python theme={null}
from datetime import datetime, timezone
block_timestamp = 1720000000
dt = datetime.fromtimestamp(block_timestamp, tz=timezone.utc)
# => datetime(2024, 7, 3, 6, 13, 20, tzinfo=timezone.utc)
```
**Converting a Unix-seconds timestamp in JavaScript:**
```javascript theme={null}
const blockTimestamp = 1720000000;
const dt = new Date(blockTimestamp * 1000); // multiply by 1000 for ms
// => 2024-07-03T06:13:20.000Z
```
Combo quote `expires_at` values are ISO-8601 instants with millisecond precision. Parse them with a full datetime parser, not a simple integer comparison.
## Parsing recommendations
Follow these language-specific patterns to safely handle all numeric fields returned by the Bravado API.
**Python**
```python theme={null}
from decimal import Decimal, getcontext
# Set precision high enough for your calculations
getcontext().prec = 28
data = response.json()
realized_pnl = Decimal(data["realized_pnl"]) # e.g. Decimal("1234.567890")
current_price = Decimal(data["price"]) # e.g. Decimal("0.620000")
size = Decimal(data["size"]) # e.g. Decimal("100")
# Micro-USDC conversion
fees_uusdc = Decimal(data["fees_uusdc"]) / Decimal("1000000")
```
**JavaScript / TypeScript**
```typescript theme={null}
import Decimal from "decimal.js"; // npm install decimal.js
const data = await resp.json();
const realizedPnl = new Decimal(data.realized_pnl); // exact
const currentPrice = new Decimal(data.price);
const size = new Decimal(data.size);
// Micro-USDC conversion
const feesUsdc = new Decimal(data.fees_uusdc).div(1_000_000);
```
Never parse Bravado numeric strings with `parseFloat()`, `float()`, or native JSON number parsing. These types cannot represent 6-decimal USDC values exactly and will silently introduce rounding errors in balance and PnL calculations.