Broker API

Custody and Beneficial Ownership

MyStocks Partner API

Understand omnibus custody, per-sub-account beneficial ownership, settlement, and custody reconciliation in the MyStocks operating model.

Integration guides Get a sandbox key

Explore endpoints

1 of 1

GET

/report/reconciliation

Report - Reconciliation suite

Full endpoint documentation

Sandbox availablegetReconciliationReport

Daily reconciliation pack for B2B operations. Returns cash ledger, securities ledger, unsettled trades, fees, dividends, corporate actions, and custody position files for the partner master account and all sub-accounts. Add format=csv&section=... to download a section as CSV for finance, SFTP mirroring, or data warehouse ingestion. JSON responses include an explicit cash roll-forward, data-quality controls, and customer-sub-ledger-versus-MyStocks-omnibus proof. A status of EXCEPTIONS identifies unit or invalid-value differences; INCOMPLETE means no MyStocks omnibus positions were available for comparison. Sandbox returns current virtual wallets and holdings for the master and at most 500 sub-accounts, with null custody totals and INCOMPLETE status. Sandbox historical dates and from/to receive 422; section filtering receives 400. Sandbox format=csv exports current account totals. Neither this Sandbox report nor an internal ledger alone proves external settlement.

Parameters

asOfstringquery

Single business date to reconcile. Overrides default today when from/to are omitted.

Example: 2026-06-30

fromstringquery

tostringquery

formatjson | csvquery

Example: json

CSV export section.

limitintegerquery

Per-account transaction/order scan limit.

Example: 1000

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

See the response format and API Reference for this endpoint.

Response codes

200Reconciliation report or CSV file.

422Sandbox historical report or account limit unsupported.

Sandbox playground

Read-only sandbox request

asOf Optional · queryfrom Optional · queryto Optional · queryformat Optional · querysection Optional · querylimit Optional · querySandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/report/reconciliation

Open in API Tester API Reference

