API Reference / Contract evaluation
Report how much of a predicate's matched catalog the valuation can price
Runs a contract's predicate against the catalog exactly as EvaluateContract does, but reports every matched item instead of only the ones the valuation could price. Returns the count of matched items, how many of those the valuation prices, how many it does not, and a capped sample of the unpriced item names. Use this to show a member which of their predicate's matches have no usable market price before they activate the contract.
/ analytics. v1. Analytics/ GetContractCoverageRequest body
application/jsonRequired
Request to measure how much of a predicate's matched catalog a valuation can price, with a sample of the items it cannot.
cursor?stringnext_cursor from the previous response of the same request. Empty starts counting from the beginning. Only meaningful with resumable set.
facetFields?array<string>Dimensions to break the matched items down by, at most 2, counted in the same pass as the totals. Empty returns no facets.
Value in"EVALUATE_"EVALUATE_
predicate?PredicateWhich items to match, with every filter set reference already expanded, evaluated exactly as EvaluateContract does.
Show attributes
filterSet?FilterSetReferenceThis node is a reference to a named, reusable filter set, expanded into its fragment before evaluation.
Show attributes
filterSetId?stringIdentifier 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?PredicateGroupThis node is a group: an AND/OR combination of child predicate nodes.
Show attributes
condition?stringLogical combinator applied to rules: AND or OR.
Value in"PREDICATE_"PREDICATE_
rules?array<Predicate>Child predicate nodes combined by condition. Must be non-empty.
rule?PredicateRuleThis node is a leaf rule: a single subject-operator-value condition.
Show attributes
field?stringThis rule's subject is an item attribute, resolved against the items catalog.
Value in"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_
marketData?MarketDataFieldThis rule's subject is a (source, metric) market-observation value.
Show attributes
freshnessFreshnessMaximum 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?stringThe oldest market data to use. Must be positive.
metric?stringName of the market-observation metric to resolve, for example a source's 7-day sales volume.
source?stringMarket-data source the metric is resolved against.
operator?stringComparison 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_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_
value?PredicateValueRight-hand side value the subject is compared against.
Show attributes
boolValue?booleanBoolean value, used when the subject's comparison is against a boolean item attribute such as has_stat_trak or has_souvenir.
decimalValue?stringExact 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?NumberRangeNumber 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?numberThe highest value inside the range, included. Must be at least minimum.
Format"double"
minimum?numberThe lowest value inside the range, included.
Format"double"
numberValue?numberNumeric 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?StringListList 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?stringString value, used when the subject's comparison is against text.
valueField?stringThis rule's subject is the valuation's combined computed price for the item.
Value in"PREDICATE_
query?stringText the item's market hash name must contain, as EvaluateContract applies it, so the counts match a searched preview.
resumable?booleanCount for about eight seconds and answer with the running totals and a next_cursor to continue from, instead of counting every match in one call. A broad predicate takes longer than the API's request limit to count. sample_limit is reduced to at most 100 in this mode.
sampleLimit?integerMaximum number of unpriced item names to return. Zero uses the default of 100 and values above 1000 are reduced to 1000 rather than rejected.
Format"int32"
valuation?ValuationHow to price each matched item. An item counts as priced when the valuation produces a maximum price above zero.
Show attributes
references?array<ValuationReference>The price sources to combine, each a market data lookup or a sale computation.
Show attributes
adjustment?numberFraction 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"
aggregationAggregationHow the selected sales combine into one price. Required for a sale computation and not allowed on a market data lookup.
Show attributes
average?AverageOptionsOptions for an average. Only used when type is average.
Show attributes
weighted?booleanTrue weights each sale by its quantity. False averages sale prices equally.
type?stringThe combining function: average, median, minimum, maximum, mode or percentile. Percentile needs the reference's percentile field.
Value in"AGGREGATION_"AGGREGATION_"AGGREGATION_"AGGREGATION_"AGGREGATION_"AGGREGATION_
freshnessFreshnessMaximum 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?stringThe oldest market data to use. Must be positive.
lag?LagShifts an hours or days window into the past. Sale computation only. Absent prices on the latest sales.
Show attributes
shift?stringHow far to shift the window back from now. Only valid with a time window.
metric?stringMetric to read, such as "listing-price", which makes this a market data lookup. Absent for a sale computation.
outlier?OutlierDrops sales far from the typical price before combining them. Sale computation only. Absent keeps every sale.
Show attributes
sigma?numberSales more than this many standard deviations from the mean are dropped, such as 2.0.
Format"double"
percentileintegerPercentile to take, from 0 to 100. Required with the percentile aggregation and not allowed otherwise.
Format"int32"
source?stringMarket source to price from, such as "market-csgo".
truncatePercentage?booleanFor 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?WindowWhich recent sales to read, which together with aggregation makes this a sale computation. Absent for a market data lookup.
Show attributes
count?integerRead the most recent this many sales, whenever they happened. Cannot be combined with lag.
Format"int32"
length?stringRead sales from this long before now. Lag can shift the window into the past.
strategy?stringHow 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_"VALUATION_"VALUATION_
Response body
application/json
Success
facets?array<EvaluateContractFacetCounts>One breakdown per requested facet field, in request order, counting every matched item, priced or not.
Show attributes
counts?FacetFieldCountsThe values by count descending then value, at most 50, with truncated set when more values exist.
Show attributes
truncated?booleanTrue when the field has more than 50 values, so the list shows only the 50 most common.
values?array<FacetValueCount>The values and their counts, ordered by count descending then by value, at most 50.
Show attributes
count?stringNumber of rows carrying the value under the facet's predicate. Returned as a JSON string to preserve integer precision.
Format"int64"
value?stringThe value as the list rows carry it: an enum name, a base64 id or an account name, so a client maps it to a label exactly as it maps a row.
field?stringThe facet field these counts break down.
Value in"EVALUATE_"EVALUATE_
inBandCount?integerPriced matched items that also pass the predicate's computed price bounds: the items the contract would buy or sell.
Format"int32"
inBandMaxBuyPriceTotalCents?stringSum of max_buy_price_cents over the in_band_count items, in cents: what the contract spends if each item fills once.
Format"int64"
leftOut?array<MatchLeftOutCount>Catalog items the predicate's rules match that are never candidates of a contract, so matched_count leaves them out, counted by the reason. Only reasons with at least one item are listed, in the enum's order. Set on the response that completes a resumable count.
Show attributes
count?integerMatched items left out for the reason.
Format"int32"
reason?stringWhy these items are left out.
Value in"MATCH_
matchedCount?integerNumber of catalog items matching the predicate.
Format"int32"
nextCursor?stringSet when a resumable count stopped early: every figure in this response is the running total so far. Send it as cursor to continue. Empty once every match has been counted.
pricedCount?integerNumber of matched items the valuation prices above zero.
Format"int32"
references?array<ReferenceCoverage>One tally per valuation reference, in reference order, of the matched items for which that reference found only an older observation or no data at all.
Show attributes
finishesUnpriced?array<FinishUnpricedCount>Of the matched Doppler and Gamma Doppler finishes (items named <Steam name> - <finish>), how many the reference left unpriced, by the reason, so a page can say why a finish is not bought. Only reasons with at least one finish are listed, in the enum's order.
Show attributes
count?integerMatched finishes left unpriced for the reason.
Format"int32"
reason?stringWhy the reference left these finishes unpriced.
Value in"FINISH_"FINISH_"FINISH_
missingCount?integerMatched items for which the reference found no usable data at all.
Format"int32"
referenceIndex?integerZero-based position of the reference in the valuation's references.
Format"int32"
staleCount?integerMatched items for which the reference found an observation older than its freshness window, so it was not used.
Format"int32"
unpricedCount?integerNumber of matched items the valuation cannot price, equal to matched_count minus priced_count.
Format"int32"
unpricedMarketHashNames?array<string>Market hash names of up to sample_limit unpriced items, in alphabetical order, to show which items lack market data.
application/json
The request was malformed, such as a missing required field or an unparseable cursor.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The request lacks a valid API key in the Authorization header.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The API key is not allowed to perform this action on this workspace.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The request was rate limited. Slow down and retry later.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
An internal server error occurred.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
curl -X POST "https://api.goldmine.to/analytics.v1.Analytics/GetContractCoverage" \
-H "Authorization: Bearer $CSTRADER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"predicate": {
"group": {
"condition": "PREDICATE_CONDITION_AND",
"rules": [
{
"rule": {
"field": "PREDICATE_FIELD_WEAPON",
"operator": "PREDICATE_OPERATOR_EQ",
"value": {
"stringValue": "AK-47"
}
}
},
{
"rule": {
"field": "PREDICATE_FIELD_RARITY",
"operator": "PREDICATE_OPERATOR_IN",
"value": {
"stringListValue": {
"values": [
"Covert",
"Classified"
]
}
}
}
}
]
}
},
"valuation": {
"references": [
{
"source": "market-csgo",
"metric": "listing-price",
"adjustment": -0.05
}
],
"strategy": "VALUATION_STRATEGY_MIN"
},
"sampleLimit": 100
}'const res = await fetch("https://api.goldmine.to/analytics.v1.Analytics/GetContractCoverage", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CSTRADER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"predicate": {
"group": {
"condition": "PREDICATE_CONDITION_AND",
"rules": [
{
"rule": {
"field": "PREDICATE_FIELD_WEAPON",
"operator": "PREDICATE_OPERATOR_EQ",
"value": {
"stringValue": "AK-47"
}
}
},
{
"rule": {
"field": "PREDICATE_FIELD_RARITY",
"operator": "PREDICATE_OPERATOR_IN",
"value": {
"stringListValue": {
"values": [
"Covert",
"Classified"
]
}
}
}
}
]
}
},
"valuation": {
"references": [
{
"source": "market-csgo",
"metric": "listing-price",
"adjustment": -0.05
}
],
"strategy": "VALUATION_STRATEGY_MIN"
},
"sampleLimit": 100
}),
});
const data = await res.json();body := strings.NewReader(`{
"predicate": {
"group": {
"condition": "PREDICATE_CONDITION_AND",
"rules": [
{
"rule": {
"field": "PREDICATE_FIELD_WEAPON",
"operator": "PREDICATE_OPERATOR_EQ",
"value": {
"stringValue": "AK-47"
}
}
},
{
"rule": {
"field": "PREDICATE_FIELD_RARITY",
"operator": "PREDICATE_OPERATOR_IN",
"value": {
"stringListValue": {
"values": [
"Covert",
"Classified"
]
}
}
}
}
]
}
},
"valuation": {
"references": [
{
"source": "market-csgo",
"metric": "listing-price",
"adjustment": -0.05
}
],
"strategy": "VALUATION_STRATEGY_MIN"
},
"sampleLimit": 100
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.goldmine.to/analytics.v1.Analytics/GetContractCoverage", body)
if err != nil {
return err
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("CSTRADER_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)import os, requests
res = requests.post(
"https://api.goldmine.to/analytics.v1.Analytics/GetContractCoverage",
headers={"Authorization": f"Bearer {os.environ['CSTRADER_API_KEY']}"},
json={
"predicate": {
"group": {
"condition": "PREDICATE_CONDITION_AND",
"rules": [
{
"rule": {
"field": "PREDICATE_FIELD_WEAPON",
"operator": "PREDICATE_OPERATOR_EQ",
"value": {
"stringValue": "AK-47"
}
}
},
{
"rule": {
"field": "PREDICATE_FIELD_RARITY",
"operator": "PREDICATE_OPERATOR_IN",
"value": {
"stringListValue": {
"values": [
"Covert",
"Classified"
]
}
}
}
}
]
}
},
"valuation": {
"references": [
{
"source": "market-csgo",
"metric": "listing-price",
"adjustment": -0.05
}
],
"strategy": "VALUATION_STRATEGY_MIN"
},
"sampleLimit": 100
},
)
data = res.json(){
"matchedCount": 200,
"pricedCount": 160,
"unpricedCount": 40,
"unpricedMarketHashNames": [
"AK-47 | Bloodsport (Battle-Scarred)",
"AK-47 | Vulcan (Battle-Scarred)"
]
}{
"code": "invalid_argument",
"message": "The request was malformed, such as a missing required field or an unparseable cursor."
}{
"code": "unauthenticated",
"message": "The request lacks a valid API key in the Authorization header."
}{
"code": "permission_denied",
"message": "The API key is not allowed to perform this action on this workspace."
}{
"code": "resource_exhausted",
"message": "The request was rate limited. Slow down and retry later."
}{
"code": "internal",
"message": "An internal server error occurred."
}