SearchLimitOrders

Searches limit orders using flexible filtering criteria.

Supports filtering by token, account, and populating live ledger data.

Overview

Method Options

Authorisation specification of the SearchLimitOrders method.

Type	METHOD_TYPE_READ
Access Level	METHOD_ACCESS_LEVEL_AUTHORISED
Roles	ROLE_TRADING_ADMIN ROLE_TRADING_VIEWER ROLE_TRADING_LIMIT_ORDER_ADMIN ROLE_TRADING_LIMIT_ORDER_VIEWER

Parameters

Request and response parameter message overview:

Input: SearchLimitOrdersRequest Message

Field	Type	Required	Description
Token	string	False	Filter by token (optional).
Account	string	False	Filter by account (optional). Format: accounts/{ULIDv2}.
States	meshtrade.trading.limit_order.v1.LimitOrderState[]	False	Filter by states (optional).
LiveLedgerData	bool	False	When true, fetches live ledger data for matching orders. When false, returns only stored metadata.

Returns: SearchLimitOrdersResponse Message

Field	Type	Description
LimitOrders	meshtrade.trading.limit_order.v1.LimitOrder[]	Collection of limit orders matching the search criteria.

Protobuf

syntax = "proto3";

package meshtrade.trading.limit_order.v1;

import "buf/validate/validate.proto";
import "meshtrade/option/method_options/v1/method_options.proto";
import "meshtrade/trading/limit_order/v1/limit_order.proto";

option go_package = "github.com/meshtrade/api/go/trading/limit_order/v1;limit_order_v1";
option java_package = "co.meshtrade.api.trading.limit_order.v1";

/*
   LimitOrderService manages limit orders for trading operations (BETA).

   This service provides comprehensive limit order management capabilities including
   order creation, cancellation, querying, and real-time monitoring. All operations
   are scoped to the authenticated group's hierarchy and require appropriate trading
   domain permissions.

   Note: This service is currently in BETA. Interface and functionality may change.
*/
service LimitOrderService {
  /*
     Creates a new limit order.

     Submits a limit order to the trading system. The order is validated and
     submitted to the appropriate ledger for execution.
  */
  rpc CreateLimitOrder(CreateLimitOrderRequest) returns (LimitOrder) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_TRADING_ADMIN,
        ROLE_TRADING_LIMIT_ORDER_ADMIN
      ]
      verification_status: VERIFICATION_STATUS_VERIFIED
    };
  }

  /*
     Cancels an existing limit order.

     Initiates cancellation of a limit order on the ledger.
  */
  rpc CancelLimitOrder(CancelLimitOrderRequest) returns (LimitOrder) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_WRITE
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_TRADING_ADMIN,
        ROLE_TRADING_LIMIT_ORDER_ADMIN
      ]
    };
  }

  /*
     Retrieves a specific limit order by its resource name.

     Provides access to limit order metadata and optionally fetches live
     ledger data when populate_ledger_data is true.
  */
  rpc GetLimitOrder(GetLimitOrderRequest) returns (LimitOrder) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_TRADING_ADMIN,
        ROLE_TRADING_VIEWER,
        ROLE_TRADING_LIMIT_ORDER_ADMIN,
        ROLE_TRADING_LIMIT_ORDER_VIEWER
      ]
    };
  }

  /*
     Retrieves a limit order by its external reference.

     Convenient lookup using client-provided external reference identifier.
  */
  rpc GetLimitOrderByExternalReference(GetLimitOrderByExternalReferenceRequest) returns (LimitOrder) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_TRADING_ADMIN,
        ROLE_TRADING_VIEWER,
        ROLE_TRADING_LIMIT_ORDER_ADMIN,
        ROLE_TRADING_LIMIT_ORDER_VIEWER
      ]
    };
  }

  /*
     Lists all limit orders within the authenticated group's scope.

     Returns the complete set of limit orders accessible to the executing context.
  */
  rpc ListLimitOrders(ListLimitOrdersRequest) returns (ListLimitOrdersResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_TRADING_ADMIN,
        ROLE_TRADING_VIEWER,
        ROLE_TRADING_LIMIT_ORDER_ADMIN,
        ROLE_TRADING_LIMIT_ORDER_VIEWER
      ]
    };
  }

  /*
     Searches limit orders using flexible filtering criteria.

     Supports filtering by token, account, and populating live ledger data.
  */
  rpc SearchLimitOrders(SearchLimitOrdersRequest) returns (SearchLimitOrdersResponse) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_TRADING_ADMIN,
        ROLE_TRADING_VIEWER,
        ROLE_TRADING_LIMIT_ORDER_ADMIN,
        ROLE_TRADING_LIMIT_ORDER_VIEWER
      ]
    };
  }

  /*
     Monitors a limit order for real-time updates.

     Supports lookup by either resource name or external reference using
     the identifier oneof field in the request. Returns a stream of limit
     order states as they change.
  */
  rpc MonitorLimitOrder(MonitorLimitOrderRequest) returns (stream LimitOrder) {
    option (meshtrade.option.method_options.v1.method_options) = {
      type: METHOD_TYPE_READ
      access_level: METHOD_ACCESS_LEVEL_AUTHORISED
      roles: [
        ROLE_TRADING_ADMIN,
        ROLE_TRADING_VIEWER,
        ROLE_TRADING_LIMIT_ORDER_ADMIN,
        ROLE_TRADING_LIMIT_ORDER_VIEWER
      ]
    };
  }
}

