CalculateTransferFee

Calculates the transfer fee for a given transfer amount. Returns the calculated fee amount, VAT amount and VAT rate that would be applied to a transfer of the specified amount.

Overview

Method Options

Authorisation specification of the CalculateTransferFee method.

Type	METHOD_TYPE_READ
Access Level	METHOD_ACCESS_LEVEL_AUTHORISED
Roles	ROLE_WALLET_ADMIN ROLE_WALLET_VIEWER ROLE_WALLET_TRANSFER_ADMIN ROLE_WALLET_TRANSFER_VIEWER

Parameters

Request and response parameter message overview:

Input: CalculateTransferFeeRequest Message

Field	Type	Required	Description
Amount	meshtrade.type.v1.Amount	True	The transfer amount to calculate fees for.

Returns: CalculateTransferFeeResponse Message

Field	Type	Description
FeeAmount	meshtrade.type.v1.Amount	The calculated fee amount for the transfer.
VatAmount	meshtrade.type.v1.Amount	The VAT amount calculated on the fee.
VatRate	meshtrade.type.v1.Decimal	The VAT rate used for the fee calculation.

Protobuf

syntax = "proto3";

package meshtrade.wallet.transfer.v1;

import "buf/validate/validate.proto";
import "meshtrade/option/method_options/v1/method_options.proto";
import "meshtrade/type/v1/amount.proto";
import "meshtrade/type/v1/decimal.proto";
import "meshtrade/type/v1/sorting.proto";
import "meshtrade/wallet/transfer/v1/transfer.proto";

option go_package = "github.com/meshtrade/api/go/wallet/transfer/v1;transfer_v1";
option java_package = "co.meshtrade.api.wallet.transfer.v1";

