API Reference / Contracts
Get profit over time for several contracts
Returns each contract's profit per day, week or month over one range, for up to 100 contracts in one read.
/ contracts. v1. Contracts/ GetContractPnLPeriodsRequest body
application/jsonRequired
Request for the profit per period of up to 100 contracts in the caller's workspace.
contractIdsarray<string>The contracts to read, at most 100. A contract outside the caller's workspace, or deleted, is left out of the response.
endTimestringEnd of the period range.
Format"date-time"
granularitystringTime bucket size for every series.
Value in"PNL_"PNL_"PNL_"PNL_
startTimestringStart of the period range.
Format"date-time"
Response body
application/json
Success
contracts?array<ContractPnLPeriods>One series per contract found.
Show attributes
contractId?stringThe contract.
Format"byte" base64
periods?array<PnLPeriod>The series, one entry per bucket across the range in time order, with zeroes for a bucket with no activity.
Show attributes
buyCostCents?stringCost of items purchased during this period, in cents: the sum of listing_price_cents for purchases made in this time bucket.
Format"int64"
buyCostMicros?stringbuy_cost_cents in millionths of a dollar, summed from the exact buy prices. Exact to the millionth of a dollar, so a purchase charged a fraction of a cent counts at what it cost. The _cents figure beside it sums prices rounded up to a cent and is kept for limits.
Format"int64"
lostCostCents?stringThe buy cost of the items lost in this period, in cents, bucketed by when they were lost. Pnl_cents already subtracts it.
Format"int64"
lostCostMicros?stringlost_cost_cents in millionths of a dollar, from the exact buy prices.
Format"int64"
marketplaces?array<PnLPeriodMarketplace>The period's realised profit split by selling marketplace, present only when the request set group_by_marketplace. The entries sum to pnl_cents. A sale whose marketplace is unknown is grouped as "unknown".
Show attributes
marketplace?stringThe selling market that settled the sales. "unknown" when the sale predates selling_marketplace and cannot be attributed.
pnlCents?stringRealised profit for the items this market settled in the period, in cents: sell revenue minus the buy cost of those same sold items.
Format"int64"
pnlMicros?stringpnl_cents in millionths of a dollar, from the exact buy cost. Exact to the millionth of a dollar, so a purchase charged a fraction of a cent counts at what it cost. The _cents figure beside it sums prices rounded up to a cent and is kept for limits.
Format"int64"
periodEnd?stringEnd of this period's time bucket, inclusive.
Format"date-time"
periodStart?stringStart of this period's time bucket, inclusive.
Format"date-time"
pnlCents?stringRealised profit for items sold during this period, in cents: sell revenue minus buy cost for those same sold items, bucketed by sale completion time, minus the cost of the items lost in the period (lost_cost_cents), bucketed by when they were lost.
Format"int64"
pnlMicros?stringpnl_cents in millionths of a dollar: sell revenue minus the exact buy cost of those sold items and of the items lost in the period. Exact to the millionth of a dollar, so a purchase charged a fraction of a cent counts at what it cost. The _cents figure beside it sums prices rounded up to a cent and is kept for limits.
Format"int64"
purchaseCount?stringNumber of purchases made during this period.
Format"int64"
saleCount?stringNumber of items sold during this period, bucketed by sale completion time and credited to a contract as sell_revenue_cents is. Lost items are not sales and are not counted.
Format"int64"
sellRevenueCents?stringRealised sell revenue for items sold during this period, in cents: the sum of sell_price_cents for sales completed in this time bucket.
Format"int64"
strategies?array<PnLPeriodStrategy>The period's purchases split by the buying mechanism that produced each one, present only when the request set group_purchases_by_strategy. The entries sum to purchase_count.
Show attributes
purchaseCount?stringNumber of purchases this mechanism made during the period.
Format"int64"
strategy?stringThe buying mechanism that produced the purchases.
Value in"PURCHASE_"PURCHASE_"PURCHASE_"PURCHASE_
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.
curl -X POST "https://api.goldmine.to/contracts.v1.Contracts/GetContractPnLPeriods" \
-H "Authorization: Bearer $CSTRADER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contractIds": [
"AY86PB0ufwCKGyw9Tl9gcQ=="
],
"endTime": "2026-11-03T16:10:00Z",
"granularity": "PNL_GRANULARITY_DAY",
"startTime": "2026-11-03T16:10:00Z"
}'const res = await fetch("https://api.goldmine.to/contracts.v1.Contracts/GetContractPnLPeriods", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CSTRADER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"contractIds": [
"AY86PB0ufwCKGyw9Tl9gcQ=="
],
"endTime": "2026-11-03T16:10:00Z",
"granularity": "PNL_GRANULARITY_DAY",
"startTime": "2026-11-03T16:10:00Z"
}),
});
const data = await res.json();body := strings.NewReader(`{
"contractIds": [
"AY86PB0ufwCKGyw9Tl9gcQ=="
],
"endTime": "2026-11-03T16:10:00Z",
"granularity": "PNL_GRANULARITY_DAY",
"startTime": "2026-11-03T16:10:00Z"
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.goldmine.to/contracts.v1.Contracts/GetContractPnLPeriods", 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/contracts.v1.Contracts/GetContractPnLPeriods",
headers={"Authorization": f"Bearer {os.environ['CSTRADER_API_KEY']}"},
json={
"contractIds": [
"AY86PB0ufwCKGyw9Tl9gcQ=="
],
"endTime": "2026-11-03T16:10:00Z",
"granularity": "PNL_GRANULARITY_DAY",
"startTime": "2026-11-03T16:10:00Z"
},
)
data = res.json(){
"contracts": [
{
"contractId": "AY86PB0ufwCKGyw9Tl9gcQ==",
"periods": [
{}
]
}
]
}{
"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."
}