MonitorLimitOrder

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.

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
Protobuf

Method Options

Authorisation specification of the MonitorLimitOrder 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: `MonitorLimitOrderRequest` Message

Field	Type	Required	Description
`Name`	`string`	False	The resource name of the limit order to monitor. Format: limit_orders/{ULIDv2}.
`ExternalReference`	`string`	False	The external reference identifier.
`LiveLedgerData`	`bool`	False	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.

Returns: `LimitOrder Message`

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
Python
Java

package main

import (
	"context"
	"io"
	"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()

	// Monitor a limit order in real-time via server-side streaming
	// You can use either the resource name or external reference

	// Option 1: Monitor by resource name
	request := &limit_orderv1.MonitorLimitOrderRequest{
		Identifier: &limit_orderv1.MonitorLimitOrderRequest_Name{
			Name: "limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9",
		},
	}

	// Option 2: Monitor by external reference (commented out)
	// request := &limit_orderv1.MonitorLimitOrderRequest{
	// 	Identifier: &limit_orderv1.MonitorLimitOrderRequest_ExternalReference{
	// 		ExternalReference: "my-trading-system-order-123",
	// 	},
	// }

	// Call the MonitorLimitOrder streaming method
	// This opens a long-lived server-side stream that pushes order updates
	stream, err := service.MonitorLimitOrder(ctx, request)
	if err != nil {
		log.Fatalf("Failed to initiate stream: %v", err)
	}

	log.Println("✓ Monitoring limit order for real-time updates...")
	log.Println("  Listening for status changes... (Ctrl+C to stop)")

	// Consume stream responses
	// The server pushes updates whenever order status changes on the ledger
monitorOrder:
	for {
		limitOrder, err := stream.Recv()
		if err == io.EOF {
			break // Stream completed normally
		}
		if err != nil {
			log.Fatalf("Stream error: %v", err)
		}

		// Process each order update as it arrives
		log.Printf("\n📡 State update received: %s", limitOrder.State)
		log.Printf("  Resource name: %s", limitOrder.Name)
		log.Printf("  Account: %s", limitOrder.Account)
		log.Printf("  External ref: %s", limitOrder.ExternalReference)
		log.Printf("  Side: %s", limitOrder.Side)
		log.Printf("  Limit price: %s %s", limitOrder.LimitPrice.Value.Value, limitOrder.LimitPrice.Token.Code)
		log.Printf("  Quantity: %s %s", limitOrder.Quantity.Value.Value, limitOrder.Quantity.Token.Code)

		// Handle order state transitions
		switch limitOrder.State {
		case limit_orderv1.LimitOrderState_LIMIT_ORDER_STATE_SUBMISSION_IN_PROGRESS:
			log.Printf("  ⏳ Order submission in progress...")

		case limit_orderv1.LimitOrderState_LIMIT_ORDER_STATE_SUBMISSION_FAILED:
			log.Printf("  ❌ Order submission failed")
			break monitorOrder

		case limit_orderv1.LimitOrderState_LIMIT_ORDER_STATE_OPEN:
			log.Printf("  ✓ Order open on ledger and available for matching")
			// Order is active - continue monitoring for fills

		case limit_orderv1.LimitOrderState_LIMIT_ORDER_STATE_COMPLETE_IN_PROGRESS:
			log.Printf("  ⏳ Order completion in progress...")

		case limit_orderv1.LimitOrderState_LIMIT_ORDER_STATE_COMPLETE:
			log.Printf("  🎉 Order completed (fully filled)!")
			break monitorOrder

		case limit_orderv1.LimitOrderState_LIMIT_ORDER_STATE_CANCELLATION_IN_PROGRESS:
			log.Printf("  ⏳ Order cancellation in progress...")

		case limit_orderv1.LimitOrderState_LIMIT_ORDER_STATE_CANCELLED:
			log.Printf("  ❌ Order cancelled")
			break monitorOrder

		default:
			log.Printf("  ⚠️  Unexpected order state: %v", limitOrder.State)
		}
	}

	log.Println("\n✓ Stream completed successfully")
}

