Skip to content

API Reference / Contracts

List contracts in a workspace

Returns a paged list of full contracts in the workspace, ordered by the requested sort field and direction. Filtering by contract type and by status, and sorting, are all applied server side, so the client passes the active tab and sort here rather than filtering a fetched page. Each page carries hydrated entities, so no follow-up GetContracts is needed.

POST/contracts.v1.Contracts/ListContracts

Request body

application/jsonRequired

Request for one page of the contracts in the caller's workspace, filtered by type, status and filter, in the requested order.

cursor?string

Opaque pagination cursor from a previous ListContractsResponse. Empty for the first page.

descending?boolean

Order descending instead of ascending.

filter?ContractFilter

Optional filters applied before paging. Timestamp ranges include from and exclude before. Snapshot bounds are inclusive.

Show attributes
accountGroupIds?array<string>

Only contracts assigned to one of these account groups, OR within the field. Empty does not restrict. A contract with no account group never matches a non-empty set.

createdBefore?string

Only contracts created before this time. Absent sets no upper bound.

Format"date-time"

createdFrom?string

Only contracts created at or after this time. Absent sets no lower bound.

Format"date-time"

evaluated?boolean

True requires a recorded successful evaluation. False requires no recorded successful evaluation. Omitted includes both.

evaluatedBefore?string

Only contracts last evaluated before this time. Contracts never evaluated do not match. Absent sets no upper bound.

Format"date-time"

evaluatedFrom?string

Only contracts last evaluated at or after this time. Contracts never evaluated do not match. Absent sets no lower bound.

Format"date-time"

problems?array<string>

Only contracts in at least one of these health conditions, OR within the field, by the same derivation that fills Contract.problems. Empty does not restrict.

Value in"CONTRACT_PROBLEM_TARGETS_OUTDATED""CONTRACT_PROBLEM_HOLDINGS_UNCONFIRMED""CONTRACT_PROBLEM_EVALUATION_FAILED""CONTRACT_PROBLEM_UNPRICED_ITEMS"

profitFrom?string

Start of the window for the realised profit sort, not a condition on which contracts match. Unset counts every sale. Read only by a list sorted by realised profit, and bound to its cursor.

Format"date-time"

query?string

Case-insensitive literal substring, not a regular expression or wildcard pattern, matched against the contract name or against the market_hash_name of any item in the contract's current intents (the items its latest evaluation targets, which already resolve weapon, paint, category, collection and referenced filter sets). A draft has no intents, so it matches by name only. Absent or empty matches every contract.

snapshotMaximum?string

Only contracts whose latest snapshot number is at most this. Absent sets no upper bound.

Format"int64"

snapshotMinimum?string

Only contracts whose latest snapshot number is at least this. Absent sets no lower bound.

Format"int64"

types?array<string>

Contract types to include, OR within the field. Empty includes every type.

Value in"CONTRACT_TYPE_BUYING""CONTRACT_TYPE_SELLING"

updatedBefore?string

Only contracts a user last edited before this time. Absent sets no upper bound.

Format"date-time"

updatedFrom?string

Only contracts a user last edited at or after this time. Absent sets no lower bound.

Format"date-time"

limit?integer

Maximum number of contracts to return. Server caps this at a service-defined upper bound.

Format"int32"

sortField?string

Field to order the page by. Unspecified orders by creation time.

Value in"CONTRACT_SORT_FIELD_CREATED_AT""CONTRACT_SORT_FIELD_NAME""CONTRACT_SORT_FIELD_UPDATED_AT""CONTRACT_SORT_FIELD_TYPE""CONTRACT_SORT_FIELD_STATUS""CONTRACT_SORT_FIELD_SNAPSHOT""CONTRACT_SORT_FIELD_EVALUATED_AT""CONTRACT_SORT_FIELD_REALIZED_PROFIT"

statuses?array<string>

