Service Methods

Table of Methods

The Reporting Account Report Service has the following methods:

• GetAccountReport

• GetExcelAccountReport

Protobuf

syntax = "proto3";

package meshtrade.reporting.account_report.v1;

import "buf/validate/validate.proto";
import "google/protobuf/timestamp.proto";
import "meshtrade/iam/role/v1/role.proto";
import "meshtrade/option/v1/method_type.proto";
import "meshtrade/reporting/account_report/v1/account_report.proto";
import "meshtrade/type/v1/token.proto";

option go_package = "github.com/meshtrade/api/go/reporting/account_report/v1;account_report_v1";
option java_package = "co.meshtrade.api.reporting.account_report.v1";

/*
   The AccountReportService provides endpoints for generating and exporting
   comprehensive account activity reports.

   Clients can use this service to retrieve structured reports containing income,
   fees, and trading statements for a specified account and time period. All
   financial values within the reports are denominated in a user-specified
   reporting currency.

   Access to all service methods requires appropriate Reporting domain permissions.
*/
service AccountReportService {
  /*
     Retrieves a structured account report.

     Generates a detailed report for the given account and time range, with all
     values denominated in the specified reporting asset token.
  */
  rpc GetAccountReport(GetAccountReportRequest) returns (meshtrade.reporting.account_report.v1.AccountReport) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_REPORTING_ADMIN,
        ROLE_REPORTING_VIEWER
      ]
    };
  }

  /*
     Exports an account report as a downloadable Excel file.

     Generates the same report as GetAccountReport but returns it as a
     base64-encoded string representing an Excel (.xlsx) file.
  */
  rpc GetExcelAccountReport(GetExcelAccountReportRequest) returns (GetExcelAccountReportResponse) {
    option (meshtrade.option.v1.method_type) = METHOD_TYPE_READ;
    option (meshtrade.iam.role.v1.roles) = {
      roles: [
        ROLE_REPORTING_ADMIN,
        ROLE_REPORTING_VIEWER
      ]
    };
  }
}

/*
  Defines the parameters for requesting a structured account report.
*/
message GetAccountReportRequest {
  option (buf.validate.message).cel = {
    id: "period.chronological.get",
    message: "period_end must be on or after period_start",
    expression: "this.period_end > this.period_start"
  };

  /*
     The Account Number for which the report is requested.
     Must be a 7-digit number starting with '1'.
  */
  string account_number = 1 [(buf.validate.field) = {
    string: {
      pattern: "^1[0-9]{6}$"
    }
  }];

  /*
     The start of the reporting period (inclusive). This field is required.
  */
  google.protobuf.Timestamp period_start = 2 [(buf.validate.field).required = true];

  /*
     The end of the reporting period (inclusive). This field is required.
  */
  google.protobuf.Timestamp period_end = 3 [(buf.validate.field).required = true];

  /*
     The asset token used to valuate all financial data in the report.
     This is typically a fiat stablecoin (e.g., USDC) but can be any supported asset.
     This field is required.
  */
  meshtrade.type.v1.Token reporting_asset_token = 4 [(buf.validate.field).required = true];
}

/*
  Defines the parameters for requesting an Excel export of an account report.
*/
message GetExcelAccountReportRequest {
  option (buf.validate.message).cel = {
    id: "period.chronological.excel",
    message: "period_end must be on or after period_start",
    expression: "this.period_end >= this.period_start"
  };

  /*
     The Unique Mesh Account Number for which the report is requested.
     Must be a 7-digit number starting with '1'.
  */
  string account_number = 1 [(buf.validate.field) = {
    string: {
      pattern: "^1[0-9]{6}$"
    }
  }];

  /*
     The start of the reporting period (inclusive). This field is required.
  */
  google.protobuf.Timestamp period_start = 2 [(buf.validate.field).required = true];

  /*
     The end of the reporting period (inclusive). This field is required.
  */
  google.protobuf.Timestamp period_end = 3 [(buf.validate.field).required = true];

  /*
     The asset token used to valuate all financial data in the report.
     This is typically a fiat stablecoin (e.g., mZAR or USDC) but can be any supported asset.
     This field is required.
  */
  meshtrade.type.v1.Token reporting_asset_token = 4 [(buf.validate.field).required = true];
}

/*
  Contains the response for an Excel account report export.
*/
message GetExcelAccountReportResponse {
  /*
     The binary content of the generated Excel (.xlsx) report, encoded as a
     base64 string.
  */
  string excel_base64 = 1;
}