Response schema

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "partnerKey": {
          "type": "string"
        },
        "period": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "format": "date"
            },
            "to": {
              "type": "string",
              "format": "date"
            }
          }
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "exportManifest": {
          "type": "object",
          "description": "Pointers to the JSON and per-section CSV variants of this report.",
          "properties": {
            "api": {
              "type": "string",
              "example": "/api/v1/partner/report/reconciliation"
            },
            "csv": {
              "type": "string",
              "example": "/api/v1/partner/report/reconciliation?format=csv&section={cash|securities|unsettled|fees|dividends|corporate_actions|custody_positions}"
            },
            "sftpEligible": {
              "type": "boolean"
            }
          }
        },
        "summary": {
          "type": "object",
          "properties": {
            "accountCount": {
              "type": "integer"
            },
            "closingCashBalance": {
              "type": "number"
            },
            "closingSecuritiesValue": {
              "type": "number"
            },
            "unsettledTradeCount": {
              "type": "integer"
            },
            "unsettledBuyAmount": {
              "type": "number"
            },
            "unsettledSellAmount": {
              "type": "number"
            },
            "totalFees": {
              "type": "number"
            },
            "totalDividends": {
              "type": "number"
            },
            "custodyPositionCount": {
              "type": "integer"
            },
            "corporateActionCount": {
              "type": "integer"
            },
            "reconciliationStatus": {
              "type": "string",
              "enum": [
                "BALANCED",
                "EXCEPTIONS",
                "INCOMPLETE"
              ]
            },
            "custodyExceptionCount": {
              "type": "integer"
            }
          }
        },
        "proof": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "BALANCED",
                "EXCEPTIONS",
                "INCOMPLETE"
              ]
            },
            "cashRollForward": {
              "type": "object",
              "properties": {
                "closingCashBalance": {
                  "type": "number"
                },
                "completedCredits": {
                  "type": "number"
                },
                "completedDebits": {
                  "type": "number"
                },
                "netMovement": {
                  "type": "number"
                },
                "derivedOpeningCashBalance": {
                  "type": "number"
                },
                "equation": {
                  "type": "string"
                }
              }
            },
            "custody": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "BALANCED",
                    "EXCEPTIONS",
                    "INCOMPLETE"
                  ]
                },
                "comparedInstrumentCount": {
                  "type": "integer"
                },
                "beneficialUnits": {
                  "type": "number"
                },
                "custodyUnits": {
                  "type": "number"
                },
                "exceptions": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "instrumentId": {
                        "type": "string"
                      },
                      "beneficialUnits": {
                        "type": "number"
                      },
                      "custodyUnits": {
                        "type": "number"
                      },
                      "differenceUnits": {
                        "type": "number"
                      }
                    }
                  }
                }
              }
            },
            "notes": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "accounts": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "One account (master or sub-account) covered by the reconciliation report.",
            "properties": {
              "userId": {
                "type": "string"
              },
              "accountType": {
                "type": "string",
                "enum": [
                  "MASTER",
                  "SUBACCOUNT"
                ]
              },
              "externalId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Your identifier for the sub-account, if set. Null for the master account."
              },
              "displayName": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        },
        "cashLedger": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "One wallet transaction in the reconciliation period. The fees and dividends arrays reuse this shape (filtered to type FEE and DISTRIBUTION/DIVIDEND respectively).",
            "properties": {
              "userId": {
                "type": "string"
              },
              "accountType": {
                "type": "string",
                "enum": [
                  "MASTER",
                  "SUBACCOUNT"
                ]
              },
              "externalId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "transactionId": {
                "type": "string"
              },
              "type": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Transaction type, e.g. DEPOSIT, WITHDRAWAL, INVEST, FEE, DISTRIBUTION."
              },
              "status": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "direction": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "CREDIT or DEBIT where recorded."
              },
              "amount": {
                "type": "number"
              },
              "currency": {
                "type": "string",
                "example": "USD"
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceType": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "createdAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "settledAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        },
        "securitiesLedger": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "One holding row in the securities ledger, valued in USD.",
            "properties": {
              "userId": {
                "type": "string"
              },
              "accountType": {
                "type": "string",
                "enum": [
                  "MASTER",
                  "SUBACCOUNT"
                ]
              },
              "externalId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "symbol": {
                "type": "string",
                "example": "SCOM.KE"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "exchange": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceType": {
                "type": "string",
                "example": "LISTED_STOCK"
              },
              "sourceId": {
                "type": "string"
              },
              "units": {
                "type": "number"
              },
              "reservedUnits": {
                "type": "number",
                "description": "Units locked by open SELL orders."
              },
              "costBasis": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "amountInvested": {
                "type": "number"
              },
              "currentValue": {
                "type": "number"
              },
              "currency": {
                "type": "string",
                "example": "USD"
              },
              "localCurrency": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "updatedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          }
        },
        "unsettledTrades": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "One open (PENDING/PROCESSING) trade order awaiting settlement.",
            "properties": {
              "userId": {
                "type": "string"
              },
              "accountType": {
                "type": "string",
                "enum": [
                  "MASTER",
                  "SUBACCOUNT"
                ]
              },
              "externalId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "orderId": {
                "type": "string"
              },
              "clientOrderId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "quoteId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "type": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "BUY",
                  "SELL",
                  null
                ]
              },
              "symbol": {
                "type": "string"
              },
              "exchange": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status": {
                "type": "string",
                "example": "PENDING"
              },
              "quantity": {
                "type": "number"
              },
              "filledQuantity": {
                "type": "number"
              },
              "remainingQuantity": {
                "type": "number"
              },
              "totalAmount": {
                "type": "number"
              },
              "feeAmount": {
                "type": "number"
              },
              "settlementUsdPrice": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "createdAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "settledAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "omsStatus": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        },
        "fees": {
          "type": "array",
          "description": "Cash-ledger entries with type FEE.",
          "items": {
            "type": "object",
            "description": "One wallet transaction in the reconciliation period. The fees and dividends arrays reuse this shape (filtered to type FEE and DISTRIBUTION/DIVIDEND respectively).",
            "properties": {
              "userId": {
                "type": "string"
              },
              "accountType": {
                "type": "string",
                "enum": [
                  "MASTER",
                  "SUBACCOUNT"
                ]
              },
              "externalId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "transactionId": {
                "type": "string"
              },
              "type": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Transaction type, e.g. DEPOSIT, WITHDRAWAL, INVEST, FEE, DISTRIBUTION."
              },
              "status": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "direction": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "CREDIT or DEBIT where recorded."
              },
              "amount": {
                "type": "number"
              },
              "currency": {
                "type": "string",
                "example": "USD"
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceType": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "createdAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "settledAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        },
        "dividends": {
          "type": "array",
          "description": "Cash-ledger entries with type DISTRIBUTION or DIVIDEND.",
          "items": {
            "type": "object",
            "description": "One wallet transaction in the reconciliation period. The fees and dividends arrays reuse this shape (filtered to type FEE and DISTRIBUTION/DIVIDEND respectively).",
            "properties": {
              "userId": {
                "type": "string"
              },
              "accountType": {
                "type": "string",
                "enum": [
                  "MASTER",
                  "SUBACCOUNT"
                ]
              },
              "externalId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "transactionId": {
                "type": "string"
              },
              "type": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Transaction type, e.g. DEPOSIT, WITHDRAWAL, INVEST, FEE, DISTRIBUTION."
              },
              "status": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "direction": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "CREDIT or DEBIT where recorded."
              },
              "amount": {
                "type": "number"
              },
              "currency": {
                "type": "string",
                "example": "USD"
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceType": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "createdAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "settledAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        },
        "corporateActions": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "Corporate action affecting a symbol held by a reported account in the period.",
            "properties": {
              "id": {
                "type": "string"
              },
              "symbol": {
                "type": "string"
              },
              "type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "SPLIT"
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "exDate": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "recordDate": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "payDate": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "amount": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "currency": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "createdAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          }
        },
        "custodyPositions": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "Custody register entry for an account's beneficially-owned position.",
            "properties": {
              "positionId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "accountType": {
                "type": "string",
                "enum": [
                  "MASTER",
                  "SUBACCOUNT"
                ]
              },
              "externalId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "instrumentId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "legalHolder": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "beneficialOwner": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "unitsHeld": {
                "type": "number"
              },
              "averageCost": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "currency": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "accruedInterest": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "status": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "updatedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          }
        }
      },
      "required": [
        "partnerKey",
        "period",
        "summary",
        "proof"
      ]
    },
    {
      "type": "object",
      "required": [
        "reconciliationId",
        "asOf",
        "generatedAt",
        "status",
        "cash",
        "positions",
        "accounts",
        "accountCount",
        "valuationBasis",
        "exceptions",
        "fixture",
        "sandbox",
        "note"
      ],
      "properties": {
        "reconciliationId": {
          "type": "string"
        },
        "asOf": {
          "type": "string"
        },
        "generatedAt": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "INCOMPLETE"
          ]
        },
        "cash": {
          "type": "object",
          "required": [
            "ledgerUsd",
            "custodyUsd",
            "differenceUsd"
          ],
          "properties": {
            "ledgerUsd": {
              "type": "number"
            },
            "custodyUsd": {
              "type": "null"
            },
            "differenceUsd": {
              "type": "null"
            }
          }
        },
        "positions": {
          "type": "object",
          "required": [
            "ledgerMarketValueUsd",
            "custodyMarketValueUsd",
            "differenceUsd"
          ],
          "properties": {
            "ledgerMarketValueUsd": {
              "type": "number"
            },
            "custodyMarketValueUsd": {
              "type": "null"
            },
            "differenceUsd": {
              "type": "null"
            }
          }
        },
        "accounts": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "accountId",
              "accountType",
              "cashBalance",
              "positions"
            ],
            "properties": {
              "accountId": {
                "type": "string"
              },
              "accountType": {
                "type": "string",
                "enum": [
                  "MASTER",
                  "SUBACCOUNT"
                ]
              },
              "cashBalance": {
                "type": "number"
              },
              "positions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "symbol",
                    "units",
                    "valueUsd"
                  ],
                  "properties": {
                    "symbol": {
                      "type": "string"
                    },
                    "units": {
                      "type": "number"
                    },
                    "valueUsd": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          }
        },
        "accountCount": {
          "type": "integer"
        },
        "valuationBasis": {
          "type": "string",
          "enum": [
            "current_virtual_wallets_and_holdings"
          ]
        },
        "exceptions": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        },
        "fixture": {
          "type": "boolean",
          "enum": [
            false
          ]
        },
        "sandbox": {
          "type": "boolean",
          "enum": [
            true
          ]
        },
        "note": {
          "type": "string"
        }
      }
    }
  ]
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/report/reconciliation' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY"