Optional status set, the grouping dimension CountContracts breaks down by. Empty returns every status. Sorting and filtering are server side, so the client passes the active tab here rather than filtering a fetched page.

Value in"CONTRACT_STATUS_DRAFT""CONTRACT_STATUS_BUILDING""CONTRACT_STATUS_ACTIVE"

Response body

application/json

Success

contracts?array<Contract>

Full contracts for this page, ordered by the requested sort. A page carries the hydrated entities, not bare ids, so the caller needs no follow-up GetContracts.

Show attributes
accountGroupId?string

Opaque 16-byte identifier of the account group whose Steam accounts carry out the contract, base64-encoded in JSON. Empty when no group is assigned.

Format"byte" base64

createdAt?string

When the contract was created.

Format"date-time"

createdBy?string

Actor who created the contract. Unset when the actor carried no originating user.

Format"byte" base64

deletedAt?string

When the contract was deleted. Absent while it is live. Deleted contracts are not returned by reads.

Format"date-time"

description?string

Free-form contract description.

evaluatedAt?string

When the latest successful evaluation completed, including projection and rollup. Unset when no successful completion was recorded. An unchanged successful evaluation advances this time. A failed evaluation does not. This is independent of the configuration edit timestamp and snapshot creation time.

Format"date-time"

evaluatedConfigVersion?string

Captured contract configuration version used by the latest successful evaluation. Preserved when a later configuration edit changes version. Unset when unknown. An explicit zero is a known version.

Format"int64"

evaluatedInputGeneration?string

Opaque completed-market-feed fingerprint used by the latest successful evaluation, including a successful empty or unchanged result. Unset when provenance is unknown. This is independent of the current snapshot's original generation and does not certify independently mutable catalog, primitive observations, sales, or exchange rates.

evaluatedMatchedCount?integer

Catalog items the latest successful evaluation's rules matched, priced or not. Unset when no successful evaluation recorded it.

Format"int32"

evaluatedUnpricedCount?integer

Of evaluated_matched_count, the items the valuation could not price, so the contract cannot buy or sell them. Unset when no successful evaluation recorded it.

Format"int32"

evaluationFailedAt?string

When the latest evaluation since the last success failed. Unset when no evaluation has failed since the last success: a successful evaluation clears it.

Format"date-time"

evaluationFailureReason?string

Why the latest evaluation since the last success failed. Unspecified when evaluation_failed_at is unset. The customer-facing sentence is the client's copy for each value.

Value in"CONTRACT_EVALUATION_FAILURE_REASON_RULES_INVALID""CONTRACT_EVALUATION_FAILURE_REASON_FILTER_SET_MISSING""CONTRACT_EVALUATION_FAILURE_REASON_ANALYTICS_UNAVAILABLE""CONTRACT_EVALUATION_FAILURE_REASON_TIMED_OUT""CONTRACT_EVALUATION_FAILURE_REASON_INTERNAL"

id?string

Opaque 16-byte contract identifier, base64-encoded in JSON.

Format"byte" base64

limits?ContractLimits

Ownership and spend limits and the watchlist setting. Absent means no limits.

Show attributes
maxOwnedAtLimit?string

What happens to the contract's resting orders, offers and bids for an item when the workspace holds max_owned_per_item of it. Unspecified cancels them.

Value in"LIMIT_REACHED_ACTION_CANCEL""LIMIT_REACHED_ACTION_LEAVE"

maxOwnedPerItem?integer

Maximum copies of one item the whole workspace may hold at once, across all of its contracts. Absent means no limit.

Format"int32"

purchaseWindow?PurchaseWindow

Limit on this contract's own number of purchases in a rolling window. Absent means no limit.

Show attributes
atLimit?string

What happens to the contract's resting orders, offers and bids when this limit is reached. Unspecified cancels them.

Value in"LIMIT_REACHED_ACTION_CANCEL""LIMIT_REACHED_ACTION_LEAVE"

