Fix limit order API examples and documentation

docs/docs/api-reference/trading/limit_order/v1/index.mdx

@@ -21,30 +21,109 @@ This warning will be removed once complete and ready for use.
 
 ## Overview
 
-LimitOrderService manages limit orders for trading operations (BETA).
+LimitOrderService manages limit orders for trading operations on supported ledgers (currently Stellar).
 
-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.
+This service provides comprehensive limit order management capabilities including:
+- **Order creation** with flexible pricing and quantity specifications
+- **Order cancellation** for active orders
+- **Order querying** by resource name or external reference
+- **Order listing and searching** with optional filters
+- **Real-time monitoring** via server-side streaming
+- **Live ledger data** integration for up-to-date order status
+
+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.
 
-Add your custom documentation for the Trading Limit Order v1 service here.
-This file is generated once and can be manually edited to provide
-service-specific information, examples, and usage guidance.
+## Key Features
+
+### Live Ledger Data
+Many read operations support an optional `live_ledger_data` flag that enriches responses with real-time ledger state:
+- When `false` (default): Returns persisted order metadata with `LIMIT_ORDER_STATUS_UNSPECIFIED`
+- When `true`: Queries the underlying ledger and populates current order status (e.g., `LIMIT_ORDER_STATUS_OPEN`, `LIMIT_ORDER_STATUS_COMPLETE`)
+
+### External References
+Each limit order can be tagged with a unique `external_reference` string, enabling:
+- Integration with external trading systems
+- Order tracking across multiple systems
+- Quick lookup via `GetLimitOrderByExternalReference`
+
+### Resource Naming
+Limit orders use a flat resource name format:
+```
+limit_orders/{order_id}
+```
+Where `{order_id}` is a system-generated ULIDv2 identifier (26 characters).
 
 ## Quick Start
 
-1. **Configure your client** with the appropriate credentials
-2. **Choose your operations** from the available service methods
-3. **Review the types** to understand request/response structures
+1. **Obtain credentials** with `ROLE_TRADING_LIMIT_ORDER_ADMIN` or `ROLE_TRADING_LIMIT_ORDER_VIEWER`
+2. **Create an account** on your desired ledger (e.g., Stellar) using the Wallet Account service
+3. **Create a limit order** specifying price, quantity, and order side (buy/sell)
+4. **Monitor your order** using `GetLimitOrder` with `live_ledger_data: true` or stream updates via `MonitorLimitOrder`
 
 ## Common Workflows
 
-Add common workflow documentation here specific to this service.
+### Creating a Buy Order
+```
+1. Ensure you have a Stellar account (via Wallet Account service)
+2. Call CreateLimitOrder with:
+   - owner: Your group resource name (groups/{group_id})
+   - account: Your account resource name (accounts/{account_id})
+   - side: LIMIT_ORDER_SIDE_BUY
+   - limit_price: Maximum price willing to pay (e.g., 100.50 USDC)
+   - quantity: Amount to purchase (e.g., 10 USDC)
+   - external_reference: Optional unique identifier for your system
+3. Receive LimitOrder response with system-generated resource name
+4. Monitor order status until LIMIT_ORDER_STATUS_OPEN
+```
+
+### Checking Order Status
+```
+1. Call GetLimitOrder with live_ledger_data: true
+2. Inspect the status field:
+   - LIMIT_ORDER_STATUS_SUBMISSION_IN_PROGRESS: Order submitting to ledger
+   - LIMIT_ORDER_STATUS_SUBMISSION_FAILED: Order submission failed
+   - LIMIT_ORDER_STATUS_OPEN: Order is active on the ledger
+   - LIMIT_ORDER_STATUS_COMPLETE_IN_PROGRESS: Order completing
+   - LIMIT_ORDER_STATUS_COMPLETE: Order has been completely filled
+   - LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS: Cancellation in progress
+   - LIMIT_ORDER_STATUS_CANCELLED: Order was successfully cancelled
+```
+
+### Cancelling an Order
+```
+1. Call CancelLimitOrder with the order's resource name
+2. Receive LimitOrder response with initial status
+3. Monitor status transitions:
+   - LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS: Cancel submitted to ledger
+   - LIMIT_ORDER_STATUS_CANCELLED: Cancel confirmed on ledger
+```
+
+### Monitoring Orders in Real-Time
+```
+1. Call MonitorLimitOrder (server-streaming RPC)
+2. Specify order by name OR external_reference (one required)
+3. Receive continuous stream of order updates as ledger state changes
+4. React to status changes, fills, or cancellations in real-time
+```
+
+### Searching Orders
+```
+1. Call SearchLimitOrders with optional filters:
+   - token: Filter by token code (e.g., "USDC")
+   - account: Filter by specific account resource name
+   - live_ledger_data: Enrich with current ledger status
+2. Returns all matching limit orders in response
+```
 
 ## Authentication & Authorization
 
