Skip to content

API Reference / Contracts

Fetch several contracts' limits with their usage

Returns GetContractLimitUsage for many contracts in one call, alongside the IDs that did not resolve, so a contracts list reads a page of usage at once.

POST/contracts.v1.Contracts/GetContractLimitUsages

Request body

application/jsonRequired

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

contractIds?array<string>

Opaque 16-byte identifiers of the contracts, each base64-encoded in JSON. At most 200.

Response body

application/json

Success

notFoundIds?array<string>

Requested identifiers with no live contract in the caller's workspace.

usages?array<ContractLimitUsage>

One entry per configured limit of each found contract, grouped by contract in request order, then 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/GetContractLimitUsages" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractIds": [
      "EBESExQVFhcYGRobHB0eHw=="
    ]
  }'
{
  "usages": [
    {
      "contractId": "EBESExQVFhcYGRobHB0eHw==",
      "kind": "CONTRACT_LIMIT_KIND_SPEND_WINDOW",
      "scope": "CONTRACT_LIMIT_SCOPE_CONTRACT",
      "limit": "50000",
      "used": "12500",
      "remaining": "37500",
      "windowResetsAt": "2026-11-12T18:30:00Z"
    }
  ],
  "notFoundIds": []
}