count?integer

Maximum number of purchases within the window. Must be greater than zero.

Format"int32"

length?string

Length of the rolling window. Must be positive.

overcommitFactor?number

How many times the remaining purchases may rest in open orders on one market while there is room: 1 never rests more than is left. From 1 to 100. Absent uses the market's default.

Format"double"

spendWindow?SpendWindow

Limit on this contract's own spend in a rolling window. Absent means no limit.

Show attributes
amountCents?string

Maximum spend within the window, in US cents. Must be greater than zero.

Format"int64"

atLimit?string

What happens to the contract's resting orders, offers and bids when this limit is reached. Unspecified cancels them.

Value in"LIMIT_REACHED_ACTION_CANCEL""LIMIT_REACHED_ACTION_LEAVE"

length?string

Length of the rolling window. Must be positive.

overcommitFactor?number

How many times the remaining spend may rest in open orders on one market while there is room: 1 never rests more than is left. From 1 to 100. Absent uses the market's default.

Format"double"

watchlist?WatchlistConfig

Whether and how far above its price the contract watches listings it cannot buy yet, for price drops. Absent means no watching.

Show attributes
ceilingPct?number

How far above the contract's maximum buy price, in percent, a listing can be and still be watched: 5 watches listings up to 5 percent over. Must be zero or more.

Format"double"

enabled?boolean

True watches near-miss listings. False watches none.

name?string

Human-readable contract name.

predicate?Predicate

Which items the contract buys or sells. May reference filter sets.

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"

problems?array<string>

Health conditions the contract is in at read time, derived by the server in enum order from this row and the workspace's ownership coverage. Empty when the contract is healthy. The same derivation serves ContractFilter.problems, so a filtered list and the badge on each row never disagree.

Value in"CONTRACT_PROBLEM_TARGETS_OUTDATED""CONTRACT_PROBLEM_HOLDINGS_UNCONFIRMED""CONTRACT_PROBLEM_EVALUATION_FAILED""CONTRACT_PROBLEM_UNPRICED_ITEMS"

selectedMarketplaces?array<string>

The markets the contract buys or sells on, by market key such as "csfloat", "dmarket" or "market-csgo", in key order. On a buying contract, empty means every market the workspace buys on, including one it turns on later: the contract buys listings on each of them and also uses every other strategy it carries. A selection buys only on the markets it names, through the strategies the contract carries there. A contract never buys on a market where the workspace has buying off. On a selling contract with listing_sell, it is where the contract lists: empty means every market the workspace sells on, a selection only the markets it names. Always empty on any other selling contract.

snapshot?string

Snapshot sequence number used to bind evaluation runs to a contract state.

Format"int64"

status?string

Contract lifecycle state.

Value in"CONTRACT_STATUS_DRAFT""CONTRACT_STATUS_BUILDING""CONTRACT_STATUS_ACTIVE"

strategies?array<ContractStrategy>

The marketplace strategies the contract buys or sells with. Each must match the contract's type.

Show attributes
csfloatAuction?CSFloatAuctionStrategy

Buy by bidding on CSFloat auctions.

Show attributes
bidBeforeExpiry?string

How long before an auction ends to place the bid. Absent uses the default.

maxConcurrentBids?integer

Accepted and not read: how many auctions a workspace bids in at once is a limit staff set on the workspace.

Format"int32"

csfloatBuyOrder?CSFloatBuyOrderStrategy

Buy by placing buy orders on CSFloat.

Show attributes
maxOrders?integer

Maximum number of buy orders open at once. Absent uses the workspace default.

Format"int32"

maxPriceCents?string

Maximum price of one buy order, in US cents. Absent uses the workspace default.

Format"int64"

csfloatOffer?CSFloatOfferStrategy

Buy by making offers on CSFloat listings.

Show attributes
expiry?string

How long an offer stays open before it expires. Absent uses the workspace default.

maxDiscountPct?number

