CreateLimitOrder

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.

Overview
Protobuf

Method Options

Authorisation specification of the CreateLimitOrder 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: `CreateLimitOrderRequest` Message

Field	Type	Required	Description
`LimitOrder`	`meshtrade.trading.limit_order.v1.LimitOrder`	True	The limit order configuration for creation. The name field will be ignored and assigned by the system.

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"
	type_v1 "github.com/meshtrade/api/go/type/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()

	// Create a buy limit order for 10 USDC at a limit price of 100.50 USDC
	// Note: You need a valid account resource name from the Wallet Account service
	request := &limit_orderv1.CreateLimitOrderRequest{
		LimitOrder: &limit_orderv1.LimitOrder{
			// Owner must be a valid group resource name
			Owner: "groups/01HQVBZ9F8X2T3K4M5N6P7Q8R9",
			// Account must be a valid Stellar account owned by your group
			Account: "accounts/01HQVBZ9F8X2T3K4M5N6P7Q8R9",
			// Optional: External reference for tracking in your system
			ExternalReference: "my-trading-system-order-123",
			// Buy side - use LIMIT_ORDER_SIDE_SELL for selling
			Side: limit_orderv1.LimitOrderSide_LIMIT_ORDER_SIDE_BUY,
			// Limit price: maximum price you're willing to pay (100.50 USDC)
			LimitPrice: &type_v1.Amount{
				Value: &type_v1.Decimal{
					Value: "100.50",
				},
				Token: &type_v1.Token{
					Code:   "USDC",
					Issuer: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
					Ledger: type_v1.Ledger_LEDGER_STELLAR,
				},
			},
			// Quantity: amount you want to buy (10 USDC)
			Quantity: &type_v1.Amount{
				Value: &type_v1.Decimal{
					Value: "10",
				},
				Token: &type_v1.Token{
					Code:   "USDC",
					Issuer: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
					Ledger: type_v1.Ledger_LEDGER_STELLAR,
				},
			},
		},
	}

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

	// Response contains the created order with system-generated resource name and number
	log.Printf("✓ Limit order created successfully!")
	log.Printf("  Resource name: %s", limitOrder.Name)
	log.Printf("  Number: %s", limitOrder.Number)
	log.Printf("  External reference: %s", limitOrder.ExternalReference)
	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)

	// Monitor the order until it opens on the ledger
	log.Printf("\n📡 Monitoring order until it opens on the ledger...")
	monitorRequest := &limit_orderv1.MonitorLimitOrderRequest{
		Identifier: &limit_orderv1.MonitorLimitOrderRequest_Name{
			Name: limitOrder.Name,
		},
	}

	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_SUBMISSION_IN_PROGRESS:
			log.Printf("  ⏳ Order submission in progress...")

		case limit_orderv1.LimitOrderState_LIMIT_ORDER_STATE_SUBMISSION_FAILED:
			log.Fatalf("  ❌ Order submission failed")

		case limit_orderv1.LimitOrderState_LIMIT_ORDER_STATE_OPEN:
			log.Printf("  ✓ Order is now open on the ledger and available for matching!")
			break monitorOrder
		}
	}
}

