Skip to content

API Reference / Contract evaluation

Explain why named items are or are not matches of a contract

Evaluates a contract's predicate and valuation against up to 10 named catalog items, whether or not the contract matches them, and returns for each item the result of every predicate node, the figure each market data rule read, the price from each valuation reference before any price bound, the combined maximum price, the item's own float window, and where the item ends up: matched, or left out by a rule, by having no price, or by a price bound, with the path of the first node that leaves it out. Use this for the one match a member opens and the few items a search names. It is priced per named item, never per match. To explain a saved contract version, send that version's predicate and valuation.

POST/analytics.v1.Analytics/GetContractItemExplanations

Request body

application/jsonRequired

Request to explain a contract's predicate and valuation against a few named catalog items.

contractIdstring

Opaque 16-byte identifier of the contract being explained, base64-encoded in JSON. Required and must be a valid identifier, but only the predicate and valuation in this request are evaluated, never the stored contract.

Format"byte" base64

marketHashNames?array<string>

The items to explain, from 1 to 10 distinct market hash names. Explanations come back in this order.

predicate?Predicate

Which items the contract matches, with every filter set reference already expanded, exactly as sent to EvaluateContract. Node paths in the response index this predicate as sent.

Show attributes
filterSet?FilterSetReference

This node is a reference to a named, reusable filter set, expanded into its fragment before evaluation.

Show attributes
filterSetId?string

Identifier of the referenced filter set. Must belong to the same workspace as the contract. The contracts worker expands it into its predicate fragment before evaluation.

Format"byte" base64

group?PredicateGroup

This node is a group: an AND/OR combination of child predicate nodes.

Show attributes
condition?string

Logical combinator applied to rules: AND or OR.

Value in"PREDICATE_CONDITION_AND""PREDICATE_CONDITION_OR"

rules?array<Predicate>

Child predicate nodes combined by condition. Must be non-empty.

rule?PredicateRule

This node is a leaf rule: a single subject-operator-value condition.

Show attributes
field?string

This rule's subject is an item attribute, resolved against the items catalog.

Value in"PREDICATE_FIELD_MARKET_HASH_NAME""PREDICATE_FIELD_CATEGORY""PREDICATE_FIELD_WEAPON""PREDICATE_FIELD_PAINT""PREDICATE_FIELD_RARITY""PREDICATE_FIELD_COLLECTION""PREDICATE_FIELD_MIN_WEAR""PREDICATE_FIELD_MAX_WEAR""PREDICATE_FIELD_HAS_STAT_TRAK""PREDICATE_FIELD_HAS_SOUVENIR""PREDICATE_FIELD_ITEM_AGE_DAYS""PREDICATE_FIELD_WEAPON_TYPE"

marketData?MarketDataField

This rule's subject is a (source, metric) market-observation value.

Show attributes
freshnessFreshness

Maximum age of the observation this rule reads. Required, exactly one positive unit: an observation older than now minus freshness is treated as unavailable and the rule does not match.

Show attributes
maximumAge?string

The oldest market data to use. Must be positive.

metric?string

Name of the market-observation metric to resolve, for example a source's 7-day sales volume.

source?string

Market-data source the metric is resolved against.

operator?string

Comparison operator applied to the subject's resolved value. Which operators are legal depends on the subject: field allows the full attribute operator set (narrowed to gte/gt for min_wear and lte/lt for max_wear), market_data allows only eq, neq, gt, gte, lt, lte and between (with a number_range_value, both ends inclusive), and value_field allows only gt, gte, lt, lte. The list operators in, not_in, contains_any and contains_none take a string_list_value. Contains_any and contains_none apply only to the text fields market_hash_name, weapon, paint and collection, and item_age_days also takes between.

