GetLimitOrder

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.

Overview

Method Options

Authorisation specification of the GetLimitOrder 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: GetLimitOrderRequest Message

Field	Type	Required	Description
Name	string	True	The resource name of the limit order to retrieve. Format: limit_orders/{ULIDv2}.
LiveLedgerData	bool	False	When true, fetches live ledger data including fill status. When false, returns only stored metadata.

Returns: LimitOrder Message

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

	// Get a limit order by its resource name
	// Replace with an actual limit order resource name from your system
	orderName := "limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9"

	// Example 1: Get without live ledger data (faster, but status will be UNSPECIFIED)
	request := &limit_orderv1.GetLimitOrderRequest{
		Name:           orderName,
		LiveLedgerData: false,
	}

	limitOrder, err := service.GetLimitOrder(ctx, request)
	if err != nil {
		log.Fatalf("GetLimitOrder failed: %v", err)
	}

	log.Printf("✓ Limit order retrieved (cached data):")
	log.Printf("  Resource name: %s", limitOrder.Name)
	log.Printf("  Number: %s", limitOrder.Number)
	log.Printf("  Account: %s", limitOrder.Account)
	log.Printf("  External reference: %s", limitOrder.ExternalReference)
	log.Printf("  Side: %s", limitOrder.Side)
	log.Printf("  State: %s (UNSPECIFIED when live_ledger_data=false)", limitOrder.State)

	// Example 2: Get with live ledger data (queries the ledger for current status)
	requestWithLiveData := &limit_orderv1.GetLimitOrderRequest{
		Name:           orderName,
		LiveLedgerData: true,
	}

	limitOrderWithStatus, err := service.GetLimitOrder(ctx, requestWithLiveData)
	if err != nil {
		log.Fatalf("GetLimitOrder with live data failed: %v", err)
	}

	log.Printf("\n✓ Limit order retrieved (with live ledger data):")
	log.Printf("  Resource name: %s", limitOrderWithStatus.Name)
	log.Printf("  State: %s", limitOrderWithStatus.State)
	log.Printf("  Limit price: %s %s", limitOrderWithStatus.LimitPrice.Value.Value, limitOrderWithStatus.LimitPrice.Token.Code)
	log.Printf("  Quantity: %s %s", limitOrderWithStatus.Quantity.Value.Value, limitOrderWithStatus.Quantity.Token.Code)
}

Python

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


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:
        # Get a limit order by its resource name
        # Replace with an actual limit order resource name from your system
        order_name = "limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9"

        # Example 1: Get without live ledger data (faster, but status will be UNSPECIFIED)
        request = GetLimitOrderRequest(
            name=order_name,
            live_ledger_data=False,
        )

        limit_order = service.get_limit_order(request)

        print("✓ Limit order retrieved (cached data):")
        print(f"  Resource name: {limit_order.name}")
        print(f"  Number: {limit_order.number}")
        print(f"  Account: {limit_order.account}")
        print(f"  External reference: {limit_order.external_reference}")
        print(f"  Side: {limit_order.side}")
        print(f"  Status: {limit_order.status} (UNSPECIFIED when live_ledger_data=false)")

        # Example 2: Get with live ledger data (queries the ledger for current status)
        request_with_live_data = GetLimitOrderRequest(
            name=order_name,
            live_ledger_data=True,
        )

        limit_order_with_status = service.get_limit_order(request_with_live_data)

        print("\n✓ Limit order retrieved (with live ledger data):")
        print(f"  Resource name: {limit_order_with_status.name}")
        print(f"  Status: {limit_order_with_status.status}")
        print(f"  Limit price: {limit_order_with_status.limit_price.value.value} {limit_order_with_status.limit_price.token.code}")
        print(f"  Quantity: {limit_order_with_status.quantity.value.value} {limit_order_with_status.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.GetLimitOrderRequest;

import java.util.Optional;

public class GetLimitOrderExample {
    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()) {
            // Get a limit order by its resource name
            // Replace with an actual limit order resource name from your system
            String orderName = "limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9";

            // Example 1: Get without live ledger data (faster, but status will be UNSPECIFIED)
            GetLimitOrderRequest request = GetLimitOrderRequest.newBuilder()
                .setName(orderName)
                .setLiveLedgerData(false)
                .build();

            LimitOrder limitOrder = service.getLimitOrder(request, Optional.empty());

            System.out.println("✓ Limit order retrieved (cached data):");
            System.out.println("  Resource name: " + limitOrder.getName());
            System.out.println("  Number: " + limitOrder.getNumber());
            System.out.println("  Account: " + limitOrder.getAccount());
            System.out.println("  External reference: " + limitOrder.getExternalReference());
            System.out.println("  Side: " + limitOrder.getSide());
            System.out.println("  Status: " + limitOrder.getStatus() + " (UNSPECIFIED when live_ledger_data=false)");

            // Example 2: Get with live ledger data (queries the ledger for current status)
            GetLimitOrderRequest requestWithLiveData = GetLimitOrderRequest.newBuilder()
                .setName(orderName)
                .setLiveLedgerData(true)
                .build();

            LimitOrder limitOrderWithStatus = service.getLimitOrder(requestWithLiveData, Optional.empty());

            System.out.println("\n✓ Limit order retrieved (with live ledger data):");
            System.out.println("  Resource name: " + limitOrderWithStatus.getName());
            System.out.println("  Status: " + limitOrderWithStatus.getStatus());
            System.out.println("  Limit price: " + limitOrderWithStatus.getLimitPrice().getValue().getValue() +
                             " " + limitOrderWithStatus.getLimitPrice().getToken().getCode());
            System.out.println("  Quantity: " + limitOrderWithStatus.getQuantity().getValue().getValue() +
                             " " + limitOrderWithStatus.getQuantity().getToken().getCode());
        } catch (Exception e) {
            System.err.println("GetLimitOrder 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