Skip to content

Commit 6e4e841

Browse files
LawrenceMarsmanBRBussyclaude
authored
Fix limit order API examples and documentation (#116)
* SDK fixes and examples * fix(docs): Correct limit order API examples and documentation Fix multiple inaccuracies across all limit order API examples (Go, Python, Java) and service documentation: API Example Corrections: - Add missing type_v1 import to Go create example - Fix resource name format from nested to flat (limit_orders/{id}) - Remove invalid pagination fields (page_size, page_token, next_page_token) from list/search - Remove invalid external_reference filter from SearchLimitOrders - Fix MonitorLimitOrder to use oneof identifier (name OR external_reference) - Correct return type for CancelLimitOrder (returns LimitOrder, not response wrapper) - Add required owner field to CreateLimitOrder examples - Replace non-existent status enums (FILLED, PARTIALLY_FILLED) with correct ones (COMPLETE) Enhanced Examples with State Monitoring: - Update monitor examples to handle all 7 limit order states - Add monitoring to create examples until order reaches OPEN status - Add monitoring to cancel examples until order reaches CANCELLED status - Show proper handling of transient states (SUBMISSION_IN_PROGRESS, CANCELLATION_IN_PROGRESS, etc.) - Use labeled breaks for clean monitoring loop exits Documentation Fixes (index.mdx): - Correct resource naming from nested hierarchy to flat format - Fix status enum names throughout (COMPLETE not FILLED) - Remove references to non-existent pagination in SearchLimitOrders - Clarify MonitorLimitOrder request structure (oneof, not filters) - Add all 7 order states to status documentation - Include owner field requirement in create workflow All changes verified against protobuf definitions in proto/meshtrade/trading/limit_order/v1/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Bernard Bussy <[email protected]> Co-authored-by: Claude <[email protected]>
1 parent e24dec8 commit 6e4e841

File tree

24 files changed

+881
-121
lines changed

24 files changed

+881
-121
lines changed

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

Lines changed: 93 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -21,30 +21,109 @@ This warning will be removed once complete and ready for use.
2121

2222
## Overview
2323

24-
LimitOrderService manages limit orders for trading operations (BETA).
24+
LimitOrderService manages limit orders for trading operations on supported ledgers (currently Stellar).
2525

26-
This service provides comprehensive limit order management capabilities including
27-
order creation, cancellation, querying, and real-time monitoring. All operations
28-
are scoped to the authenticated group's hierarchy and require appropriate trading
29-
domain permissions.
26+
This service provides comprehensive limit order management capabilities including:
27+
- **Order creation** with flexible pricing and quantity specifications
28+
- **Order cancellation** for active orders
29+
- **Order querying** by resource name or external reference
30+
- **Order listing and searching** with optional filters
31+
- **Real-time monitoring** via server-side streaming
32+
- **Live ledger data** integration for up-to-date order status
33+
34+
All operations are scoped to the authenticated group's hierarchy and require appropriate trading domain permissions.
3035

3136
Note: This service is currently in BETA. Interface and functionality may change.
3237

33-
Add your custom documentation for the Trading Limit Order v1 service here.
34-
This file is generated once and can be manually edited to provide
35-
service-specific information, examples, and usage guidance.
38+
## Key Features
39+
40+
### Live Ledger Data
41+
Many read operations support an optional `live_ledger_data` flag that enriches responses with real-time ledger state:
42+
- When `false` (default): Returns persisted order metadata with `LIMIT_ORDER_STATUS_UNSPECIFIED`
43+
- When `true`: Queries the underlying ledger and populates current order status (e.g., `LIMIT_ORDER_STATUS_OPEN`, `LIMIT_ORDER_STATUS_COMPLETE`)
44+
45+
### External References
46+
Each limit order can be tagged with a unique `external_reference` string, enabling:
47+
- Integration with external trading systems
48+
- Order tracking across multiple systems
49+
- Quick lookup via `GetLimitOrderByExternalReference`
50+
51+
### Resource Naming
52+
Limit orders use a flat resource name format:
53+
```
54+
limit_orders/{order_id}
55+
```
56+
Where `{order_id}` is a system-generated ULIDv2 identifier (26 characters).
3657

3758
## Quick Start
3859

39-
1. **Configure your client** with the appropriate credentials
40-
2. **Choose your operations** from the available service methods
41-
3. **Review the types** to understand request/response structures
60+
1. **Obtain credentials** with `ROLE_TRADING_LIMIT_ORDER_ADMIN` or `ROLE_TRADING_LIMIT_ORDER_VIEWER`
61+
2. **Create an account** on your desired ledger (e.g., Stellar) using the Wallet Account service
62+
3. **Create a limit order** specifying price, quantity, and order side (buy/sell)
63+
4. **Monitor your order** using `GetLimitOrder` with `live_ledger_data: true` or stream updates via `MonitorLimitOrder`
4264

4365
## Common Workflows
4466

45-
Add common workflow documentation here specific to this service.
67+
### Creating a Buy Order
68+
```
69+
1. Ensure you have a Stellar account (via Wallet Account service)
70+
2. Call CreateLimitOrder with:
71+
- owner: Your group resource name (groups/{group_id})
72+
- account: Your account resource name (accounts/{account_id})
73+
- side: LIMIT_ORDER_SIDE_BUY
74+
- limit_price: Maximum price willing to pay (e.g., 100.50 USDC)
75+
- quantity: Amount to purchase (e.g., 10 USDC)
76+
- external_reference: Optional unique identifier for your system
77+
3. Receive LimitOrder response with system-generated resource name
78+
4. Monitor order status until LIMIT_ORDER_STATUS_OPEN
79+
```
80+
81+
### Checking Order Status
82+
```
83+
1. Call GetLimitOrder with live_ledger_data: true
84+
2. Inspect the status field:
85+
- LIMIT_ORDER_STATUS_SUBMISSION_IN_PROGRESS: Order submitting to ledger
86+
- LIMIT_ORDER_STATUS_SUBMISSION_FAILED: Order submission failed
87+
- LIMIT_ORDER_STATUS_OPEN: Order is active on the ledger
88+
- LIMIT_ORDER_STATUS_COMPLETE_IN_PROGRESS: Order completing
89+
- LIMIT_ORDER_STATUS_COMPLETE: Order has been completely filled
90+
- LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS: Cancellation in progress
91+
- LIMIT_ORDER_STATUS_CANCELLED: Order was successfully cancelled
92+
```
93+
94+
### Cancelling an Order
95+
```
96+
1. Call CancelLimitOrder with the order's resource name
97+
2. Receive LimitOrder response with initial status
98+
3. Monitor status transitions:
99+
- LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS: Cancel submitted to ledger
100+
- LIMIT_ORDER_STATUS_CANCELLED: Cancel confirmed on ledger
101+
```
102+
103+
### Monitoring Orders in Real-Time
104+
```
105+
1. Call MonitorLimitOrder (server-streaming RPC)
106+
2. Specify order by name OR external_reference (one required)
107+
3. Receive continuous stream of order updates as ledger state changes
108+
4. React to status changes, fills, or cancellations in real-time
109+
```
110+
111+
### Searching Orders
112+
```
113+
1. Call SearchLimitOrders with optional filters:
114+
- token: Filter by token code (e.g., "USDC")
115+
- account: Filter by specific account resource name
116+
- live_ledger_data: Enrich with current ledger status
117+
2. Returns all matching limit orders in response
118+
```
46119

47120
## Authentication & Authorization
48121

49-
This service requires appropriate role-based permissions.
50-
See the individual method documentation for specific role requirements.
122+
This service requires role-based permissions from the trading domain:
123+
124+
| Role | Permissions |
125+
|------|-------------|
126+
| `ROLE_TRADING_LIMIT_ORDER_ADMIN` | Full access: create, cancel, read all orders in group hierarchy |
127+
| `ROLE_TRADING_LIMIT_ORDER_VIEWER` | Read-only access: get, list, search, monitor orders in group hierarchy |
128+
129+
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‎

Lines changed: 42 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,17 +19,54 @@ func main() {
1919
}
2020
defer service.Close()
2121

22-
// Create request with service-specific parameters
22+
// Cancel an active limit order by its resource name
23+
// Replace with an actual limit order resource name from your system
24+
orderName := "limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9"
25+
2326
request := &limit_orderv1.CancelLimitOrderRequest{
24-
// FIXME: Populate service-specific request fields
27+
Name: orderName,
2528
}
2629

2730
// Call the CancelLimitOrder method
28-
limitOrder, err := service.CancelLimitOrder(ctx, request)
31+
response, err := service.CancelLimitOrder(ctx, request)
2932
if err != nil {
3033
log.Fatalf("CancelLimitOrder failed: %v", err)
3134
}
3235

33-
// FIXME: Add relevant response object usage
34-
log.Printf("CancelLimitOrder successful: %+v", limitOrder)
36+
// Response contains the cancellation status
37+
log.Printf("✓ Limit order cancellation initiated:")
38+
log.Printf(" Order name: %s", orderName)
39+
log.Printf(" Status: %s", response.Status)
40+
41+
// Monitor the order until cancellation is complete
42+
log.Printf("\n📡 Monitoring order until cancellation is complete...")
43+
monitorRequest := &limit_orderv1.MonitorLimitOrderRequest{
44+
Identifier: &limit_orderv1.MonitorLimitOrderRequest_Name{
45+
Name: orderName,
46+
},
47+
}
48+
49+
stream, err := service.MonitorLimitOrder(ctx, monitorRequest)
50+
if err != nil {
51+
log.Fatalf("MonitorLimitOrder failed: %v", err)
52+
}
53+
54+
monitorOrder:
55+
for {
56+
update, err := stream.Recv()
57+
if err != nil {
58+
log.Fatalf("Stream error: %v", err)
59+
}
60+
61+
log.Printf(" Status: %s", update.Status)
62+
63+
switch update.Status {
64+
case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS:
65+
log.Printf(" ⏳ Order cancellation in progress...")
66+
67+
case limit_orderv1.LimitOrderStatus_LIMIT_ORDER_STATUS_CANCELLED:
68+
log.Printf(" ✓ Order successfully cancelled on ledger!")
69+
break monitorOrder
70+
}
71+
}
3572
}

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