from meshtrade.trading.limit_order.v1 import (
    LimitOrderService,
    LimitOrderStatus,
    MonitorLimitOrderRequest,
)


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:
        # Monitor a limit order in real-time via server-side streaming
        # You can use either the resource name or external reference

        # Option 1: Monitor by resource name
        request = MonitorLimitOrderRequest(
            name="limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9",
        )

        # Option 2: Monitor by external reference (commented out)
        # request = MonitorLimitOrderRequest(
        #     external_reference="my-trading-system-order-123",
        # )

        # Call the MonitorLimitOrder streaming method
        # This opens a long-lived server-side stream that pushes order updates
        stream = service.monitor_limit_order(request)

        print("✓ Monitoring limit order for real-time updates...")
        print("  Listening for status changes... (Ctrl+C to stop)")

        try:
            # Consume stream responses
            # The server pushes updates whenever order status changes on the ledger
            for limit_order in stream:
                # Process each order update as it arrives
                print(f"\n📡 Status update received: {limit_order.status}")
                print(f"  Resource name: {limit_order.name}")
                print(f"  Account: {limit_order.account}")
                print(f"  External ref: {limit_order.external_reference}")
                print(f"  Side: {limit_order.side}")
                print(f"  Limit price: {limit_order.limit_price.value.value} {limit_order.limit_price.token.code}")
                print(f"  Quantity: {limit_order.quantity.value.value} {limit_order.quantity.token.code}")

                # Handle order state transitions
                if limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_SUBMISSION_IN_PROGRESS:
                    print("  ⏳ Order submission in progress...")

                elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_SUBMISSION_FAILED:
                    print("  ❌ Order submission failed")
                    break

                elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_OPEN:
                    print("  ✓ Order open on ledger and available for matching")
                    # Order is active - continue monitoring for fills

                elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_COMPLETE_IN_PROGRESS:
                    print("  ⏳ Order completion in progress...")

                elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_COMPLETE:
                    print("  🎉 Order completed (fully filled)!")
                    break

                elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS:
                    print("  ⏳ Order cancellation in progress...")

                elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_CANCELLED:
                    print("  ❌ Order cancelled")
                    break

                else:
                    print(f"  ⚠️  Unexpected order status: {limit_order.status}")

            print("\n✓ Stream completed successfully")
        except Exception as e:
            print(f"Stream error: {e}")
            raise


if __name__ == "__main__":
    main()

import co.meshtrade.api.trading.limit_order.v1.LimitOrderOuterClass.LimitOrder;
import co.meshtrade.api.trading.limit_order.v1.LimitOrderOuterClass.LimitOrderStatus;
import co.meshtrade.api.trading.limit_order.v1.LimitOrderService;
import co.meshtrade.api.trading.limit_order.v1.Service.MonitorLimitOrderRequest;

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

public class MonitorLimitOrderExample {
    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()) {
            // Monitor a limit order in real-time via server-side streaming
            // You can use either the resource name or external reference

            // Option 1: Monitor by resource name
            MonitorLimitOrderRequest request = MonitorLimitOrderRequest.newBuilder()
                .setName("limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9")
                .build();

            // Option 2: Monitor by external reference (commented out)
            // MonitorLimitOrderRequest request = MonitorLimitOrderRequest.newBuilder()
            //     .setExternalReference("my-trading-system-order-123")
            //     .build();

            // Call the MonitorLimitOrder streaming method
            // This opens a long-lived server-side stream that pushes order updates
            Iterator<LimitOrder> stream = service.monitorLimitOrder(request, Optional.empty());

            System.out.println("✓ Monitoring limit order for real-time updates...");
            System.out.println("  Listening for status changes... (Ctrl+C to stop)");

            // Consume stream responses
            // The server pushes updates whenever order status changes on the ledger
            monitorOrder:
            while (stream.hasNext()) {
                LimitOrder limitOrder = stream.next();

                // Process each order update as it arrives
                System.out.println("\n📡 Status update received: " + limitOrder.getStatus());
                System.out.println("  Resource name: " + limitOrder.getName());
                System.out.println("  Account: " + limitOrder.getAccount());
                System.out.println("  External ref: " + limitOrder.getExternalReference());
                System.out.println("  Side: " + limitOrder.getSide());
                System.out.println("  Limit price: " + limitOrder.getLimitPrice().getValue().getValue() +
                                 " " + limitOrder.getLimitPrice().getToken().getCode());
                System.out.println("  Quantity: " + limitOrder.getQuantity().getValue().getValue() +
                                 " " + limitOrder.getQuantity().getToken().getCode());

                // Handle order state transitions
                switch (limitOrder.getStatus()) {
                    case LIMIT_ORDER_STATUS_SUBMISSION_IN_PROGRESS:
                        System.out.println("  ⏳ Order submission in progress...");
                        break;

                    case LIMIT_ORDER_STATUS_SUBMISSION_FAILED:
                        System.out.println("  ❌ Order submission failed");
                        break monitorOrder;

                    case LIMIT_ORDER_STATUS_OPEN:
                        System.out.println("  ✓ Order open on ledger and available for matching");
                        // Order is active - continue monitoring for fills
                        break;

                    case LIMIT_ORDER_STATUS_COMPLETE_IN_PROGRESS:
                        System.out.println("  ⏳ Order completion in progress...");
                        break;

                    case LIMIT_ORDER_STATUS_COMPLETE:
                        System.out.println("  🎉 Order completed (fully filled)!");
                        break monitorOrder;

                    case LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS:
                        System.out.println("  ⏳ Order cancellation in progress...");
                        break;

                    case LIMIT_ORDER_STATUS_CANCELLED:
                        System.out.println("  ❌ Order cancelled");
                        break monitorOrder;

                    default:
                        System.out.println("  ⚠️  Unexpected order status: " + limitOrder.getStatus());
                        break;
                }
            }

            System.out.println("\n✓ Stream completed successfully");
        } catch (Exception e) {
            System.err.println("MonitorLimitOrder 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

Trading Limit Order v1 Method List - For Other methods

Method Options​

Parameters​

Input: MonitorLimitOrderRequest Message​

Returns: LimitOrder Message​

Code Examples​

Advanced Configuration​

Other Methods​