SearchTransfersByAddress

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.

Overview

Method Options

Authorisation specification of the SearchTransfersByAddress 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: SearchTransfersByAddressRequest Message

Field	Type	Required	Description
Address	string	True	The ledger address of the account

Returns: SearchTransfersByAddressResponse 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"

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

	// Search for all transfers involving a specific ledger address
	request := &transferv1.SearchTransfersByAddressRequest{
		Address: "GBZH4LMGAYUDNFPNFGOBKU76DDRJHIAKGKGO2LNZFLQB6DMKV7EYHT", // Ledger address to search
	}

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

	// Display all transfers involving this address (as sender or receiver)
	log.Printf("Found %d transfers for address:", len(response.Transfers))
	for _, transfer := range response.Transfers {
		log.Printf("  Transfer %s:", transfer.Number)
		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.wallet.transfer.v1 import (
    SearchTransfersByAddressRequest,
    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:
        # Search for all transfers involving a specific ledger address
        request = SearchTransfersByAddressRequest(
            address="GBZH4LMGAYUDNFPNFGOBKU76DDRJHIAKGKGO2LNZFLQB6DMKV7EYHT",  # Ledger address to search
        )

        # Call the SearchTransfersByAddress method
        response = service.search_transfers_by_address(request)

        # Display all transfers involving this address (as sender or receiver)
        print(f"Found {len(response.transfers)} transfers for address:")
        for transfer in response.transfers:
            print(f"  Transfer {transfer.number}:")
            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.wallet.transfer.v1.TransferService;
import co.meshtrade.api.wallet.transfer.v1.Service.SearchTransfersByAddressRequest;
import co.meshtrade.api.wallet.transfer.v1.Service.SearchTransfersByAddressResponse;
import co.meshtrade.api.wallet.transfer.v1.Transfer.Transfer;

import java.util.Optional;

public class SearchTransfersByAddressExample {
    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()) {
            // Search for all transfers involving a specific ledger address
            SearchTransfersByAddressRequest request = SearchTransfersByAddressRequest.newBuilder()
                .setAddress("GBZH4LMGAYUDNFPNFGOBKU76DDRJHIAKGKGO2LNZFLQB6DMKV7EYHT")  // Ledger address to search
                .build();

            // Call the SearchTransfersByAddress method
            SearchTransfersByAddressResponse response = service.searchTransfersByAddress(request, Optional.empty());

            // Display all transfers involving this address (as sender or receiver)
            System.out.println("Found " + response.getTransfersList().size() + " transfers for address:");
            for (Transfer transfer : response.getTransfersList()) {
                System.out.println("  Transfer " + transfer.getNumber() + ":");
                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("SearchTransfersByAddress 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