ListTransfers

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.

Overview

Method Options

Authorisation specification of the ListTransfers 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: ListTransfersRequest Message

Field	Type	Required	Description
Sorting	Field Type Required Description Field string False Field to sort by. Supported values: "number" or empty string for default ordering. Order meshtrade.type.v1.SortingOrder False Sort order for results.	False	Optional sorting configuration.

Returns: ListTransfersResponse Message

Field	Type	Description
Transfers	meshtrade.wallet.transfer.v1.Transfer[]

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 optional sorting
	request := &transferv1.ListTransfersRequest{
		Sorting: &transferv1.ListTransfersRequest_Sorting{
			Field: "number",                              // Sort by transfer number
			Order: typev1.SortingOrder_SORTING_ORDER_ASC, // Ascending order
		},
	}

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

	// Display all transfers in the hierarchy
	log.Printf("Found %d transfers:", len(response.Transfers))
	for _, transfer := range response.Transfers {
		log.Printf("  Transfer %s:", transfer.Number)
		log.Printf("    Name: %s", transfer.Name)
		log.Printf("    From: %s", transfer.From)
		log.Printf("    To: %s", transfer.To)
		log.Printf("    Amount: %s %s", transfer.Amount.Value, transfer.Amount.Token.Code)
		log.Printf("    State: %s", transfer.State)
	}
}

Python

from meshtrade.type.v1 import SortingOrder
from meshtrade.wallet.transfer.v1 import (
    ListTransfersRequest,
    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 optional sorting
        request = ListTransfersRequest(
            sorting=ListTransfersRequest.Sorting(
                field="number",  # Sort by transfer number
                order=SortingOrder.SORTING_ORDER_ASC,  # Ascending order
            )
        )

        # Call the ListTransfers method
        response = service.list_transfers(request)

        # Display all transfers in the hierarchy
        print(f"Found {len(response.transfers)} transfers:")
        for transfer in response.transfers:
            print(f"  Transfer {transfer.number}:")
            print(f"    Name: {transfer.name}")
            print(f"    From: {transfer.from_}")
            print(f"    To: {transfer.to}")
            print(f"    Amount: {transfer.amount.value} {transfer.amount.token.code}")
            print(f"    State: {transfer.state}")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.type.v1.Sorting.SortingOrder;
import co.meshtrade.api.wallet.transfer.v1.TransferService;
import co.meshtrade.api.wallet.transfer.v1.Service.ListTransfersRequest;
import co.meshtrade.api.wallet.transfer.v1.Service.ListTransfersResponse;
import co.meshtrade.api.wallet.transfer.v1.Transfer.Transfer;

import java.util.Optional;

public class ListTransfersExample {
    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 optional sorting
            ListTransfersRequest request = ListTransfersRequest.newBuilder()
                .setSorting(ListTransfersRequest.Sorting.newBuilder()
                    .setField("number")  // Sort by transfer number
                    .setOrder(SortingOrder.SORTING_ORDER_ASC)  // Ascending order
                    .build())
                .build();

            // Call the ListTransfers method
            ListTransfersResponse response = service.listTransfers(request, Optional.empty());

            // Display all transfers in the hierarchy
            System.out.println("Found " + response.getTransfersList().size() + " transfers:");
            for (Transfer transfer : response.getTransfersList()) {
                System.out.println("  Transfer " + transfer.getNumber() + ":");
                System.out.println("    Name: " + transfer.getName());
                System.out.println("    From: " + transfer.getFrom());
                System.out.println("    To: " + transfer.getTo());
                System.out.println("    Amount: " + transfer.getAmount().getValue()
                    + " " + transfer.getAmount().getToken().getCode());
                System.out.println("    State: " + transfer.getState());
            }
        } catch (Exception e) {
            System.err.println("ListTransfers 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