/*
   TransferService manages asset transfers.

   Service allows for the creation and retrieval of transfers. It can also be used
   to monitor transfers to react to state changes.
*/
service TransferService {
  /*
     Transfer creates a transfer entity and executes a transfer on chain
  */
  rpc CreateTransfer(CreateTransferRequest) returns (meshtrade.wallet.transfer.v1.Transfer) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_TRANSFER_ADMIN
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Retrieves a specific transfer by its resource identifier.
  */
  rpc GetTransfer(GetTransferRequest) returns (meshtrade.wallet.transfer.v1.Transfer) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_TRANSFER_ADMIN,
        ROLE_WALLET_TRANSFER_VIEWER
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Retrieves all transfers associated with a ledger account address.

     Finds all transfers where the given ledger account address was either in the to or from field.
  */
  rpc SearchTransfersByAddress(SearchTransfersByAddressRequest) returns (SearchTransfersByAddressResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_TRANSFER_ADMIN,
        ROLE_WALLET_TRANSFER_VIEWER
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Lists all transfers within the authenticated group's hierarchical scope.

     Returns the complete set of transfers accessible to the executing context,
     including transfers owned by the group and all descendant groups.
  */
  rpc ListTransfers(ListTransfersRequest) returns (ListTransfersResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_TRANSFER_ADMIN,
        ROLE_WALLET_TRANSFER_VIEWER
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Monitors a transfer for real-time updates.

     Supports lookup by either resource name.
     Returns a stream of transfer states as they change.
  */
  rpc MonitorTransfer(MonitorTransferRequest) returns (stream Transfer) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_TRANSFER_ADMIN,
        ROLE_WALLET_TRANSFER_VIEWER
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Calculates the transfer fee for a given transfer amount.

     Returns the calculated fee amount, VAT amount and VAT rate
     that would be applied to a transfer of the specified amount.
  */
  rpc CalculateTransferFee(CalculateTransferFeeRequest) returns (CalculateTransferFeeResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_WALLET_ADMIN,
        ROLE_WALLET_VIEWER,
        ROLE_WALLET_TRANSFER_ADMIN,
        ROLE_WALLET_TRANSFER_VIEWER
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }
}

/*
   Request to create a transfer.
*/
message CreateTransferRequest {
  /*
     The transfer configuration for creation.
     The name, number, ledger_id, and owners fields will be ignored and assigned by the system.
  */
  meshtrade.wallet.transfer.v1.Transfer transfer = 1 [(buf.validate.field) = {required: true}];
}

message GetTransferRequest {
  /*
     The resource name of the transfer to retrieve.
     Format: wallet/transfers/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    string: {pattern: "^wallet/transfers/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"}
  }];
}

message SearchTransfersByAddressRequest {
  /*
     The ledger address of the account
  */
  string address = 1 [(buf.validate.field) = {
    required: true
    string: {max_len: 255}
  }];
}

message SearchTransfersByAddressResponse {
  repeated Transfer transfers = 1;
}

message ListTransfersRequest {
  /*
     Sorting configuration for organizing results.
  */
  message Sorting {
    /*
       Field to sort by.
       Supported values: "number" or empty string for default ordering.
    */
    string field = 1 [(buf.validate.field) = {
      string: {
        in: [
          "",
          "number"
        ]
      }
      cel: {
        id: "field.valid"
        message: "field must be one of: number, or empty"
        expression: "this in ['', 'number']"
      }
    }];

    /*
       Sort order for results.
    */
    meshtrade.type.v1.SortingOrder order = 2;
  }

  /*
     Optional sorting configuration.
  */
  Sorting sorting = 1;
}

message ListTransfersResponse {
  repeated Transfer transfers = 1;
}

/*
   Request to monitor a transfer.
*/
message MonitorTransferRequest {
  /*
     The resource name of the transfer to monitor.
     Format: wallet/transfers/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    string: {pattern: "^wallet/transfers/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"}
  }];
}

/*
   Request to calculate the transfer fee for a given amount.
*/
message CalculateTransferFeeRequest {
  /*
     The transfer amount to calculate fees for.
  */
  meshtrade.type.v1.Amount amount = 1 [(buf.validate.field) = {required: true}];
}

/*
   Response containing the calculated transfer fee breakdown.
*/
message CalculateTransferFeeResponse {
  /*
     The calculated fee amount for the transfer.
  */
  meshtrade.type.v1.Amount fee_amount = 1;

  /*
     The VAT amount calculated on the fee.
  */
  meshtrade.type.v1.Amount vat_amount = 2;

  /*
     The VAT rate used for the fee calculation.
  */
  meshtrade.type.v1.Decimal vat_rate = 3;
}

Code Examples

Select supported SDK in the language of your choice for a full example of how to invoke the this method:

Go

package main

import (
	"context"
	"log"

	typev1 "github.com/meshtrade/api/go/type/v1"
	transferv1 "github.com/meshtrade/api/go/wallet/transfer/v1"
)

func main() {
	ctx := context.Background()

	// Default configuration is used and credentials come from MESH_API_CREDENTIALS
	// environment variable or default discovery methods. Zero config required
	// unless you want custom configuration.
	service, err := transferv1.NewTransferService()
	if err != nil {
		log.Fatalf("Failed to create service: %v", err)
	}
	defer service.Close()

	// Create request with the transfer amount to calculate fees for
	request := &transferv1.CalculateTransferFeeRequest{
		Amount: &typev1.Amount{
			Token: &typev1.Token{
				Code:   "USDC",
				Issuer: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
				Ledger: typev1.Ledger_LEDGER_STELLAR,
			},
			Value: &typev1.Decimal{Value: "1000.00"},
		},
	}

	// Call the CalculateTransferFee method
	response, err := service.CalculateTransferFee(ctx, request)
	if err != nil {
		log.Fatalf("CalculateTransferFee failed: %v", err)
	}

	// Display the fee breakdown
	log.Printf("Transfer fee breakdown:")
	log.Printf("  Fee Amount: %s %s", response.FeeAmount.Value.Value, response.FeeAmount.Token.Code)
	log.Printf("  VAT Amount: %s %s", response.VatAmount.Value.Value, response.VatAmount.Token.Code)
	log.Printf("  VAT Rate: %s", response.VatRate.Value)
}

Python

from meshtrade.type.v1 import Amount, Decimal, Ledger, Token
from meshtrade.wallet.transfer.v1 import (
    CalculateTransferFeeRequest,
    TransferService,
)


def main():
    # Default configuration is used and credentials come from MESH_API_CREDENTIALS
    # environment variable or default discovery methods. Zero config required
    # unless you want custom configuration.
    service = TransferService()

    with service:
        # Create request with the transfer amount to calculate fees for
        request = CalculateTransferFeeRequest(
            amount=Amount(
                token=Token(
                    code="USDC",
                    issuer="GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
                    ledger=Ledger.LEDGER_STELLAR,
                ),
                value=Decimal(value="1000.00"),
            ),
        )

        # Call the CalculateTransferFee method
        response = service.calculate_transfer_fee(request)

        # Display the fee breakdown
        print("Transfer fee breakdown:")
        print(f"  Fee Amount: {response.fee_amount.value.value} {response.fee_amount.token.code}")
        print(f"  VAT Amount: {response.vat_amount.value.value} {response.vat_amount.token.code}")
        print(f"  VAT Rate: {response.vat_rate.value}")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.type.v1.Amount.Amount;
import co.meshtrade.api.type.v1.Decimal.Decimal;
import co.meshtrade.api.type.v1.Ledger;
import co.meshtrade.api.type.v1.Type.Token;
import co.meshtrade.api.wallet.transfer.v1.TransferService;
import co.meshtrade.api.wallet.transfer.v1.Service.CalculateTransferFeeRequest;
import co.meshtrade.api.wallet.transfer.v1.Service.CalculateTransferFeeResponse;

import java.util.Optional;

public class CalculateTransferFeeExample {
    public static void main(String[] args) {
        // Default configuration is used and credentials come from MESH_API_CREDENTIALS
        // environment variable or default discovery methods. Zero config required
        // unless you want custom configuration.
        try (TransferService service = new TransferService()) {
            // Create request with the transfer amount to calculate fees for
            CalculateTransferFeeRequest request = CalculateTransferFeeRequest.newBuilder()
                .setAmount(Amount.newBuilder()
                    .setToken(Token.newBuilder()
                        .setCode("USDC")
                        .setIssuer("GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN")
                        .setLedger(Ledger.LEDGER_STELLAR)
                        .build())
                    .setValue(Decimal.newBuilder()
                        .setValue("1000.00")
                        .build())
                    .build())
                .build();

            // Call the CalculateTransferFee method
            CalculateTransferFeeResponse response = service.calculateTransferFee(request, Optional.empty());

            // Display the fee breakdown
            System.out.println("Transfer fee breakdown:");
            System.out.println("  Fee Amount: " + response.getFeeAmount().getValue().getValue()
                + " " + response.getFeeAmount().getToken().getCode());
            System.out.println("  VAT Amount: " + response.getVatAmount().getValue().getValue()
                + " " + response.getVatAmount().getToken().getCode());
            System.out.println("  VAT Rate: " + response.getVatRate().getValue());
        } catch (Exception e) {
            System.err.println("CalculateTransferFee failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Advanced Configuration

For advanced client configuration options (custom endpoints, TLS settings, timeouts), see the SDK Configuration Guide.

Other Methods

• Wallet Transfer v1 Method List - For Other methods