CancelLimitOrder

Cancels an existing limit order.

Initiates cancellation of a limit order on the ledger.

Overview
Protobuf

Method Options

Authorisation specification of the CancelLimitOrder method.

Type	`METHOD_TYPE_WRITE`
Access Level	`METHOD_ACCESS_LEVEL_AUTHORISED`
Roles	`ROLE_TRADING_ADMIN` `ROLE_TRADING_LIMIT_ORDER_ADMIN`

Parameters

Request and response parameter message overview:

Input: `CancelLimitOrderRequest` Message

Field	Type	Required	Description
`Name`	`string`	True	The resource name of the limit order to cancel. Format: limit_orders/{ULIDv2}.

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

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

	request := &limit_orderv1.CancelLimitOrderRequest{
		Name: orderName,
	}

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

	// Response contains the cancellation status
	log.Printf("✓ Limit order cancellation initiated:")
	log.Printf("  Order name: %s", orderName)
	log.Printf("  State: %s", response.State)

	// Monitor the order until cancellation is complete
	log.Printf("\n📡 Monitoring order until cancellation is complete...")
	monitorRequest := &limit_orderv1.MonitorLimitOrderRequest{
		Identifier: &limit_orderv1.MonitorLimitOrderRequest_Name{
			Name: orderName,
		},
	}

	stream, err := service.MonitorLimitOrder(ctx, monitorRequest)
	if err != nil {
		log.Fatalf("MonitorLimitOrder failed: %v", err)
	}

monitorOrder:
	for {
		update, err := stream.Recv()
		if err != nil {
			log.Fatalf("Stream error: %v", err)
		}

		log.Printf("  State: %s", update.State)

		switch update.State {
		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 successfully cancelled on ledger!")
			break monitorOrder
		}
	}
}

from meshtrade.trading.limit_order.v1 import (
    CancelLimitOrderRequest,
    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:
        # Cancel an active limit order by its resource name
        # Replace with an actual limit order resource name from your system
        order_name = "limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9"

        request = CancelLimitOrderRequest(
            name=order_name,
        )

        # Call the CancelLimitOrder method
        response = service.cancel_limit_order(request)

        # Response contains the cancellation status
        print("✓ Limit order cancellation initiated:")
        print(f"  Order name: {order_name}")
        print(f"  Status: {response.status}")

        # Monitor the order until cancellation is complete
        print("\n📡 Monitoring order until cancellation is complete...")
        monitor_request = MonitorLimitOrderRequest(
            name=order_name,
        )

        stream = service.monitor_limit_order(monitor_request)

        for update in stream:
            print(f"  Status: {update.status}")

            if update.status == LimitOrderStatus.LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS:
                print("  ⏳ Order cancellation in progress...")

            elif update.status == LimitOrderStatus.LIMIT_ORDER_STATUS_CANCELLED:
                print("  ✓ Order successfully cancelled on ledger!")
                break


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.CancelLimitOrderRequest;
import co.meshtrade.api.trading.limit_order.v1.Service.MonitorLimitOrderRequest;

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

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

            CancelLimitOrderRequest request = CancelLimitOrderRequest.newBuilder()
                .setName(orderName)
                .build();

            // Call the CancelLimitOrder method
            LimitOrder response = service.cancelLimitOrder(request, Optional.empty());

            // Response contains the cancellation status
            System.out.println("✓ Limit order cancellation initiated:");
            System.out.println("  Order name: " + orderName);
            System.out.println("  Status: " + response.getStatus());

            // Monitor the order until cancellation is complete
            System.out.println("\n📡 Monitoring order until cancellation is complete...");
            MonitorLimitOrderRequest monitorRequest = MonitorLimitOrderRequest.newBuilder()
                .setName(orderName)
                .build();

            Iterator<LimitOrder> stream = service.monitorLimitOrder(monitorRequest, Optional.empty());

            monitorOrder:
            while (stream.hasNext()) {
                LimitOrder update = stream.next();
                System.out.println("  Status: " + update.getStatus());

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

                    case LIMIT_ORDER_STATUS_CANCELLED:
                        System.out.println("  ✓ Order successfully cancelled on ledger!");
                        break monitorOrder;

                    default:
                        break;
                }
            }
        } catch (Exception e) {
            System.err.println("CancelLimitOrder 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: CancelLimitOrderRequest Message​

Returns: LimitOrder Message​

Code Examples​

Advanced Configuration​

Other Methods​