diff --git a/docs/docs/api-reference/trading/limit_order/v1/index.mdx b/docs/docs/api-reference/trading/limit_order/v1/index.mdx index aa71a464..da542a1d 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/index.mdx +++ b/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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.go b/docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.go index 8a8c4e50..61e11e53 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.go +++ b/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 + } + } } diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.java b/docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.java index 34531b90..6ce8f751 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.java +++ b/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 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(); diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.py b/docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.py index 1174219d..626adf0c 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/cancel-limit-order/example.py +++ b/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__": diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.go b/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.go index 2454e30f..1fe825ae 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.go +++ b/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.go @@ -5,6 +5,7 @@ import ( "log" limit_orderv1 "github.com/meshtrade/api/go/trading/limit_order/v1" + type_v1 "github.com/meshtrade/api/go/type/v1" ) func main() { @@ -19,9 +20,41 @@ func main() { } defer service.Close() - // Create request with service-specific parameters + // 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{ - // FIXME: Populate service-specific request fields + 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 @@ -30,6 +63,47 @@ func main() { log.Fatalf("CreateLimitOrder failed: %v", err) } - // FIXME: Add relevant response object usage - log.Printf("CreateLimitOrder successful: %+v", limitOrder) + // Response contains the created order with system-generated resource name + log.Printf("āœ“ Limit order created successfully!") + log.Printf(" Resource name: %s", limitOrder.Name) + 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(" Status: %s", update.Status) + + switch update.Status { + case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_SUBMISSION_IN_PROGRESS: + log.Printf(" ā³ Order submission in progress...") + + case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_SUBMISSION_FAILED: + log.Fatalf(" āŒ Order submission failed") + + case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_OPEN: + log.Printf(" āœ“ Order is now open on the ledger and available for matching!") + break monitorOrder + } + } } diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.java b/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.java index ac95003d..4bcbead8 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.java +++ b/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.java @@ -1,7 +1,15 @@ +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.LimitOrder.LimitOrder; +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 { @@ -10,16 +18,96 @@ 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 + // 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() - // FIXME: Populate service-specific request fields + .setLimitOrder(limitOrderToCreate) .build(); // Call the CreateLimitOrder method LimitOrder limitOrder = service.createLimitOrder(request, Optional.empty()); - // FIXME: Add relevant response object usage - System.out.println("CreateLimitOrder successful: " + limitOrder); + // Response contains the created order with system-generated resource name + System.out.println("āœ“ Limit order created successfully!"); + System.out.println(" Resource name: " + limitOrder.getName()); + 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 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(); diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.py b/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.py index 2e21377a..a23e9c4b 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.py +++ b/docs/docs/api-reference/trading/limit_order/v1/service/create-limit-order/example.py @@ -1,7 +1,12 @@ from meshtrade.trading.limit_order.v1 import ( CreateLimitOrderRequest, + LimitOrder, LimitOrderService, + LimitOrderSide, + LimitOrderStatus, + MonitorLimitOrderRequest, ) +from meshtrade.type.v1 import Amount, Decimal, Ledger, Token def main(): @@ -11,16 +16,72 @@ def main(): service = LimitOrderService() with service: - # Create request with service-specific parameters + # 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( - # FIXME: Populate service-specific request fields + 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) - # FIXME: Add relevant response object usage - print("CreateLimitOrder successful:", limit_order) + # Response contains the created order with system-generated resource name + print("āœ“ Limit order created successfully!") + print(f" Resource name: {limit_order.name}") + 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__": diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.go b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.go index fc7d6ffe..439c5281 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.go +++ b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.go @@ -19,9 +19,12 @@ func main() { } defer service.Close() - // Create request with service-specific parameters + // 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{ - // FIXME: Populate service-specific request fields + ExternalReference: externalRef, } // Call the GetLimitOrderByExternalReference method @@ -30,6 +33,13 @@ func main() { log.Fatalf("GetLimitOrderByExternalReference failed: %v", err) } - // FIXME: Add relevant response object usage - log.Printf("GetLimitOrderByExternalReference successful: %+v", limitOrder) + // 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") } diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.java b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.java index 2a6fb91f..55091602 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.java +++ b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.java @@ -1,6 +1,6 @@ +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 co.meshtrade.api.trading.limit_order.v1.LimitOrder.LimitOrder; import java.util.Optional; @@ -10,16 +10,28 @@ 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 + // 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() - // FIXME: Populate service-specific request fields + .setExternalReference(externalRef) .build(); // Call the GetLimitOrderByExternalReference method LimitOrder limitOrder = service.getLimitOrderByExternalReference(request, Optional.empty()); - // FIXME: Add relevant response object usage - System.out.println("GetLimitOrderByExternalReference successful: " + limitOrder); + // 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(); diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.py b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.py index 6a4468e3..c9098ce6 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.py +++ b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order-by-external-reference/example.py @@ -11,16 +11,26 @@ def main(): service = LimitOrderService() with service: - # Create request with service-specific parameters + # 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( - # FIXME: Populate service-specific request fields + external_reference=external_ref, ) # Call the GetLimitOrderByExternalReference method limit_order = service.get_limit_order_by_external_reference(request) - # FIXME: Add relevant response object usage - print("GetLimitOrderByExternalReference successful:", limit_order) + # 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__": diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.go b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.go index 79a3fcfc..5cc7d949 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.go +++ b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.go @@ -19,17 +19,42 @@ func main() { } defer service.Close() - // Create request with service-specific parameters + // 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{ - // FIXME: Populate service-specific request fields + Name: orderName, + LiveLedgerData: false, } - // Call the GetLimitOrder method limitOrder, err := service.GetLimitOrder(ctx, request) if err != nil { log.Fatalf("GetLimitOrder failed: %v", err) } - // FIXME: Add relevant response object usage - log.Printf("GetLimitOrder successful: %+v", limitOrder) + log.Printf("āœ“ Limit order retrieved (cached data):") + log.Printf(" Resource name: %s", limitOrder.Name) + log.Printf(" Account: %s", limitOrder.Account) + log.Printf(" External reference: %s", limitOrder.ExternalReference) + log.Printf(" Side: %s", limitOrder.Side) + log.Printf(" Status: %s (UNSPECIFIED when live_ledger_data=false)", limitOrder.Status) + + // 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(" Status: %s", limitOrderWithStatus.Status) + 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) } diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.java b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.java index 9b894779..46a2d85e 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.java +++ b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.java @@ -1,6 +1,6 @@ +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 co.meshtrade.api.trading.limit_order.v1.LimitOrder.LimitOrder; import java.util.Optional; @@ -10,16 +10,40 @@ 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 + // 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() - // FIXME: Populate service-specific request fields + .setName(orderName) + .setLiveLedgerData(false) .build(); - // Call the GetLimitOrder method LimitOrder limitOrder = service.getLimitOrder(request, Optional.empty()); - // FIXME: Add relevant response object usage - System.out.println("GetLimitOrder successful: " + limitOrder); + System.out.println("āœ“ Limit order retrieved (cached data):"); + System.out.println(" Resource name: " + limitOrder.getName()); + 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(); diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.py b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.py index da659cb0..6d179df0 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.py +++ b/docs/docs/api-reference/trading/limit_order/v1/service/get-limit-order/example.py @@ -11,16 +11,38 @@ def main(): service = LimitOrderService() with service: - # Create request with service-specific parameters + # 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( - # FIXME: Populate service-specific request fields + name=order_name, + live_ledger_data=False, ) - # Call the GetLimitOrder method limit_order = service.get_limit_order(request) - # FIXME: Add relevant response object usage - print("GetLimitOrder successful:", limit_order) + print("āœ“ Limit order retrieved (cached data):") + print(f" Resource name: {limit_order.name}") + 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__": diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.go b/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.go index fa01862b..62c13d31 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.go +++ b/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.go @@ -19,9 +19,10 @@ func main() { } defer service.Close() - // Create request with service-specific parameters + // List all limit orders in your group hierarchy request := &limit_orderv1.ListLimitOrdersRequest{ - // FIXME: Populate service-specific request fields + // Optional: Set to true to enrich with live ledger status (slower) + LiveLedgerData: false, } // Call the ListLimitOrders method @@ -30,6 +31,16 @@ func main() { log.Fatalf("ListLimitOrders failed: %v", err) } - // FIXME: Add relevant response object usage - log.Printf("ListLimitOrders successful: %+v", response) + // Response contains list of limit orders + log.Printf("āœ“ Listed %d limit orders:", len(response.LimitOrders)) + for i, order := range response.LimitOrders { + log.Printf("\n Order #%d:", i+1) + log.Printf(" Resource name: %s", order.Name) + log.Printf(" Account: %s", order.Account) + log.Printf(" External ref: %s", order.ExternalReference) + log.Printf(" Side: %s", order.Side) + log.Printf(" Limit price: %s %s", order.LimitPrice.Value.Value, order.LimitPrice.Token.Code) + log.Printf(" Quantity: %s %s", order.Quantity.Value.Value, order.Quantity.Token.Code) + log.Printf(" Status: %s", order.Status) + } } diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.java b/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.java index edfda7d0..b5fde615 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.java +++ b/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.java @@ -1,3 +1,4 @@ +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.ListLimitOrdersRequest; import co.meshtrade.api.trading.limit_order.v1.Service.ListLimitOrdersResponse; @@ -10,16 +11,31 @@ 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 + // List all limit orders in your group hierarchy ListLimitOrdersRequest request = ListLimitOrdersRequest.newBuilder() - // FIXME: Populate service-specific request fields + // Optional: Set to true to enrich with live ledger status (slower) + .setLiveLedgerData(false) .build(); // Call the ListLimitOrders method ListLimitOrdersResponse response = service.listLimitOrders(request, Optional.empty()); - // FIXME: Add relevant response object usage - System.out.println("ListLimitOrders successful: " + response); + // Response contains list of limit orders + System.out.println("āœ“ Listed " + response.getLimitOrdersCount() + " limit orders:"); + int i = 1; + for (LimitOrder order : response.getLimitOrdersList()) { + System.out.println("\n Order #" + i + ":"); + System.out.println(" Resource name: " + order.getName()); + System.out.println(" Account: " + order.getAccount()); + System.out.println(" External ref: " + order.getExternalReference()); + System.out.println(" Side: " + order.getSide()); + System.out.println(" Limit price: " + order.getLimitPrice().getValue().getValue() + + " " + order.getLimitPrice().getToken().getCode()); + System.out.println(" Quantity: " + order.getQuantity().getValue().getValue() + + " " + order.getQuantity().getToken().getCode()); + System.out.println(" Status: " + order.getStatus()); + i++; + } } catch (Exception e) { System.err.println("ListLimitOrders failed: " + e.getMessage()); e.printStackTrace(); diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.py b/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.py index de16b2e0..ddadd4c6 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.py +++ b/docs/docs/api-reference/trading/limit_order/v1/service/list-limit-orders/example.py @@ -11,16 +11,26 @@ def main(): service = LimitOrderService() with service: - # Create request with service-specific parameters + # List all limit orders in your group hierarchy request = ListLimitOrdersRequest( - # FIXME: Populate service-specific request fields + # Optional: Set to true to enrich with live ledger status (slower) + live_ledger_data=False, ) # Call the ListLimitOrders method response = service.list_limit_orders(request) - # FIXME: Add relevant response object usage - print("ListLimitOrders successful:", response) + # Response contains list of limit orders + print(f"āœ“ Listed {len(response.limit_orders)} limit orders:") + for i, order in enumerate(response.limit_orders, 1): + print(f"\n Order #{i}:") + print(f" Resource name: {order.name}") + print(f" Account: {order.account}") + print(f" External ref: {order.external_reference}") + print(f" Side: {order.side}") + print(f" Limit price: {order.limit_price.value.value} {order.limit_price.token.code}") + print(f" Quantity: {order.quantity.value.value} {order.quantity.token.code}") + print(f" Status: {order.status}") if __name__ == "__main__": diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.go b/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.go index 36186156..fbbb1884 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.go +++ b/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.go @@ -20,18 +20,36 @@ func main() { } defer service.Close() - // Create request with service-specific parameters + // Monitor a limit order in real-time via server-side streaming + // You can use either the resource name or external reference + + // Option 1: Monitor by resource name request := &limit_orderv1.MonitorLimitOrderRequest{ - // FIXME: Populate service-specific request fields + Identifier: &limit_orderv1.MonitorLimitOrderRequest_Name{ + Name: "limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9", + }, } + // Option 2: Monitor by external reference (commented out) + // request := &limit_orderv1.MonitorLimitOrderRequest{ + // Identifier: &limit_orderv1.MonitorLimitOrderRequest_ExternalReference{ + // ExternalReference: "my-trading-system-order-123", + // }, + // } + // Call the MonitorLimitOrder streaming method + // This opens a long-lived server-side stream that pushes order updates stream, err := service.MonitorLimitOrder(ctx, request) if err != nil { log.Fatalf("Failed to initiate stream: %v", err) } + log.Println("āœ“ Monitoring limit order for real-time updates...") + log.Println(" Listening for status changes... (Ctrl+C to stop)") + // Consume stream responses + // The server pushes updates whenever order status changes on the ledger +monitorOrder: for { limitOrder, err := stream.Recv() if err == io.EOF { @@ -41,9 +59,46 @@ func main() { log.Fatalf("Stream error: %v", err) } - // Process each response as it arrives - log.Printf("Received: %+v", limitOrder) + // Process each order update as it arrives + log.Printf("\nšŸ“” Status update received: %s", limitOrder.Status) + log.Printf(" Resource name: %s", limitOrder.Name) + log.Printf(" Account: %s", limitOrder.Account) + log.Printf(" External ref: %s", limitOrder.ExternalReference) + 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) + + // Handle order state transitions + switch limitOrder.Status { + case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_SUBMISSION_IN_PROGRESS: + log.Printf(" ā³ Order submission in progress...") + + case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_SUBMISSION_FAILED: + log.Printf(" āŒ Order submission failed") + break monitorOrder + + case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_OPEN: + log.Printf(" āœ“ Order open on ledger and available for matching") + // Order is active - continue monitoring for fills + + case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_COMPLETE_IN_PROGRESS: + log.Printf(" ā³ Order completion in progress...") + + case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_COMPLETE: + log.Printf(" šŸŽ‰ Order completed (fully filled)!") + break monitorOrder + + 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 cancelled") + break monitorOrder + + default: + log.Printf(" āš ļø Unexpected order status: %v", limitOrder.Status) + } } - log.Println("Stream completed successfully") + log.Println("\nāœ“ Stream completed successfully") } diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.java b/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.java index 6500c0f4..ae995b87 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.java +++ b/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.java @@ -1,6 +1,7 @@ +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.MonitorLimitOrderRequest; -import co.meshtrade.api.trading.limit_order.v1.LimitOrder.LimitOrder; import java.util.Iterator; import java.util.Optional; @@ -11,23 +12,81 @@ 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 + // Monitor a limit order in real-time via server-side streaming + // You can use either the resource name or external reference + + // Option 1: Monitor by resource name MonitorLimitOrderRequest request = MonitorLimitOrderRequest.newBuilder() - // FIXME: Populate service-specific request fields + .setName("limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9") .build(); + // Option 2: Monitor by external reference (commented out) + // MonitorLimitOrderRequest request = MonitorLimitOrderRequest.newBuilder() + // .setExternalReference("my-trading-system-order-123") + // .build(); + // Call the MonitorLimitOrder streaming method + // This opens a long-lived server-side stream that pushes order updates Iterator stream = service.monitorLimitOrder(request, Optional.empty()); - // Consume stream responses using iterator pattern + System.out.println("āœ“ Monitoring limit order for real-time updates..."); + System.out.println(" Listening for status changes... (Ctrl+C to stop)"); + + // Consume stream responses + // The server pushes updates whenever order status changes on the ledger + monitorOrder: while (stream.hasNext()) { LimitOrder limitOrder = stream.next(); - // Process each response as it arrives - System.out.println("Received: " + limitOrder); + // Process each order update as it arrives + System.out.println("\nšŸ“” Status update received: " + limitOrder.getStatus()); + System.out.println(" Resource name: " + limitOrder.getName()); + System.out.println(" Account: " + limitOrder.getAccount()); + System.out.println(" External ref: " + limitOrder.getExternalReference()); + 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()); + + // Handle order state transitions + switch (limitOrder.getStatus()) { + case LIMIT_ORDER_STATUS_SUBMISSION_IN_PROGRESS: + System.out.println(" ā³ Order submission in progress..."); + break; + + case LIMIT_ORDER_STATUS_SUBMISSION_FAILED: + System.out.println(" āŒ Order submission failed"); + break monitorOrder; + + case LIMIT_ORDER_STATUS_OPEN: + System.out.println(" āœ“ Order open on ledger and available for matching"); + // Order is active - continue monitoring for fills + break; + + case LIMIT_ORDER_STATUS_COMPLETE_IN_PROGRESS: + System.out.println(" ā³ Order completion in progress..."); + break; + + case LIMIT_ORDER_STATUS_COMPLETE: + System.out.println(" šŸŽ‰ Order completed (fully filled)!"); + break monitorOrder; + + case LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS: + System.out.println(" ā³ Order cancellation in progress..."); + break; + + case LIMIT_ORDER_STATUS_CANCELLED: + System.out.println(" āŒ Order cancelled"); + break monitorOrder; + + default: + System.out.println(" āš ļø Unexpected order status: " + limitOrder.getStatus()); + break; + } } - System.out.println("Stream completed successfully"); + System.out.println("\nāœ“ Stream completed successfully"); } catch (Exception e) { System.err.println("MonitorLimitOrder stream failed: " + e.getMessage()); e.printStackTrace(); diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.py b/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.py index 6c7f48cd..a80710c8 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.py +++ b/docs/docs/api-reference/trading/limit_order/v1/service/monitor-limit-order/example.py @@ -1,5 +1,6 @@ from meshtrade.trading.limit_order.v1 import ( LimitOrderService, + LimitOrderStatus, MonitorLimitOrderRequest, ) @@ -11,23 +12,71 @@ def main(): service = LimitOrderService() with service: - # Create request with service-specific parameters + # Monitor a limit order in real-time via server-side streaming + # You can use either the resource name or external reference + + # Option 1: Monitor by resource name request = MonitorLimitOrderRequest( - # FIXME: Populate service-specific request fields + name="limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9", ) + # Option 2: Monitor by external reference (commented out) + # request = MonitorLimitOrderRequest( + # external_reference="my-trading-system-order-123", + # ) + # Call the MonitorLimitOrder streaming method + # This opens a long-lived server-side stream that pushes order updates stream = service.monitor_limit_order(request) + print("āœ“ Monitoring limit order for real-time updates...") + print(" Listening for status changes... (Ctrl+C to stop)") + try: - # Consume stream responses using iterator pattern + # Consume stream responses + # The server pushes updates whenever order status changes on the ledger for limit_order in stream: - # Process each response as it arrives - print("Received:", limit_order) + # Process each order update as it arrives + print(f"\nšŸ“” Status update received: {limit_order.status}") + print(f" Resource name: {limit_order.name}") + print(f" Account: {limit_order.account}") + print(f" External ref: {limit_order.external_reference}") + 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}") + + # Handle order state transitions + if limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_SUBMISSION_IN_PROGRESS: + print(" ā³ Order submission in progress...") + + elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_SUBMISSION_FAILED: + print(" āŒ Order submission failed") + break + + elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_OPEN: + print(" āœ“ Order open on ledger and available for matching") + # Order is active - continue monitoring for fills + + elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_COMPLETE_IN_PROGRESS: + print(" ā³ Order completion in progress...") + + elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_COMPLETE: + print(" šŸŽ‰ Order completed (fully filled)!") + break + + elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS: + print(" ā³ Order cancellation in progress...") + + elif limit_order.status == LimitOrderStatus.LIMIT_ORDER_STATUS_CANCELLED: + print(" āŒ Order cancelled") + break + + else: + print(f" āš ļø Unexpected order status: {limit_order.status}") - print("Stream completed successfully") + print("\nāœ“ Stream completed successfully") except Exception as e: - print("Stream error:", e) + print(f"Stream error: {e}") raise diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.go b/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.go index 20d93637..96be49dd 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.go +++ b/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.go @@ -19,9 +19,17 @@ func main() { } defer service.Close() - // Create request with service-specific parameters + // Search limit orders with optional filters + // Replace with an actual account resource name from your system + accountName := "accounts/01HQVBZ9F8X2T3K4M5N6P7Q8R9" + request := &limit_orderv1.SearchLimitOrdersRequest{ - // FIXME: Populate service-specific request fields + // Optional: Filter by token code + Token: "USDC", + // Optional: Filter by account (returns only orders for this account) + Account: accountName, + // Optional: Set to true to enrich with live ledger status + LiveLedgerData: true, } // Call the SearchLimitOrders method @@ -30,6 +38,16 @@ func main() { log.Fatalf("SearchLimitOrders failed: %v", err) } - // FIXME: Add relevant response object usage - log.Printf("SearchLimitOrders successful: %+v", response) + // Response contains filtered list of limit orders + log.Printf("āœ“ Found %d limit orders matching filters:", len(response.LimitOrders)) + for i, order := range response.LimitOrders { + log.Printf("\n Order #%d:", i+1) + log.Printf(" Resource name: %s", order.Name) + log.Printf(" Account: %s", order.Account) + log.Printf(" External ref: %s", order.ExternalReference) + log.Printf(" Side: %s", order.Side) + log.Printf(" Status: %s", order.Status) + log.Printf(" Limit price: %s %s", order.LimitPrice.Value.Value, order.LimitPrice.Token.Code) + log.Printf(" Quantity: %s %s", order.Quantity.Value.Value, order.Quantity.Token.Code) + } } diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.java b/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.java index 52ea5f0b..196a6215 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.java +++ b/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.java @@ -1,3 +1,4 @@ +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.SearchLimitOrdersRequest; import co.meshtrade.api.trading.limit_order.v1.Service.SearchLimitOrdersResponse; @@ -10,16 +11,38 @@ 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 + // Search limit orders with optional filters + // Replace with an actual account resource name from your system + String accountName = "accounts/01HQVBZ9F8X2T3K4M5N6P7Q8R9"; + SearchLimitOrdersRequest request = SearchLimitOrdersRequest.newBuilder() - // FIXME: Populate service-specific request fields + // Optional: Filter by token code + .setToken("USDC") + // Optional: Filter by account (returns only orders for this account) + .setAccount(accountName) + // Optional: Set to true to enrich with live ledger status + .setLiveLedgerData(true) .build(); // Call the SearchLimitOrders method SearchLimitOrdersResponse response = service.searchLimitOrders(request, Optional.empty()); - // FIXME: Add relevant response object usage - System.out.println("SearchLimitOrders successful: " + response); + // Response contains filtered list of limit orders + System.out.println("āœ“ Found " + response.getLimitOrdersCount() + " limit orders matching filters:"); + int i = 1; + for (LimitOrder order : response.getLimitOrdersList()) { + System.out.println("\n Order #" + i + ":"); + System.out.println(" Resource name: " + order.getName()); + System.out.println(" Account: " + order.getAccount()); + System.out.println(" External ref: " + order.getExternalReference()); + System.out.println(" Side: " + order.getSide()); + System.out.println(" Status: " + order.getStatus()); + System.out.println(" Limit price: " + order.getLimitPrice().getValue().getValue() + + " " + order.getLimitPrice().getToken().getCode()); + System.out.println(" Quantity: " + order.getQuantity().getValue().getValue() + + " " + order.getQuantity().getToken().getCode()); + i++; + } } catch (Exception e) { System.err.println("SearchLimitOrders failed: " + e.getMessage()); e.printStackTrace(); diff --git a/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.py b/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.py index 49a4f0ba..369e7f61 100644 --- a/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.py +++ b/docs/docs/api-reference/trading/limit_order/v1/service/search-limit-orders/example.py @@ -11,16 +11,33 @@ def main(): service = LimitOrderService() with service: - # Create request with service-specific parameters + # Search limit orders with optional filters + # Replace with an actual account resource name from your system + account_name = "accounts/01HQVBZ9F8X2T3K4M5N6P7Q8R9" + request = SearchLimitOrdersRequest( - # FIXME: Populate service-specific request fields + # Optional: Filter by token code + token="USDC", + # Optional: Filter by account (returns only orders for this account) + account=account_name, + # Optional: Set to true to enrich with live ledger status + live_ledger_data=True, ) # Call the SearchLimitOrders method response = service.search_limit_orders(request) - # FIXME: Add relevant response object usage - print("SearchLimitOrders successful:", response) + # Response contains filtered list of limit orders + print(f"āœ“ Found {len(response.limit_orders)} limit orders matching filters:") + for i, order in enumerate(response.limit_orders, 1): + print(f"\n Order #{i}:") + print(f" Resource name: {order.name}") + print(f" Account: {order.account}") + print(f" External ref: {order.external_reference}") + print(f" Side: {order.side}") + print(f" Status: {order.status}") + print(f" Limit price: {order.limit_price.value.value} {order.limit_price.token.code}") + print(f" Quantity: {order.quantity.value.value} {order.quantity.token.code}") if __name__ == "__main__": diff --git a/go/trading/limit_order/v1/service.pb.go b/go/trading/limit_order/v1/service.pb.go index d3ee63b5..3a655ccb 100644 --- a/go/trading/limit_order/v1/service.pb.go +++ b/go/trading/limit_order/v1/service.pb.go @@ -534,9 +534,9 @@ const file_meshtrade_trading_limit_order_v1_service_proto_rawDesc = "" + "\vlimit_order\x18\x01 \x01(\v2,.meshtrade.trading.limit_order.v1.LimitOrderB\x06\xbaH\x03\xc8\x01\x01R\n" + "limitOrder\"q\n" + "\x17CancelLimitOrderRequest\x12V\n" + - "\x04name\x18\x01 \x01(\tBB\xbaH?\xc8\x01\x01r:25^limit_orders/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$\x98\x01&R\x04name\"\x98\x01\n" + + "\x04name\x18\x01 \x01(\tBB\xbaH?\xc8\x01\x01r:25^limit_orders/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$\x98\x01'R\x04name\"\x98\x01\n" + "\x14GetLimitOrderRequest\x12V\n" + - "\x04name\x18\x01 \x01(\tBB\xbaH?\xc8\x01\x01r:25^limit_orders/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$\x98\x01&R\x04name\x12(\n" + + "\x04name\x18\x01 \x01(\tBB\xbaH?\xc8\x01\x01r:25^limit_orders/[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$\x98\x01'R\x04name\x12(\n" + "\x10live_ledger_data\x18\x02 \x01(\bR\x0eliveLedgerData\"\x8a\x01\n" + "'GetLimitOrderByExternalReferenceRequest\x125\n" + "\x12external_reference\x18\x01 \x01(\tB\x06\xbaH\x03\xc8\x01\x01R\x11externalReference\x12(\n" + @@ -552,7 +552,7 @@ const file_meshtrade_trading_limit_order_v1_service_proto_rawDesc = "" + "\x19SearchLimitOrdersResponse\x12O\n" + "\flimit_orders\x18\x01 \x03(\v2,.meshtrade.trading.limit_order.v1.LimitOrderR\vlimitOrders\"\xb0\x01\n" + "\x18MonitorLimitOrderRequest\x12U\n" + - "\x04name\x18\x01 \x01(\tB?\xbaH