Skip to content

API Reference / Contracts

Fetch a contract's limits with their usage

Returns each configured buying limit of a contract beside how much of it is used now, counted by the same rules buying enforces: copies held per item across the workspace, and this contract's purchases and spend in its rolling windows with when room frees up. Whether holdings can be confirmed at all is GetOwnershipCoverage.

POST/contracts.v1.Contracts/GetContractLimitUsage

Request body

application/jsonRequired

Request for the configured limits of one contract in the caller's workspace, each with its current usage.

contractIdstring

Contract identifier.

Format"byte" base64

Response body

application/json

Success

usages?array<ContractLimitUsage>

One entry per configured limit, in kind order.

Show attributes
contractId?string

The contract the limit belongs to.

Format"byte" base64

kind?string

Which limit this is.

Value in"CONTRACT_LIMIT_KIND_MAX_OWNED_PER_ITEM""CONTRACT_LIMIT_KIND_PURCHASE_WINDOW""CONTRACT_LIMIT_KIND_SPEND_WINDOW"

limit?string

The configured limit: copies per item, purchases in the window, or cents in the window.

Format"int64"

remaining?string

For a window, how much is left before it blocks buying (never negative). For max owned per item, how many of the contract's items are still under the limit.

Format"int64"

scope?string

What the limit counts across: the whole workspace for max owned per item, this contract alone for the two windows.

Value in"CONTRACT_LIMIT_SCOPE_WORKSPACE""CONTRACT_LIMIT_SCOPE_CONTRACT"

used?string

For a window, the purchases or cents counted in it now. For max owned per item, how many of the contract's items the workspace already holds at or over the limit, which buying skips.

Format"int64"

windowResetsAt?string

For a window with counted purchases, when the oldest of them leaves the window and frees room. Unset for max owned per item and for an empty window.

Format"date-time"

curl -X POST "https://api.goldmine.to/contracts.v1.Contracts/GetContractLimitUsage" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": "EBESExQVFhcYGRobHB0eHw=="
  }'
{
  "usages": [
    {
      "contractId": "EBESExQVFhcYGRobHB0eHw==",
      "kind": "CONTRACT_LIMIT_KIND_PURCHASE_WINDOW",
      "scope": "CONTRACT_LIMIT_SCOPE_CONTRACT",
      "limit": "10",
      "used": "3",
      "remaining": "7",
      "windowResetsAt": "2026-11-10T09:00:00Z"
    }
  ]
}