Testing Guide

Overview

This testing guide is designed to help developers and QA teams test the Stock Protocol Maker API in a controlled environment. The guide explains how to simulate different order states and lifecycle scenarios using predefined quantity rules.

The mock matching engine returns consistent responses based on the order quantity values you submit. This allows you to verify various order status behaviors without requiring actual blockchain transactions or real market conditions.

Purpose

• Validate order creation and lifecycle management
• Test order state transitions (pending, partially filled, filled, rejected, cancelled)
• Verify API responses for different scenarios
• Ensure proper error handling and edge cases
• Prepare for production deployment with confidence

Testing Environment

Base URL: Use {API_BASE_URL} placeholder for your testing environment

Authentication: Required - Use JWT token obtained from Authorization API

Blockchain: BSC Testnet (Chain ID: 97) or configured test network

Order Quantity Rules

To simulate different order states, use the following quantity patterns when creating orders:

Market-Specific Rules

• No minimum quantity restrictions for US stocks
• Can use any quantity following the patterns below

Quantity Patterns

1. Pending Orders (Awaiting Fill)

Pattern: Quantities ending in 1 (e.g., 1, 10, 100, 1000, 10000)

Expected Behavior:

• Order is created and remains in pending state
• No fills are executed
• Order stays on the order book waiting for takers

Use Case: Test order creation and order book listing

Example Quantities:

1, 10, 100, 1000, 10000

---

2. Partially Filled Orders

Pattern: Quantities ending in 2 (e.g., 2, 20, 200, 2000, 20000)

Expected Behavior:

• Order is created and immediately partially filled
• Order status becomes partially_filled
• Remaining quantity stays on order book
• Fill records are generated

Use Case: Test partial execution and remaining quantity tracking

Example Quantities:

2, 20, 200, 2000, 20000

---

3. Rejected Orders

Pattern: Quantities ending in 3 (e.g., 3, 30, 300, 3000, 30000)

Expected Behavior:

• Order is rejected by the system
• Order status becomes rejected
• No fills are executed
• Error message is returned

Use Case: Test error handling and rejection scenarios

Example Quantities:

3, 30, 300, 3000, 30000

---

4. Partially Cancelled Orders

Pattern: Quantities ending in 4 (e.g., 4, 40, 400, 4000, 40000)

Expected Behavior:

• Order is created and partially filled
• Remaining quantity is automatically cancelled
• Order status becomes cancelled
• Fill records show partial execution before cancellation

Use Case: Test cancellation with partial fills

Example Quantities:

4, 40, 400, 4000, 40000

---

5. Fully Cancelled Orders

Pattern: Quantities ending in 5 (e.g., 5, 50, 500, 5000, 50000)

Expected Behavior:

• Order is created without any fills
• Order is immediately cancelled
• Order status becomes cancelled
• No fill records are generated

Use Case: Test full cancellation without execution

Example Quantities:

5, 50, 500, 5000, 50000

---

6. Fully Filled Orders

Pattern: Quantities ending in 6 (e.g., 6, 60, 600, 6000, 60000)

Expected Behavior:

• Order is created and immediately fully filled
• Order status becomes filled
• Complete fill records are generated
• No remaining quantity on order book

Use Case: Test complete order execution

Example Quantities:

6, 60, 600, 6000, 60000

---

Testing Matrix

Quantity	Last Digit	Expected Status	Filled Qty	Remaining Qty	Description
1	1	pending	0	1	Order awaiting fill
2	2	partially_filled	~1	~1	Partial execution
3	3	rejected	0	0	Order rejected
4	4	cancelled	~2	0	Partial fill then cancelled
5	5	cancelled	0	0	Fully cancelled
6	6	filled	6	0	Fully executed

Query Order Status

After creating orders, query their status using:

curl -X GET "{API_BASE_URL}/api/v1/orders/{order_id}" \
     -H "Authorization: Bearer {JWT_TOKEN}"

Or list all orders:

curl -X GET "{API_BASE_URL}/api/v1/orders?status=pending" \
     -H "Authorization: Bearer {JWT_TOKEN}"

Best Practices

1. Test All States

Create a comprehensive test suite covering all quantity patterns:

• 1 order for each pattern (1, 2, 3, 4, 5, 6)
• Multiple quantities per pattern (10, 100, 1000)
• Different tickers and sides (buy/sell)

2. Verify State Transitions

Monitor order state changes:

• Check initial state after creation
• Query status after expected transitions
• Verify fill records match expected behavior

3. Test Error Scenarios

• Invalid quantities (negative, zero)
• Invalid prices
• Expired orders
• Insufficient balance (if applicable)

4. Clean Up Test Data

After testing, cancel pending orders:

curl -X DELETE "{API_BASE_URL}/api/v1/orders/{order_id}" \
     -H "Authorization: Bearer {JWT_TOKEN}"

Order Status Reference

Status	Description	Can Cancel	Has Fills
pending	Order on book, awaiting fill	Yes	No
partially_filled	Order partially executed	Yes	Yes
filled	Order fully executed	No	Yes
cancelled	Order cancelled by user/system	No	Maybe
rejected	Order rejected by system	No	No
expired	Order expired (past expiry time)	No	Maybe

Troubleshooting

Issue: Order not created

Solution: Check authentication token, verify all required fields, ensure quantity follows valid pattern

Issue: Unexpected order status

Solution: Verify quantity last digit matches expected pattern, check order query timing

Issue: Cannot query order

Solution: Ensure order_id is correct, verify authentication, check order hasn't expired

Issue: Fill records missing

Solution: Only orders with quantities ending in 2, 4, or 6 have fills in testing environment

Additional Resources

• Authorization API - Obtain JWT token
• Create Order API - Order creation details
• Query Orders API - Order query endpoints
• Cancel Order API - Order cancellation

Support

For testing environment issues or questions:

• Check API response error messages
• Review this testing guide
• Contact development team with order IDs and timestamps

---

Note: This testing guide applies only to testing/sandbox environments. Production environments use real blockchain transactions and market conditions.