MonitorTransfer

Monitors a transfer for real-time updates. Supports lookup by either resource name. Returns a stream of transfer states as they change.

Server-Side Streaming Method

This method uses server-side streaming, meaning it returns multiple responses over time rather than a single response. The server sends a stream of responses to the client, and the client processes each response as it arrives.

Stream Lifecycle:

• Initiation: Call the method to create a stream
• Data Reception: Receive multiple responses over the stream
• Completion: Stream ends normally (EOF/end event) or with an error
• Resource Management: Streams should be fully consumed or explicitly closed

See the code examples below for language-specific streaming consumption patterns.

Overview

Method Options

Authorisation specification of the MonitorTransfer 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: MonitorTransferRequest Message

Field	Type	Required	Description
Name	string	False	The resource name of the transfer to monitor. Format: wallet/transfers/{ULIDv2}.

Returns: Transfer Message

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"
	"io"
	"log"

	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()

	// Monitor a specific transfer for real-time state updates
	request := &transferv1.MonitorTransferRequest{
		Name: "wallet/transfers/01HQ3K5M8XYZ2NFVJT9BKR7P4C", // Transfer resource name
	}

	// Call the MonitorTransfer streaming method
	stream, err := service.MonitorTransfer(ctx, request)
	if err != nil {
		log.Fatalf("Failed to initiate stream: %v", err)
	}

	// Consume stream responses as the transfer state changes
	for {
		transfer, err := stream.Recv()
		if err == io.EOF {
			break // Stream completed normally
		}
		if err != nil {
			log.Fatalf("Stream error: %v", err)
		}

		// React to state changes
		log.Printf("Transfer %s state: %s", transfer.Number, transfer.State)

		if transfer.State == transferv1.TransferState_TRANSFER_STATE_SUCCESSFUL {
			log.Printf("Transfer completed successfully")
			log.Printf("  Fee: %s", transfer.Fee.Amount.Value)
			break
		}
		if transfer.State == transferv1.TransferState_TRANSFER_STATE_FAILED {
			log.Printf("Transfer failed")
			break
		}
	}
}

Python

from meshtrade.wallet.transfer.v1 import (
    MonitorTransferRequest,
    TransferService,
    TransferState,
)


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:
        # Monitor a specific transfer for real-time state updates
        request = MonitorTransferRequest(
            name="wallet/transfers/01HQ3K5M8XYZ2NFVJT9BKR7P4C",  # Transfer resource name
        )

        # Call the MonitorTransfer streaming method
        stream = service.monitor_transfer(request)

        try:
            # Consume stream responses as the transfer state changes
            for transfer in stream:
                # React to state changes
                print(f"Transfer {transfer.number} state: {transfer.state}")

                if transfer.state == TransferState.TRANSFER_STATE_SUCCESSFUL:
                    print("Transfer completed successfully")
                    print(f"  Fee: {transfer.fee.amount.value}")
                    break
                if transfer.state == TransferState.TRANSFER_STATE_FAILED:
                    print("Transfer failed")
                    break
        except Exception as e:
            print("Stream error:", e)
            raise


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.wallet.transfer.v1.TransferService;
import co.meshtrade.api.wallet.transfer.v1.Service.MonitorTransferRequest;
import co.meshtrade.api.wallet.transfer.v1.Transfer.Transfer;
import co.meshtrade.api.wallet.transfer.v1.Transfer.TransferState;

import java.util.Iterator;
import java.util.Optional;

public class MonitorTransferExample {
    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()) {
            // Monitor a specific transfer for real-time state updates
            MonitorTransferRequest request = MonitorTransferRequest.newBuilder()
                .setName("wallet/transfers/01HQ3K5M8XYZ2NFVJT9BKR7P4C")  // Transfer resource name
                .build();

            // Call the MonitorTransfer streaming method
            Iterator<Transfer> stream = service.monitorTransfer(request, Optional.empty());

            // Consume stream responses as the transfer state changes
            while (stream.hasNext()) {
                Transfer transfer = stream.next();

                // React to state changes
                System.out.println("Transfer " + transfer.getNumber()
                    + " state: " + transfer.getState());

                if (transfer.getState() == TransferState.TRANSFER_STATE_SUCCESSFUL) {
                    System.out.println("Transfer completed successfully");
                    System.out.println("  Fee: " + transfer.getFee().getAmount().getValue());
                    break;
                }
                if (transfer.getState() == TransferState.TRANSFER_STATE_FAILED) {
                    System.out.println("Transfer failed");
                    break;
                }
            }
        } catch (Exception e) {
            System.err.println("MonitorTransfer stream 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