API Reference / Contract evaluation
Evaluate a contract against current market data
Runs a contract's predicate and valuation against the latest market data and returns the matching items together with the maximum price to pay for each. Results are paginated through a cursor. Use this to preview what a contract would buy before activating it.
/ analytics. v1. Analytics/ EvaluateContractRequest body
application/jsonRequired
Request to run a predicate and valuation against the latest market data and return one page of matching items with their maximum buy prices.
contractIdstringOpaque 16-byte identifier of the contract being previewed, 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
cursor?stringOpaque cursor from a previous EvaluateContractResponse.next_cursor. Empty for the first page. Send the same predicate and valuation with every page.
descending?booleanReverses the order. Ties on price fall back to market hash name in the same direction.
limit?integerMaximum number of intents to return, up to 1000. Zero uses the default of 100. A larger value is rejected with invalid_argument.
Format"int32"
matches?stringWhich matches to return. Unspecified returns the matches the contract would buy. The unpriced and outside-price-range lists need a valuation. Send the same value with every page.
Value in"EVALUATE_"EVALUATE_
predicate?PredicateWhich items to match, with every filter set reference already expanded. A filter set reference is rejected with invalid_argument.
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, matched case sensitively like a contains rule, ANDed with the predicate. Empty matches every item. Send the same query with every page. A changed query needs a fresh cursor.
skipCounts?booleanLeave matched_count and unpriced_count unset on the first page. Counting prices every match, which for a broad predicate takes far longer than the page itself, so a caller that shows the page first and reads GetContractCoverage separately sets this.
sortField?stringOrder of the intents. Unspecified orders by market hash name.
Value in"EVALUATE_"EVALUATE_
valuation?ValuationHow to price each matched item. Absent evaluates the predicate only and returns intents without a maximum price. A predicate rule on a computed price requires a valuation.
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
completedFeedGeneration?stringOpaque lowercase SHA-256 fingerprint of the completed market-feed publications used by this page. Present on every successful page, including an empty or final page. The empty completed-source set has its own deterministic fingerprint. An omitted value means unknown provenance. This fences completed feeds only. Catalog, primitive observations, sales, and exchange rates remain independently mutable.
intents?array<EvaluateContractIntent>The matched items on this page, each with its maximum buy price.
Show attributes
failedPriceBounds?array<ComputedPriceBound>For a match outside the price range: each computed-price bound of the predicate its maximum price fails, in predicate order. Empty for every other match.
Show attributes
operator?stringHow the maximum price must compare to value_cents: GT, GTE, LT, LTE, EQ or NEQ.
Value in"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_"PREDICATE_
valueCents?numberThe bound, in US cents, exactly as the predicate gives it.
Format"double"
marketHashName?stringSteam market hash name of the matched item, such as "AK-47 | Redline (Field-Tested)".
maxBuyPriceCents?stringMaximum price to pay for one unit of the item, in US cents. Absent when the request had no valuation or the valuation could not price this item.
Format"int64"
maxFloat?numberHighest acceptable float (wear) value for this item, from 0.0 to 1.0: the upper end of the part of the predicate's float window that falls inside this item's own wear range. When the predicate has several float windows joined by an any-of group, only the windows this item's wear range reaches count. Absent when the predicate sets no float bound or the item has no float, which means 1.0.
Format"double"
maxFloatDecimal?stringmax_float as exact decimal text: the predicate's own upper bound exactly as the predicate gave it 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.
minFloat?numberLowest acceptable float (wear) value for this item, from 0.0 to 1.0: the lower end of the part of the predicate's float window that falls inside this item's own wear range. When the predicate has several float windows joined by an any-of group, only the windows this item's wear range reaches count. Absent when the predicate sets no float bound or the item has no float, which means 0.0.
Format"double"
minFloatDecimal?stringmin_float as exact decimal text: the predicate's own lower bound exactly as the predicate gave it 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.
referencePrices?array<ReferencePrice>Each valuation reference's resolved price for this item, in reference order, so the maximum price can be traced back to its source figures. Empty when the request had no valuation.
Show attributes
lastObservedAt?stringFor a stale reference, when last_value_cents was observed. Set only when outcome is stale.
Format"date-time"
lastValueCents?stringFor 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?stringThe metric read for a market data lookup. Absent for a sale computation.
observedAt?stringWhen 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?stringWhether the reference resolved a price, found only an observation older than its freshness window, or found no data at all.
Value in"REFERENCE_"REFERENCE_"REFERENCE_
priceCents?stringThe 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?integerZero-based position of the reference in the valuation's references.
Format"int32"
source?stringThe reference's market source, such as "market-csgo".
valueCents?stringThe price the source gave before the reference's adjustment, in US cents. Absent when the source had no usable data.
Format"int64"
licensedSourcesWithheld?LicensedSourcesWithheldNo 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?stringThe rule that left them out.
Value in"LICENSED_"LICENSED_"LICENSED_"LICENSED_"LICENSED_
resetsAt?stringWhen 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?stringThe licensed provider whose figures were left out.
matchedCount?integerCatalog items the predicate matches, priced or not, counted exactly as GetContractCoverage counts them. Set on the first page only, so a caller storing the evaluation's health reads it once.
Format"int32"
nextCursor?stringCursor to pass as cursor to fetch the next page. Empty when this is the last page.
unpricedCount?integerOf matched_count, the items the valuation cannot price above zero. Set on the first page only.
Format"int32"
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/EvaluateContract" \
-H "Authorization: Bearer $CSTRADER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contractId": "EBESExQVFhcYGRobHB0eHw==",
"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"
]
}
}
}
},
{
"rule": {
"marketData": {
"source": "market-csgo",
"metric": "volume"
},
"operator": "PREDICATE_OPERATOR_GTE",
"value": {
"numberValue": 5
}
}
},
{
"rule": {
"valueField": "PREDICATE_VALUE_FIELD_COMPUTED_PRICE",
"operator": "PREDICATE_OPERATOR_LTE",
"value": {
"numberValue": 150000
}
}
}
]
}
},
"valuation": {
"references": [
{
"source": "market-csgo",
"metric": "listing-price",
"adjustment": -0.05
}
],
"strategy": "VALUATION_STRATEGY_MIN"
},
"limit": 100
}'const res = await fetch("https://api.goldmine.to/analytics.v1.Analytics/EvaluateContract", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CSTRADER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"contractId": "EBESExQVFhcYGRobHB0eHw==",
"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"
]
}
}
}
},
{
"rule": {
"marketData": {
"source": "market-csgo",
"metric": "volume"
},
"operator": "PREDICATE_OPERATOR_GTE",
"value": {
"numberValue": 5
}
}
},
{
"rule": {
"valueField": "PREDICATE_VALUE_FIELD_COMPUTED_PRICE",
"operator": "PREDICATE_OPERATOR_LTE",
"value": {
"numberValue": 150000
}
}
}
]
}
},
"valuation": {
"references": [
{
"source": "market-csgo",
"metric": "listing-price",
"adjustment": -0.05
}
],
"strategy": "VALUATION_STRATEGY_MIN"
},
"limit": 100
}),
});
const data = await res.json();body := strings.NewReader(`{
"contractId": "EBESExQVFhcYGRobHB0eHw==",
"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"
]
}
}
}
},
{
"rule": {
"marketData": {
"source": "market-csgo",
"metric": "volume"
},
"operator": "PREDICATE_OPERATOR_GTE",
"value": {
"numberValue": 5
}
}
},
{
"rule": {
"valueField": "PREDICATE_VALUE_FIELD_COMPUTED_PRICE",
"operator": "PREDICATE_OPERATOR_LTE",
"value": {
"numberValue": 150000
}
}
}
]
}
},
"valuation": {
"references": [
{
"source": "market-csgo",
"metric": "listing-price",
"adjustment": -0.05
}
],
"strategy": "VALUATION_STRATEGY_MIN"
},
"limit": 100
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.goldmine.to/analytics.v1.Analytics/EvaluateContract", 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/EvaluateContract",
headers={"Authorization": f"Bearer {os.environ['CSTRADER_API_KEY']}"},
json={
"contractId": "EBESExQVFhcYGRobHB0eHw==",
"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"
]
}
}
}
},
{
"rule": {
"marketData": {
"source": "market-csgo",
"metric": "volume"
},
"operator": "PREDICATE_OPERATOR_GTE",
"value": {
"numberValue": 5
}
}
},
{
"rule": {
"valueField": "PREDICATE_VALUE_FIELD_COMPUTED_PRICE",
"operator": "PREDICATE_OPERATOR_LTE",
"value": {
"numberValue": 150000
}
}
}
]
}
},
"valuation": {
"references": [
{
"source": "market-csgo",
"metric": "listing-price",
"adjustment": -0.05
}
],
"strategy": "VALUATION_STRATEGY_MIN"
},
"limit": 100
},
)
data = res.json(){
"intents": [
{
"marketHashName": "AK-47 | Redline (Field-Tested)",
"maxBuyPriceCents": "142500",
"referencePrices": [
{
"referenceIndex": 0,
"source": "market-csgo",
"metric": "listing-price",
"valueCents": "150000",
"priceCents": "142500"
}
],
"minFloat": 0.15,
"maxFloat": 0.38
}
],
"nextCursor": "eyJtIjoiQUstNDcgfCBSZWRsaW5lIChGaWVsZC1UZXN0ZWQpIn0="
}{
"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."
}