Container ROI and history

Development contract

These methods are implemented and tested locally. Public production access has not launched. They read CSFolder’s existing calculations; they never trigger an upstream request or calculate a probability tree per API call.

Three methods

• GET /v1/openables?valuation_mode=steam_gross&limit=100 — paginate the public catalog, not a top-100 subset. Pass meta.next_page as after until it is null.
• GET /v1/openables/{slug}?valuation_mode=cash_ask — current published calculation and quality fields for the exact slug returned by the catalog.
• GET /v1/openables/{slug}/history?from=2026-08-01&to=2026-08-31&granularity=day — stored model snapshots. Pagination uses after; keep all filters unchanged.

All three require a Bearer key with market:read and use the same account quota as other market methods. Inactive containers are hidden, except retired Armory pools retained with active: false for hypothetical analysis. Draft-only definitions and draft calculations are not published.

Valuation and units

valuation_mode accepts steam_gross (default) or cash_ask. These are valuation models, not selectable individual marketplaces or guaranteed liquidation proceeds. There is no silent fallback from a missing cash calculation to Steam, or vice versa. current: null means no published calculation for the selected mode and current methodology, not zero ROI.

Money fields ending in _cents use integer USD cents, with currency: "USD" and minor_units: 2. Decimal percentage fields are strings to preserve precision.

Field	Meaning
cost_cents	Total modeled cost of one opening/claim under the selected model
expected_value_cents	Modeled expected output value, not the median or guaranteed sale value
expected_profit_cents	Modeled expected value minus modeled cost
return_pct	Expected value / cost × 100
profit_roi_pct	return_pct − 100, present on the current calculation
profit_chance_pct	Modeled probability of a profitable outcome, not the return percentage

For example, a modeled cost of 1,000 cents and expected value of 800 cents mean return_pct: "80.000000", profit_roi_pct: "-20.000000" and expected_profit_cents: -200. Return percentages are not probabilities: they can exceed 100, and profit ROI can be negative. These metrics do not promise realized profit or account for every user’s execution conditions.

Quality and time

Missing point estimates remain null. The current calculation also returns lower/upper expected-value and profit-chance bounds, quantiles, price-coverage percentages, confidence and flags. Do not turn an unknown upper bound into zero or treat the lower bound as the point estimate. priced_probability_mass_pct describes coverage of possible outcomes, not the chance of profit.

• calculated_at is the current model’s calculation/check time.
• price_as_of is the stored input-price time; it may be null and is not an individual timestamp for every outcome.
• stale follows the site’s ROI policy: calculation age over 8 hours, unknown price time or price age over 24 hours.
• meta.generated_at is only response generation time.

The worker currently recalculates ROI on a six-hour schedule. More frequent API calls do not make the model fresher.

Historical model snapshots

Select granularity=hour|day and optionally methodology_version. The default methodology matches the current calculation; specify the version explicitly to keep a backfill stable across API upgrades. Each row retains revision_id, revision_number and methodology_version; do not merge incompatible versions into one unqualified curve. Published revisions that were later retired remain readable. Pages read the current stored history, not an immutable point-in-time export: a later reconstruction may revise historical values.

One request spans at most 366 UTC calendar days and returns up to 2,000 rows (default 1,000). The default window is the last 31 calendar days. For a longer backfill, request consecutive windows and follow each window’s meta.next_page before advancing.

History returns only the selected resolution: there is no hourly/daily fallback, interpolation or gap filling. An existing container without matching points returns an empty array.

kind: "model_snapshot" distinguishes this from actual sales or realized investment returns. ts is the bucket timestamp; recorded_at is when the stored row was written, not when all input prices were observed. Existing storage does not distinguish live model snapshots from historical reconstructions, so provenance: "not_recorded" is explicit. An hourly bucket does not prove a new hourly calculation. Do not call this an independently observed hourly ROI series.

Prompt for an ROI comparison tool

Build a CS2 container comparison dashboard using CSFolder Data API.
Read /llms.txt and /openapi.json first. Keep CSFOLDER_API_KEY on the server.
Load every catalog page from /v1/openables; do not stop at the first 100.
Keep steam_gross and cash_ask separate. Show modeled cost, expected value,
profit ROI, profit chance, coverage, confidence, price time and stale status.
Treat all null estimates as unavailable. Never present expected ROI as a guarantee.
Draw history from the documented history method without filling missing dates.
Keep revision/methodology changes visible and label reconstruction provenance unknown.
Test empty history, partial pricing, negative ROI, pagination and 401/429/503.

See data quality and the generated API reference for the current contract.