Trading Limit Order v1 Service

Skip The Details?

• 👉 Jump to Package Types
• 👉 Jump to Service Methods

SDK and Documentation Under Construction 🚧

This warning will be removed once complete and ready for use.

Overview

LimitOrderService manages limit orders for trading operations on supported ledgers (currently Stellar).

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.

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_STATE_UNSPECIFIED
• When true: Queries the underlying ledger and populates current order status (e.g., LIMIT_ORDER_STATE_OPEN, LIMIT_ORDER_STATE_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. 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

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_STATE_OPEN

Checking Order Status

1. Call GetLimitOrder with live_ledger_data: true
2. Inspect the status field:
   - LIMIT_ORDER_STATE_SUBMISSION_IN_PROGRESS: Order submitting to ledger
   - LIMIT_ORDER_STATE_SUBMISSION_FAILED: Order submission failed
   - LIMIT_ORDER_STATE_OPEN: Order is active on the ledger
   - LIMIT_ORDER_STATE_COMPLETE_IN_PROGRESS: Order completing
   - LIMIT_ORDER_STATE_COMPLETE: Order has been completely filled
   - LIMIT_ORDER_STATE_CANCELLATION_IN_PROGRESS: Cancellation in progress
   - LIMIT_ORDER_STATE_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_STATE_CANCELLATION_IN_PROGRESS: Cancel submitted to ledger
   - LIMIT_ORDER_STATE_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 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.