/*
   Request to create a new limit order.
*/
message CreateLimitOrderRequest {
  /*
     The limit order configuration for creation.
     The name field will be ignored and assigned by the system.
  */
  LimitOrder limit_order = 1 [(buf.validate.field) = {required: true}];
}

/*
   Request to cancel a limit order.
*/
message CancelLimitOrderRequest {
  /*
     The resource name of the limit order to cancel.
     Format: limit_orders/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 39
      pattern: "^limit_orders/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];
}

/*
   Request to retrieve a limit order by name.
*/
message GetLimitOrderRequest {
  /*
     The resource name of the limit order to retrieve.
     Format: limit_orders/{ULIDv2}.
  */
  string name = 1 [(buf.validate.field) = {
    required: true
    string: {
      len: 39
      pattern: "^limit_orders/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
    }
  }];

  /*
     When true, fetches live ledger data including fill status.
     When false, returns only stored metadata.
  */
  bool live_ledger_data = 2;
}

/*
   Request to retrieve a limit order by external reference.
*/
message GetLimitOrderByExternalReferenceRequest {
  /*
     The external reference identifier.
  */
  string external_reference = 1 [(buf.validate.field) = {required: true}];

  /*
     When true, fetches live ledger data including fill status.
     When false, returns only stored metadata.
  */
  bool live_ledger_data = 2;
}

/*
   Request to list all limit orders.
*/
message ListLimitOrdersRequest {
  /*
     When true, fetches live ledger data for all orders.
     When false, returns only stored metadata.
  */
  bool live_ledger_data = 1;
}

/*
   Response containing a list of limit orders.
*/
message ListLimitOrdersResponse {
  /*
     Collection of limit orders in the hierarchy.
  */
  repeated LimitOrder limit_orders = 1;
}

/*
   Request to search limit orders with filtering criteria.
*/
message SearchLimitOrdersRequest {
  /*
     Filter by token (optional).
  */
  string token = 1;

  /*
     Filter by account (optional).
     Format: accounts/{ULIDv2}.
  */
  string account = 2 [(buf.validate.field) = {
    string: {pattern: "^accounts/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"}
  }];

  /*
     Filter by states (optional).
  */
  repeated LimitOrderState states = 3;

  /*
     When true, fetches live ledger data for matching orders.
     When false, returns only stored metadata.
  */
  bool live_ledger_data = 4;
}

/*
   Response containing search results.
*/
message SearchLimitOrdersResponse {
  /*
     Collection of limit orders matching the search criteria.
  */
  repeated LimitOrder limit_orders = 1;
}

/*
   Request to monitor a limit order.
   Supports lookup by either resource name or external reference.
*/
message MonitorLimitOrderRequest {
  /*
     Identifier for the limit order to monitor.
     Exactly one field must be specified.
  */
  oneof identifier {
    /*
       The resource name of the limit order to monitor.
       Format: limit_orders/{ULIDv2}.
    */
    string name = 1 [(buf.validate.field) = {
      string: {
        len: 39
        pattern: "^limit_orders/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
      }
    }];

    /*
       The external reference identifier.
    */
    string external_reference = 2;
  }

  /*
     When true, fetches live ledger data for order.
     When false, returns only stored metadata.
     Note: The streaming does not stream based on ledger events such as fill amount changes,
     only limit order state changes triggers a stream update. If this is set to true
     then live ledger data will populated with the updated limit order state.
  */
  bool live_ledger_data = 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"

	limit_orderv1 "github.com/meshtrade/api/go/trading/limit_order/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 := limit_orderv1.NewLimitOrderService()
	if err != nil {
		log.Fatalf("Failed to create service: %v", err)
	}
	defer service.Close()

	// Search limit orders with optional filters
	// Replace with an actual account resource name from your system
	accountName := "accounts/01HQVBZ9F8X2T3K4M5N6P7Q8R9"

	request := &limit_orderv1.SearchLimitOrdersRequest{
		// Optional: Filter by token code
		Token: "USDC",
		// Optional: Filter by account (returns only orders for this account)
		Account: accountName,
		// Optional: Set to true to enrich with live ledger status
		LiveLedgerData: true,
	}

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

	// Response contains filtered list of limit orders
	log.Printf("✓ Found %d limit orders matching filters:", len(response.LimitOrders))
	for i, order := range response.LimitOrders {
		log.Printf("\n  Order #%d:", i+1)
		log.Printf("    Resource name: %s", order.Name)
		log.Printf("    Account: %s", order.Account)
		log.Printf("    External ref: %s", order.ExternalReference)
		log.Printf("    Side: %s", order.Side)
		log.Printf("    State: %s", order.State)
		log.Printf("    Limit price: %s %s", order.LimitPrice.Value.Value, order.LimitPrice.Token.Code)
		log.Printf("    Quantity: %s %s", order.Quantity.Value.Value, order.Quantity.Token.Code)
	}
}

Python

from meshtrade.trading.limit_order.v1 import (
    LimitOrderService,
    SearchLimitOrdersRequest,
)


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

    with service:
        # Search limit orders with optional filters
        # Replace with an actual account resource name from your system
        account_name = "accounts/01HQVBZ9F8X2T3K4M5N6P7Q8R9"

        request = SearchLimitOrdersRequest(
            # Optional: Filter by token code
            token="USDC",
            # Optional: Filter by account (returns only orders for this account)
            account=account_name,
            # Optional: Set to true to enrich with live ledger status
            live_ledger_data=True,
        )

        # Call the SearchLimitOrders method
        response = service.search_limit_orders(request)

        # Response contains filtered list of limit orders
        print(f"✓ Found {len(response.limit_orders)} limit orders matching filters:")
        for i, order in enumerate(response.limit_orders, 1):
            print(f"\n  Order #{i}:")
            print(f"    Resource name: {order.name}")
            print(f"    Account: {order.account}")
            print(f"    External ref: {order.external_reference}")
            print(f"    Side: {order.side}")
            print(f"    Status: {order.status}")
            print(f"    Limit price: {order.limit_price.value.value} {order.limit_price.token.code}")
            print(f"    Quantity: {order.quantity.value.value} {order.quantity.token.code}")


if __name__ == "__main__":
    main()

Java

import co.meshtrade.api.trading.limit_order.v1.LimitOrderOuterClass.LimitOrder;
import co.meshtrade.api.trading.limit_order.v1.LimitOrderService;
import co.meshtrade.api.trading.limit_order.v1.Service.SearchLimitOrdersRequest;
import co.meshtrade.api.trading.limit_order.v1.Service.SearchLimitOrdersResponse;

import java.util.Optional;

public class SearchLimitOrdersExample {
    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 (LimitOrderService service = new LimitOrderService()) {
            // Search limit orders with optional filters
            // Replace with an actual account resource name from your system
            String accountName = "accounts/01HQVBZ9F8X2T3K4M5N6P7Q8R9";

            SearchLimitOrdersRequest request = SearchLimitOrdersRequest.newBuilder()
                // Optional: Filter by token code
                .setToken("USDC")
                // Optional: Filter by account (returns only orders for this account)
                .setAccount(accountName)
                // Optional: Set to true to enrich with live ledger status
                .setLiveLedgerData(true)
                .build();

            // Call the SearchLimitOrders method
            SearchLimitOrdersResponse response = service.searchLimitOrders(request, Optional.empty());

            // Response contains filtered list of limit orders
            System.out.println("✓ Found " + response.getLimitOrdersCount() + " limit orders matching filters:");
            int i = 1;
            for (LimitOrder order : response.getLimitOrdersList()) {
                System.out.println("\n  Order #" + i + ":");
                System.out.println("    Resource name: " + order.getName());
                System.out.println("    Account: " + order.getAccount());
                System.out.println("    External ref: " + order.getExternalReference());
                System.out.println("    Side: " + order.getSide());
                System.out.println("    Status: " + order.getStatus());
                System.out.println("    Limit price: " + order.getLimitPrice().getValue().getValue() +
                                 " " + order.getLimitPrice().getToken().getCode());
                System.out.println("    Quantity: " + order.getQuantity().getValue().getValue() +
                                 " " + order.getQuantity().getToken().getCode());
                i++;
            }
        } catch (Exception e) {
            System.err.println("SearchLimitOrders failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Advanced Configuration

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

Other Methods

• Trading Limit Order v1 Method List - For Other methods