Value in"PREDICATE_OPERATOR_EQ""PREDICATE_OPERATOR_NEQ""PREDICATE_OPERATOR_IN""PREDICATE_OPERATOR_NOT_IN""PREDICATE_OPERATOR_GT""PREDICATE_OPERATOR_GTE""PREDICATE_OPERATOR_LT""PREDICATE_OPERATOR_LTE""PREDICATE_OPERATOR_CONTAINS""PREDICATE_OPERATOR_NOT_CONTAINS""PREDICATE_OPERATOR_BETWEEN""PREDICATE_OPERATOR_CONTAINS_ANY""PREDICATE_OPERATOR_CONTAINS_NONE"

value?PredicateValue

Right-hand side value the subject is compared against.

Show attributes
boolValue?boolean

Boolean value, used when the subject's comparison is against a boolean item attribute such as has_stat_trak or has_souvenir.

decimalValue?string

Exact decimal number as text, used for a float (wear) bound on min_wear or max_wear: digits, a point and up to 16 decimal places, with no sign and no exponent, from 0 to 1. Kept and returned exactly as given, so 0.2734 reads back as 0.2734 and 0.27340 as 0.27340. A float bound given as number_value is read as the shortest decimal that number prints as, and every float bound is returned as decimal_value.

numberRangeValue?NumberRange

Number range, used with the between operator on a market-data or item_age_days rule: the rule matches when the value is at least minimum and at most maximum.

Show attributes
maximum?number

The highest value inside the range, included. Must be at least minimum.

Format"double"

minimum?number

The lowest value inside the range, included.

Format"double"

numberValue?number

Numeric value, used when the subject's comparison is against a number: a market-data bound, a computed-price bound, or a numeric item attribute.

Format"double"

stringListValue?StringList

List of string values, used with the in, not_in, contains_any and contains_none operators.

Show attributes
values?array<string>

The wrapped list of string values.

stringValue?string

String value, used when the subject's comparison is against text.

valueField?string

This rule's subject is the valuation's combined computed price for the item.

Value in"PREDICATE_VALUE_FIELD_COMPUTED_PRICE"

valuation?Valuation

How the contract prices an item. Absent explains the predicate only.

Show attributes
references?array<ValuationReference>

The price sources to combine, each a market data lookup or a sale computation.

Show attributes
adjustment?number

Fraction applied to the resolved price, which is multiplied by one plus this value: -0.3 pays 30 percent under, 0.1 pays 10 percent over. From -1 to 10.

Format"double"

aggregationAggregation

How the selected sales combine into one price. Required for a sale computation and not allowed on a market data lookup.

Show attributes
average?AverageOptions

Options for an average. Only used when type is average.

Show attributes
weighted?boolean

True weights each sale by its quantity. False averages sale prices equally.

type?string

The combining function: average, median, minimum, maximum, mode or percentile. Percentile needs the reference's percentile field.

Value in"AGGREGATION_TYPE_AVERAGE""AGGREGATION_TYPE_MEDIAN""AGGREGATION_TYPE_MINIMUM""AGGREGATION_TYPE_MAXIMUM""AGGREGATION_TYPE_MODE""AGGREGATION_TYPE_PERCENTILE"

freshnessFreshness

Maximum age of the observation a market-data lookup reads. Required for a market-data lookup (metric set). Rejected for a sale computation (window/aggregation set).

Show attributes
maximumAge?string

The oldest market data to use. Must be positive.

lag?Lag

Shifts an hours or days window into the past. Sale computation only. Absent prices on the latest sales.

Show attributes
shift?string

How far to shift the window back from now. Only valid with a time window.

metric?string

Metric to read, such as "listing-price", which makes this a market data lookup. Absent for a sale computation.

outlier?Outlier

Drops sales far from the typical price before combining them. Sale computation only. Absent keeps every sale.

Show attributes
sigma?number

Sales more than this many standard deviations from the mean are dropped, such as 2.0.

Format"double"

percentileinteger

Percentile to take, from 0 to 100. Required with the percentile aggregation and not allowed otherwise.

Format"int32"

source?string

Market source to price from, such as "market-csgo".

truncatePercentage?boolean