MyStocks maintains the per-sub-account beneficial-ownership ledger. Regulated brokers, custodians, and the relevant CSD hold and settle securities according to each market’s rules.

What the API represents

A filled order is an execution event; it is not automatically settled custody.
Unsettled sell proceeds remain unavailable for withdrawal until the relevant settlement condition is met.
Portfolio and holdings endpoints show the per-sub-account ledger.
The custody section of GET /report/reconciliation compares pooled custody positions with the sum of attributed sub-account holdings.
Corporate actions and dividends are distributed through account records and signed events.

Daily custody control

Pull securities and custody_positions sections from the reconciliation pack.
Compare total units by symbol and market with the custodian/CSD file.
Import the dated broker/CSD cash and position statement through the authorized MyStocks operations control.
Require BALANCED external reconciliation evidence within 36 hours for GA. Missing external files are INCOMPLETE; any unit or cash difference is EXCEPTIONS and must not be waived silently.
Break differences down by sub-account, pending order, settlement date, and corporate action.
Record the exception and do not silently overwrite the beneficial-ownership ledger.
Close the exception only after a corrected source record or operations confirmation.

MyStocks is a technology and orchestration platform, not a broker-dealer. The executing broker and custodian for a market are disclosed through the applicable contractual and operational process. See Architecture & Custody and Going Live.

Was this page useful?

Your signal helps us tighten partner onboarding docs.

Send note

Last updated on

FX & Currency

Customer ownership and omnibus custody