-This service requires appropriate role-based permissions. 
-See the individual method documentation for specific role requirements.
+This service requires role-based permissions from the trading domain:
+
+| Role | Permissions |
+|------|-------------|
+| `ROLE_TRADING_LIMIT_ORDER_ADMIN` | Full access: create, cancel, read all orders in group hierarchy |
+| `ROLE_TRADING_LIMIT_ORDER_VIEWER` | Read-only access: get, list, search, monitor orders in group hierarchy |
+
+All RPCs validate that the caller's group matches or is an ancestor of the requested resource's owner group.

docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.go

@@ -19,17 +19,54 @@ func main() {
 	}
 	defer service.Close()
 
-	// Create request with service-specific parameters
+	// 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{
-		// FIXME: Populate service-specific request fields
+		Name: orderName,
 	}
 
 	// Call the CancelLimitOrder method
-	limitOrder, err := service.CancelLimitOrder(ctx, request)
+	response, err := service.CancelLimitOrder(ctx, request)
 	if err != nil {
 		log.Fatalf("CancelLimitOrder failed: %v", err)
 	}
 
-	// FIXME: Add relevant response object usage
-	log.Printf("CancelLimitOrder successful: %+v", limitOrder)
+	// Response contains the cancellation status
+	log.Printf("✓ Limit order cancellation initiated:")
+	log.Printf("  Order name: %s", orderName)
+	log.Printf("  Status: %s", response.Status)
+
+	// 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("  Status: %s", update.Status)
+
+		switch update.Status {
+		case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS:
+			log.Printf("  ⏳ Order cancellation in progress...")
+
+		case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_CANCELLED:
+			log.Printf("  ✓ Order successfully cancelled on ledger!")
+			break monitorOrder
+		}
+	}
 }

docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.java

@@ -1,7 +1,10 @@
+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.LimitOrder.LimitOrder;
+import co.meshtrade.api.trading.limit_order.v1.Service.MonitorLimitOrderRequest;
 
+import java.util.Iterator;
 import java.util.Optional;
 
 public class CancelLimitOrderExample {
@@ -10,16 +13,48 @@ public static void main(String[] args) {
         // environment variable or default discovery methods. Zero config required
         // unless you want custom configuration.
         try (LimitOrderService service = new LimitOrderService()) {
-            // Create request with service-specific parameters
+            // 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()
-                // FIXME: Populate service-specific request fields
+                .setName(orderName)
                 .build();
 
             // Call the CancelLimitOrder method
-            LimitOrder limitOrder = service.cancelLimitOrder(request, Optional.empty());
+            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;
 
-            // FIXME: Add relevant response object usage
-            System.out.println("CancelLimitOrder successful: " + limitOrder);
+                    default:
+                        break;
+                }
+            }
         } catch (Exception e) {
             System.err.println("CancelLimitOrder failed: " + e.getMessage());
             e.printStackTrace();

docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.py

@@ -1,6 +1,8 @@
 from meshtrade.trading.limit_order.v1 import (
     CancelLimitOrderRequest,
     LimitOrderService,
+    LimitOrderStatus,
+    MonitorLimitOrderRequest,
 )
 
 
@@ -11,16 +13,39 @@ def main():
     service = LimitOrderService()
 
     with service:
-        # Create request with service-specific parameters
+        # 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(
-            # FIXME: Populate service-specific request fields
+            name=order_name,
         )
 
         # Call the CancelLimitOrder method
-        limit_order = service.cancel_limit_order(request)
+        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...")
 
-        # FIXME: Add relevant response object usage
-        print("CancelLimitOrder successful:", limit_order)
+            elif update.status == LimitOrderStatus.LIMIT_ORDER_STATUS_CANCELLED:
+                print("  ✓ Order successfully cancelled on ledger!")
+                break
 
 
 if __name__ == "__main__":