For a market-data lookup, preserve the raw fractional USD cents until calculating trunc((100 + adjustment * 100) * (raw / 100)). False retains the ordinary nearest-cent rounding. True is rejected for sale computations.

window?Window

Which recent sales to read, which together with aggregation makes this a sale computation. Absent for a market data lookup.

Show attributes
count?integer

Read the most recent this many sales, whenever they happened. Cannot be combined with lag.

Format"int32"

length?string

Read sales from this long before now. Lag can shift the window into the past.

strategy?string

How the references combine into one price. MIN is required for a buying contract and MAX for a selling contract. AVG is valid for either. Pairing the wrong extreme with a contract type risks overpaying (MAX on a buying contract) or underpricing (MIN on a selling contract).

Value in"VALUATION_STRATEGY_MIN""VALUATION_STRATEGY_MAX""VALUATION_STRATEGY_AVG"

Response body

application/json

Success

explanations?array<ContractItemExplanation>

The explanations, one per named item, in request order.

Show attributes
category?string

The item's catalog category, such as weapon_skin. Absent when unknown.

collection?string

The item's collection. Absent when it has none.

excludingPath?string

Path of the first predicate node that leaves the item out: the first failing rule of an all-of group, or an any-of group none of whose branches holds. Empty when the item is matched, has no price, or is not in the catalog.

marketHashName?string

The item's market hash name, as named in the request.

maxBuyPriceCents?string

The valuation's combined price in US cents before any price bound is applied. Absent when a reference the strategy needs has no price, or without a valuation.

Format"int64"

maxFloat?number

Highest float of the item's own share of the predicate's float window. Absent when the predicate sets no float bound or the item has no float.

Format"double"

maxFloatDecimal?string

max_float as exact decimal text, as EvaluateContract reports it: the predicate's own upper bound exactly as given when that bound is this item's upper edge, otherwise the item's own wear boundary to at least two decimal places. Set exactly when max_float is set.

maxWear?number

Highest float the item's wear allows, from 0.0 to 1.0. Absent for an item without a float.

Format"double"

minFloat?number

Lowest float of the item's own share of the predicate's float window. Absent when the predicate sets no float bound or the item has no float.

Format"double"

minFloatDecimal?string

min_float as exact decimal text, as EvaluateContract reports it: the predicate's own lower bound exactly as given when that bound is this item's lower edge, otherwise the item's own wear boundary to at least two decimal places. Set exactly when min_float is set.

minWear?number

Lowest float the item's wear allows, from 0.0 to 1.0. Absent for an item without a float.

Format"double"

nodes?array<ContractNodeResult>

Every node of the predicate as sent, groups and rules, in pre-order, judged for the item. Empty when the item is not in the catalog.

Show attributes
figure?number

For a market data rule, the figure it read, in US dollars for a price and as reported otherwise. Absent for other nodes, and when no figure was fresh enough.

Format"double"

met?boolean

Whether the node holds for the item. A rule whose figure is missing does not hold. Absent only for a price bound when the item has no price to judge it against.

path?string

The node's position: its child indexes from the root joined by dots. The root is the empty path. "0.2" is the third child of the root's first child.

outcome?string

Where the item ends up: matched, left out by a rule, without a price, outside a price bound, or not in the catalog.

Value in"CONTRACT_ITEM_OUTCOME_MATCHED""CONTRACT_ITEM_OUTCOME_EXCLUDED_BY_RULE""CONTRACT_ITEM_OUTCOME_NO_PRICE""CONTRACT_ITEM_OUTCOME_OUTSIDE_PRICE_BOUND""CONTRACT_ITEM_OUTCOME_NOT_IN_CATALOG"

paint?string

The item's finish, such as Redline. Absent when the item has none.

rarity?string

The item's rarity. Absent when unknown.

referencePrices?array<ReferencePrice>

Each valuation reference's resolved price for the item, in reference order, exactly as EvaluateContract reports them.

Show attributes
lastObservedAt?string