from meshtrade.trading.limit_order.v1 import (
    CreateLimitOrderRequest,
    LimitOrder,
    LimitOrderService,
    LimitOrderSide,
    LimitOrderStatus,
    MonitorLimitOrderRequest,
)
from meshtrade.type.v1 import Amount, Decimal, Ledger, Token


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:
        # Create a buy limit order for 10 USDC at a limit price of 100.50 USDC
        # Note: You need a valid account resource name from the Wallet Account service
        request = CreateLimitOrderRequest(
            limit_order=LimitOrder(
                # Owner must be a valid group resource name
                owner="groups/01HQVBZ9F8X2T3K4M5N6P7Q8R9",
                # Account must be a valid Stellar account owned by your group
                account="accounts/01HQVBZ9F8X2T3K4M5N6P7Q8R9",
                # Optional: External reference for tracking in your system
                external_reference="my-trading-system-order-123",
                # Buy side - use LIMIT_ORDER_SIDE_SELL for selling
                side=LimitOrderSide.LIMIT_ORDER_SIDE_BUY,
                # Limit price: maximum price you're willing to pay (100.50 USDC)
                limit_price=Amount(
                    value=Decimal(value="100.50"),
                    token=Token(
                        code="USDC",
                        issuer="GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
                        ledger=Ledger.LEDGER_STELLAR,
                    ),
                ),
                # Quantity: amount you want to buy (10 USDC)
                quantity=Amount(
                    value=Decimal(value="10"),
                    token=Token(
                        code="USDC",
                        issuer="GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
                        ledger=Ledger.LEDGER_STELLAR,
                    ),
                ),
            )
        )

        # Call the CreateLimitOrder method
        limit_order = service.create_limit_order(request)

        # Response contains the created order with system-generated resource name and number
        print("✓ Limit order created successfully!")
        print(f"  Resource name: {limit_order.name}")
        print(f"  Number: {limit_order.number}")
        print(f"  External reference: {limit_order.external_reference}")
        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}")

        # Monitor the order until it opens on the ledger
        print("\n📡 Monitoring order until it opens on the ledger...")
        monitor_request = MonitorLimitOrderRequest(
            name=limit_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_SUBMISSION_IN_PROGRESS:
                print("  ⏳ Order submission in progress...")

            elif update.status == LimitOrderStatus.LIMIT_ORDER_STATUS_SUBMISSION_FAILED:
                print("  ❌ Order submission failed")
                raise RuntimeError("Order submission failed")

            elif update.status == LimitOrderStatus.LIMIT_ORDER_STATUS_OPEN:
                print("  ✓ Order is now open on the ledger and available for matching!")
                break


if __name__ == "__main__":
    main()

import co.meshtrade.api.trading.limit_order.v1.LimitOrderOuterClass.LimitOrder;
import co.meshtrade.api.trading.limit_order.v1.LimitOrderOuterClass.LimitOrderSide;
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.CreateLimitOrderRequest;
import co.meshtrade.api.trading.limit_order.v1.Service.MonitorLimitOrderRequest;
import co.meshtrade.api.type.v1.AmountOuterClass.Amount;
import co.meshtrade.api.type.v1.DecimalOuterClass.Decimal;
import co.meshtrade.api.type.v1.LedgerOuterClass.Ledger;
import co.meshtrade.api.type.v1.TokenOuterClass.Token;

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

public class CreateLimitOrderExample {
    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()) {
            // Create a buy limit order for 10 USDC at a limit price of 100.50 USDC
            // Note: You need a valid account resource name from the Wallet Account service

            // Build the limit price amount (100.50 USDC)
            Amount limitPrice = Amount.newBuilder()
                .setValue(Decimal.newBuilder()
                    .setValue("100.50")
                    .build())
                .setToken(Token.newBuilder()
                    .setCode("USDC")
                    .setIssuer("GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN")
                    .setLedger(Ledger.LEDGER_STELLAR)
                    .build())
                .build();

            // Build the quantity amount (10 USDC)
            Amount quantity = Amount.newBuilder()
                .setValue(Decimal.newBuilder()
                    .setValue("10")
                    .build())
                .setToken(Token.newBuilder()
                    .setCode("USDC")
                    .setIssuer("GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN")
                    .setLedger(Ledger.LEDGER_STELLAR)
                    .build())
                .build();

            // Build the limit order
            LimitOrder limitOrderToCreate = LimitOrder.newBuilder()
                // Owner must be a valid group resource name
                .setOwner("groups/01HQVBZ9F8X2T3K4M5N6P7Q8R9")
                // Account must be a valid Stellar account owned by your group
                .setAccount("accounts/01HQVBZ9F8X2T3K4M5N6P7Q8R9")
                // Optional: External reference for tracking in your system
                .setExternalReference("my-trading-system-order-123")
                // Buy side - use LIMIT_ORDER_SIDE_SELL for selling
                .setSide(LimitOrderSide.LIMIT_ORDER_SIDE_BUY)
                .setLimitPrice(limitPrice)
                .setQuantity(quantity)
                .build();

            // Create the request
            CreateLimitOrderRequest request = CreateLimitOrderRequest.newBuilder()
                .setLimitOrder(limitOrderToCreate)
                .build();

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

            // Response contains the created order with system-generated resource name and number
            System.out.println("✓ Limit order created successfully!");
            System.out.println("  Resource name: " + limitOrder.getName());
            System.out.println("  Number: " + limitOrder.getNumber());
            System.out.println("  External reference: " + limitOrder.getExternalReference());
            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());

            // Monitor the order until it opens on the ledger
            System.out.println("\n📡 Monitoring order until it opens on the ledger...");
            MonitorLimitOrderRequest monitorRequest = MonitorLimitOrderRequest.newBuilder()
                .setName(limitOrder.getName())
                .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_SUBMISSION_IN_PROGRESS:
                        System.out.println("  ⏳ Order submission in progress...");
                        break;

                    case LIMIT_ORDER_STATUS_SUBMISSION_FAILED:
                        System.err.println("  ❌ Order submission failed");
                        throw new RuntimeException("Order submission failed");

                    case LIMIT_ORDER_STATUS_OPEN:
                        System.out.println("  ✓ Order is now open on the ledger and available for matching!");
                        break monitorOrder;

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

Returns: LimitOrder Message​

Code Examples​

Advanced Configuration​

Other Methods​