Operate

Statements and Confirms

MyStocks Partner API

Build customer and partner statements from MyStocks ledgers, executions, fees, dividends, tax lots, and activity records.

Integration guides Get a sandbox key

Explore endpoints

24 of 24

GET

/users/{userId}/gains

Realized capital gains (sub-account)

Full endpoint documentation

Sandbox availablegetSubAccountGains

Realized gains/losses for a sub-account — each disposal FIFO-matched to its acquiring lot, with acquisition + disposal dates, cost basis, proceeds, holding period, and gain. Feed a capital-gains tax statement.

Parameters

userIdstringpathRequired

Example: usr_abc123

symbolstringquery

fromstringquery

tostringquery

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

subAccountIdstring | null

accountTypestring

currencystring

Example: "USD"

methodFIFO

countinteger

totalProceedsUsdnumber

totalCostUsdnumber

realizedGainUsdnumber

periodobject

period.fromstring | null

period.tostring | null

disposalsobject[]

disposals[].symbolstring

disposals[].exchangestring | null

disposals[].quantitynumber

disposals[].acquiredAtstring | null

disposals[].disposedAtstring | null

disposals[].holdingPeriodDaysinteger | null

disposals[].costBasisUsdnumber

disposals[].proceedsUsdnumber

disposals[].gainUsdnumber

disposals[].methodFIFO

disposals[].buyOrderIdstring

disposals[].sellOrderIdstring

Response codes

200Realized disposals.

404Sub-account not found.

Sandbox playground

Read-only sandbox request

userId Required · pathsymbol Optional · queryfrom Optional · queryto Optional · querySandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/gains

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "description": "Realized capital gains/losses, each disposal FIFO-matched to its lot.",
  "properties": {
    "subAccountId": {
      "type": [
        "string",
        "null"
      ]
    },
    "accountType": {
      "type": "string"
    },
    "currency": {
      "type": "string",
      "example": "USD"
    },
    "method": {
      "type": "string",
      "enum": [
        "FIFO"
      ]
    },
    "count": {
      "type": "integer"
    },
    "totalProceedsUsd": {
      "type": "number"
    },
    "totalCostUsd": {
      "type": "number"
    },
    "realizedGainUsd": {
      "type": "number"
    },
    "period": {
      "type": "object",
      "properties": {
        "from": {
          "type": [
            "string",
            "null"
          ]
        },
        "to": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "disposals": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string"
          },
          "exchange": {
            "type": [
              "string",
              "null"
            ]
          },
          "quantity": {
            "type": "number"
          },
          "acquiredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "disposedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "holdingPeriodDays": {
            "type": [
              "integer",
              "null"
            ]
          },
          "costBasisUsd": {
            "type": "number"
          },
          "proceedsUsd": {
            "type": "number"
          },
          "gainUsd": {
            "type": "number"
          },
          "method": {
            "type": "string",
            "enum": [
              "FIFO"
            ]
          },
          "buyOrderId": {
            "type": "string"
          },
          "sellOrderId": {
            "type": "string"
          }
        }
      }
    }
  }
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/gains' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY"

MyStocks exposes source records for statements rather than prescribing your customer-facing statement layout. Combine the period-specific report endpoints with order executions and the client-activity feed.

Statement inputs

Purpose	Endpoint
Customer activity	`GET /client-activity`
Account transactions	`GET /users/{userId}/transactions`
Order and fill confirms	`GET /users/{userId}/orders/{orderId}/executions`
Positions	`GET /report/positions` or the sub-account portfolio endpoint
Fees and markup	`GET /report/fees` and `GET /report/revenue`
Dividends	`GET /report/dividends` and `GET /dividends/{symbol}/history`
Tax records	`GET /users/{userId}/tax-lots` and `GET /users/{userId}/gains`
Partner invoice	`GET /report/invoice?month=YYYY-MM`

Recommended statement model

Store the source period, account identifier, symbol, currency, quantity, unit price, gross value, fees, FX metadata, order ID, execution sequence, event IDs, and request ID. Keep pending, settled, rejected, and cancelled states distinct.

For customer statements, clearly distinguish:

order acceptance from execution;
execution from settlement;
settled cash from unsettled proceeds;
local-market price from USD wallet impact;
MyStocks records from your own fees or disclosures.

Use the Daily Reconciliation process to verify statement totals before publication.

Was this page useful?

Your signal helps us tighten partner onboarding docs.

Send note

Last updated on

Daily Processes and Reconciliation

SLA & Health