For a stale reference, when last_value_cents was observed. Set only when outcome is stale.

Format"date-time"

lastValueCents?string

For a stale reference, the last value the source reported before the reference's adjustment, in US cents. Set only when outcome is stale.

Format"int64"

metric?string

The metric read for a market data lookup. Absent for a sale computation.

observedAt?string

When the figure behind value_cents was observed: the market observation's own time for a market data lookup, or the newest sale in the window for a sale computation. Absent when value_cents is absent.

Format"date-time"

outcome?string

Whether the reference resolved a price, found only an observation older than its freshness window, or found no data at all.

Value in"REFERENCE_PRICE_OUTCOME_RESOLVED""REFERENCE_PRICE_OUTCOME_STALE""REFERENCE_PRICE_OUTCOME_MISSING"

priceCents?string

The price after the reference's adjustment, in US cents, which the valuation strategy combines. Absent when the source had no usable data.

Format"int64"

referenceIndex?integer

Zero-based position of the reference in the valuation's references.

Format"int32"

source?string

The reference's market source, such as "market-csgo".

valueCents?string

The price the source gave before the reference's adjustment, in US cents. Absent when the source had no usable data.

Format"int64"

weapon?string

The item's weapon, such as AK-47. Absent when the item has none.

weaponType?string

The item's weapon type, such as rifle. Absent when the item has none.

licensedSourcesWithheld?LicensedSourcesWithheld

No longer set: price reads carry no limits, so no licensed price source's figures are left out. Kept so existing clients still decode the response.

Show attributes
limit?string

The rule that left them out.

Value in"LICENSED_SOURCE_LIMIT_NOT_SIGNED_IN""LICENSED_SOURCE_LIMIT_UNNAMED_ITEMS""LICENSED_SOURCE_LIMIT_ITEMS_PER_REQUEST""LICENSED_SOURCE_LIMIT_REQUESTS_PER_MINUTE""LICENSED_SOURCE_LIMIT_ITEMS_PER_DAY"

resetsAt?string

When the limit next admits the read, for the per-minute and per-day limits. Absent for a rule the caller fixes by changing the read.

Format"date-time"

sourceFamily?string

The licensed provider whose figures were left out.

curl -X POST "https://api.goldmine.to/analytics.v1.Analytics/GetContractItemExplanations" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": "AY86PB0ufwCKGyw9Tl9gcQ==",
    "marketHashNames": [
      "AK-47 | Redline (Field-Tested)"
    ],
    "predicate": {
      "filterSet": {
        "filterSetId": "AY86PB0ufwCKGyw9Tl9gcQ=="
      }
    },
    "valuation": {
      "references": [
        {
          "adjustment": 3,
          "aggregation": {},
          "freshness": {},
          "lag": {},
          "metric": "listing-price",
          "outlier": {},
          "percentile": 3,
          "source": "buff163",
          "truncatePercentage": false,
          "window": {}
        }
      ],
      "strategy": "VALUATION_STRATEGY_MIN"
    }
  }'
{
  "explanations": [
    {
      "category": "example",
      "collection": "example",
      "excludingPath": "example",
      "marketHashName": "AK-47 | Redline (Field-Tested)",
      "maxBuyPriceCents": "2360",
      "maxFloat": 3,
      "maxFloatDecimal": "example",
      "maxWear": 3,
      "minFloat": 3,
      "minFloatDecimal": "example",
      "minWear": 3,
      "nodes": [
        {}
      ],
      "outcome": "CONTRACT_ITEM_OUTCOME_MATCHED",
      "paint": "example",
      "rarity": "example",
      "referencePrices": [
        {}
      ],
      "weapon": "example",
      "weaponType": "example"
    }
  ],
  "licensedSourcesWithheld": {
    "limit": "LICENSED_SOURCE_LIMIT_NOT_SIGNED_IN",
    "resetsAt": "2026-11-03T16:10:00Z",
    "sourceFamily": "example"
  }
}