Units and fields

noxstock field names carry units where ambiguity would be expensive. Preserve the value exactly unless your UI explicitly converts and labels it.

Unit suffixes

Pattern	Meaning	Example
`_usd`	Whole U.S. dollars, not thousands or millions.	`market_cap_usd: 2914000000000` means $2.914T.
`_pct`	Percent values, not decimal fractions.	`dividend_yield_pct: 1.14` means 1.14%, not 114%.
share-count fields	Full share counts.	`shares_outstanding`, `shares`, `shares_basic`, and `shares_diluted` are counts, not lots or millions.
`_seconds`	Duration in seconds.	`cache_age_seconds: 42`.
no suffix on ratios	Dimensionless ratio.	`current_ratio: 1.07`, `debt_to_equity: 0.8`.

If you display shortened numbers, keep the underlying value unchanged in your app state.

Signs matter

Do not flip signs to make values look positive.

Negative values can be the point:

{
  "drawdown_from_high_pct": -3.18,
  "working_capital_change": -2410000000,
  "net_value_usd": -510400000
}

A negative drawdown is still a drawdown. A negative insider net_value_usd can indicate net selling. A negative cash-flow line can be normal for that statement row.

Timestamps and dates

Timestamps are UTC ISO-8601 unless the field says otherwise:

"as_of": "2026-06-02T18:32:10Z"

Date-only fields use YYYY-MM-DD:

"period_end": "2026-03-28"

Do not mix as_of with fiscal dates. as_of timestamps the payload/source context; period_end, filing_date, transaction_date, and event date describe business or filing dates.

Periods and cadence

Preserve period and cadence fields when present.

Field	Use
`period`	Reporting or history lookback context, such as `quarter`, `annual`, or `1y`.
`cadence`	Row cadence for `/v2/history`: `daily`, `weekly`, `quarterly`, `annual`, or `per-payment`.
`columns`	Column order for `/v2/history.rows`.

For /v2/history, read columns before parsing rows. Rows are compact arrays by design.

{
  "columns": ["date", "close", "rsi_14"],
  "rows": [
    ["2026-05-21", 432.1, 64.5]
  ]
}

Nulls, omissions, and unavailable envelopes

Absence has meaning:

null means the field is meaningful, but this value is not available.
Omitted fields mean the schema allows absence and the source does not have a useful value.
Nested unavailable envelopes, such as holdings: { "available": false, "reason": "..." }, are intentional product states.

Do not invent missing fields for agents, charts, or UI copy.

Unsupported asset states

Unsupported endpoint/asset combinations return successful data with freshness: "unsupported". Preserve reason when present.

{
  "data": {
    "symbol": "SPY",
    "asset_type": "etf",
    "freshness": "unsupported",
    "reason": "ETFs do not report earnings"
  }
}

That is not a failure. It means the requested data does not exist in the current noxstock surface.