Lines changed: 41 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
1+
import co.meshtrade.api.trading.limit_order.v1.LimitOrderOuterClass.LimitOrder;
2+
import co.meshtrade.api.trading.limit_order.v1.LimitOrderOuterClass.LimitOrderStatus;
13
import co.meshtrade.api.trading.limit_order.v1.LimitOrderService;
24
import co.meshtrade.api.trading.limit_order.v1.Service.CancelLimitOrderRequest;
3-
import co.meshtrade.api.trading.limit_order.v1.LimitOrder.LimitOrder;
5+
import co.meshtrade.api.trading.limit_order.v1.Service.MonitorLimitOrderRequest;
46

7+
import java.util.Iterator;
58
import java.util.Optional;
69

710
public class CancelLimitOrderExample {
@@ -10,16 +13,48 @@ public static void main(String[] args) {
1013
// environment variable or default discovery methods. Zero config required
1114
// unless you want custom configuration.
1215
try (LimitOrderService service = new LimitOrderService()) {
13-
// Create request with service-specific parameters
16+
// Cancel an active limit order by its resource name
17+
// Replace with an actual limit order resource name from your system
18+
String orderName = "limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9";
19+
1420
CancelLimitOrderRequest request = CancelLimitOrderRequest.newBuilder()
15-
// FIXME: Populate service-specific request fields
21+
.setName(orderName)
1622
.build();
1723

1824
// Call the CancelLimitOrder method
19-
LimitOrder limitOrder = service.cancelLimitOrder(request, Optional.empty());
25+
LimitOrder response = service.cancelLimitOrder(request, Optional.empty());
26+
27+
// Response contains the cancellation status
28+
System.out.println("✓ Limit order cancellation initiated:");
29+
System.out.println(" Order name: " + orderName);
30+
System.out.println(" Status: " + response.getStatus());
31+
32+
// Monitor the order until cancellation is complete
33+
System.out.println("\n📡 Monitoring order until cancellation is complete...");
34+
MonitorLimitOrderRequest monitorRequest = MonitorLimitOrderRequest.newBuilder()
35+
.setName(orderName)
36+
.build();
37+
38+
Iterator<LimitOrder> stream = service.monitorLimitOrder(monitorRequest, Optional.empty());
39+
40+
monitorOrder:
41+
while (stream.hasNext()) {
42+
LimitOrder update = stream.next();
43+
System.out.println(" Status: " + update.getStatus());
44+
45+
switch (update.getStatus()) {
46+
case LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS:
47+
System.out.println(" ⏳ Order cancellation in progress...");
48+
break;
49+
50+
case LIMIT_ORDER_STATUS_CANCELLED:
51+
System.out.println(" ✓ Order successfully cancelled on ledger!");
52+
break monitorOrder;
2053

21-
// FIXME: Add relevant response object usage
22-
System.out.println("CancelLimitOrder successful: " + limitOrder);
54+
default:
55+
break;
56+
}
57+
}
2358
} catch (Exception e) {
2459
System.err.println("CancelLimitOrder failed: " + e.getMessage());
2560
e.printStackTrace();

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

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
from meshtrade.trading.limit_order.v1 import (
22
CancelLimitOrderRequest,
33
LimitOrderService,
4+
LimitOrderStatus,
5+
MonitorLimitOrderRequest,
46
)
57

68

@@ -11,16 +13,39 @@ def main():
1113
service = LimitOrderService()
1214

1315
with service:
14-
# Create request with service-specific parameters
16+
# Cancel an active limit order by its resource name
17+
# Replace with an actual limit order resource name from your system
18+
order_name = "limit_orders/01HQVBZ9F8X2T3K4M5N6P7Q8R9"
19+
1520
request = CancelLimitOrderRequest(
16-
# FIXME: Populate service-specific request fields
21+
name=order_name,
1722
)
1823

1924
# Call the CancelLimitOrder method
20-
limit_order = service.cancel_limit_order(request)
25+
response = service.cancel_limit_order(request)
26+
27+
# Response contains the cancellation status
28+
print("✓ Limit order cancellation initiated:")
29+
print(f" Order name: {order_name}")
30+
print(f" Status: {response.status}")
31+
32+
# Monitor the order until cancellation is complete
33+
print("\n📡 Monitoring order until cancellation is complete...")
34+
monitor_request = MonitorLimitOrderRequest(
35+
name=order_name,
36+
)
37+
38+
stream = service.monitor_limit_order(monitor_request)
39+
40+
for update in stream:
41+
print(f" Status: {update.status}")
42+
43+
if update.status == LimitOrderStatus.LIMIT_ORDER_STATUS_CANCELLATION_IN_PROGRESS:
44+
print(" ⏳ Order cancellation in progress...")
2145

22-
# FIXME: Add relevant response object usage
23-
print("CancelLimitOrder successful:", limit_order)
46+
elif update.status == LimitOrderStatus.LIMIT_ORDER_STATUS_CANCELLED:
47+
print(" ✓ Order successfully cancelled on ledger!")
48+
break
2449

2550

2651
if __name__ == "__main__":

0 commit comments

Comments
 (0)