GetLimitOrderByExternalReference

Retrieves a limit order by its external reference.

Convenient lookup using client-provided external reference identifier.

Overview

Method Options

Authorisation specification of the GetLimitOrderByExternalReference 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: GetLimitOrderByExternalReferenceRequest Message

Field	Type	Required	Description
ExternalReference	string	True	The external reference identifier.
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 external reference identifier
	// This is useful when you track orders in your own system using custom IDs
	externalRef := "my-trading-system-order-123"

	request := &limit_orderv1.GetLimitOrderByExternalReferenceRequest{
		ExternalReference: externalRef,
	}

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

	// Response contains the limit order matching the external reference
	log.Printf("✓ Limit order found by external reference:")
	log.Printf("  External reference: %s", limitOrder.ExternalReference)
	log.Printf("  Resource name: %s", limitOrder.Name)
	log.Printf("  Account: %s", limitOrder.Account)
	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)
	log.Printf("\nNote: External references must be unique within your group hierarchy")
}

Python

from meshtrade.trading.limit_order.v1 import (
    GetLimitOrderByExternalReferenceRequest,
    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 external reference identifier
        # This is useful when you track orders in your own system using custom IDs
        external_ref = "my-trading-system-order-123"

        request = GetLimitOrderByExternalReferenceRequest(
            external_reference=external_ref,
        )

        # Call the GetLimitOrderByExternalReference method
        limit_order = service.get_limit_order_by_external_reference(request)

        # Response contains the limit order matching the external reference
        print("✓ Limit order found by external reference:")
        print(f"  External reference: {limit_order.external_reference}")
        print(f"  Resource name: {limit_order.name}")
        print(f"  Account: {limit_order.account}")
        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}")
        print("\nNote: External references must be unique within your group hierarchy")


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.GetLimitOrderByExternalReferenceRequest;

import java.util.Optional;

public class GetLimitOrderByExternalReferenceExample {
    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 external reference identifier
            // This is useful when you track orders in your own system using custom IDs
            String externalRef = "my-trading-system-order-123";

            GetLimitOrderByExternalReferenceRequest request = GetLimitOrderByExternalReferenceRequest.newBuilder()
                .setExternalReference(externalRef)
                .build();

            // Call the GetLimitOrderByExternalReference method
            LimitOrder limitOrder = service.getLimitOrderByExternalReference(request, Optional.empty());

            // Response contains the limit order matching the external reference
            System.out.println("✓ Limit order found by external reference:");
            System.out.println("  External reference: " + limitOrder.getExternalReference());
            System.out.println("  Resource name: " + limitOrder.getName());
            System.out.println("  Account: " + limitOrder.getAccount());
            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());
            System.out.println("\nNote: External references must be unique within your group hierarchy");
        } catch (Exception e) {
            System.err.println("GetLimitOrderByExternalReference 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