Largest discount below the listing price to offer, in percent. Absent uses the workspace default.

Format"double"

minPriceCents?string

Lowest listing price to make offers on, in US cents. Absent uses the workspace default.

Format"int64"

csfloatScraping?CSFloatScrapingStrategy

Buy matching CSFloat listings found by scanning the marketplace.

Show attributes
maxConcurrent?integer

Maximum number of scan requests in flight at once. Absent uses the default.

Format"int32"

scrapeInterval?string

Time between scans. Absent uses the default.

csfloatSell?CSFloatSellStrategy

Sell by listing held items on CSFloat.

Show attributes
priceSource?string

Market source the listing price is based on, such as "buff163" or "steam". Absent uses the default.

undercutPct?number

How far below the lowest competing CSFloat listing to list, in percent. Absent uses the workspace default.

Format"double"

dmarketListing?DMarketListingStrategy

Buy matching DMarket listings found by searching the marketplace.

listingSell?ListingSellStrategy

Sell by listing held items on the markets the selling contract names in selected_marketplaces, or on every market the workspace sells on when it names none.

Show attributes
ceilingPct?number

Top of the price range, in percent above the valuation price: 20 allows listing up to 20 percent above it. Must be zero or more. Absent uses the workspace default.

Format"double"

undercutPct?number

How far below the cheapest competing listing to list, in percent. Must be at least zero and below 100. Absent lists one price step below it.

Format"double"

marketCsgoListing?MarketCSGOListingStrategy

Buy matching Market.CSGO listings found by searching the marketplace.

offerHandling?OfferHandlingStrategy

Sell-side handling of offers buyers make on listed items.

Show attributes
autoDecline?boolean

True declines offers automatically. Checked before the accept threshold. Absent uses the workspace default.

minOfferAcceptPct?number

Offers at or above this percent of the listing price are accepted automatically. Zero or less turns automatic acceptance off. Absent uses the workspace default.

Format"double"

saleAccept?SaleAcceptStrategy

Sell-side delay before a sale is accepted.

Show attributes
delay?string

How long to wait before accepting a sale. Zero or absent accepts immediately.

type?string

Whether the contract buys or sells. Chosen when the contract is created and cannot change.

Value in"CONTRACT_TYPE_BUYING""CONTRACT_TYPE_SELLING"

updatedAt?string

When the user last edited contract configuration. System evaluation and lifecycle changes do not advance this timestamp.

Format"date-time"

updatedBy?string

Actor who last updated the contract. Unset when the actor carried no originating user.

Format"byte" base64

valuation?Valuation

How the contract prices each matched item: the most it pays when buying, or its listing price when selling. Absent only on a draft. A contract cannot be activated without one.

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"

version?string

The contract's settings version shown to users, such as Version 12, and the optimistic concurrency token for edits. Every user edit increments it. System evaluation snapshot and status changes do not.

Format"int64"

workspaceId?string

Workspace the contract belongs to.

Format"byte" base64

nextCursor?string

Cursor to pass to fetch the next page. Empty when there are no more results.

curl -X POST "https://api.goldmine.to/contracts.v1.Contracts/ListContracts" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50,
    "cursor": "",
    "filter": {
      "types": [
        "CONTRACT_TYPE_BUYING"
      ]
    },
    "statuses": [
      "CONTRACT_STATUS_ACTIVE",
      "CONTRACT_STATUS_BUILDING"
    ],
    "sortField": "CONTRACT_SORT_FIELD_NAME"
  }'
{
  "contracts": [
    {
      "id": "EBESExQVFhcYGRobHB0eHw==",
      "workspaceId": "AAECAwQFBgcICQoLDA0ODw==",
      "name": "AK-47 under $50",
      "status": "CONTRACT_STATUS_ACTIVE",
      "type": "CONTRACT_TYPE_BUYING",
      "version": "3"
    }
  ],
  "nextCursor": ""
}