Testing Guide

Overview

This testing guide is designed to help developers and QA teams test the Stove Protocol Precise Execution 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 based on quantity patterns.
Test order state transitions triggered by specific quantity prefixes (e.g., PENDING → LOCKED, LOCKED → partially_filled, PENDING → LOCKED → filled).
Verify API responses for different scenarios, including normal execution, cancellation, and rejection.
Ensure proper error handling and edge cases for each quantity-driven behavior.
Prepare for production deployment with confidence by covering core order states and transitions.

Testing Environment

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

Authentication: Required - API Key + Signature. See Authorization

Blockchain: Supports the following test networks

Supported Testnets

RPC URL:             https://data-seed-prebsc-1-s1.binance.org:8545
RFQSettlement:       0xcB310c56a19078aA969a922f382613D932d89d83
StockTokenManager:   0xfd806E473FBA407963F92c41a0d3828789f1906d
Explorer:            https://testnet.bscscan.com

Obtaining Test Tokens

Before creating orders in the testing environment, you need to obtain MOCK_USDT or MOCK_USDC test tokens. The test token contracts are deployed on testnets and provide a faucet function for users to obtain test tokens for free.

Test Token Contract Addresses

MOCK_USDT: 0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91
MOCK_USDC: 0x4F891B3d31425FD9993789f0Ce0577C3e953d099
Decimals: 18

Method 1: Call faucet Function Using Web3 Libraries

javascript

import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://data-seed-prebsc-1-s1.binance.org:8545/');
const wallet = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);
const MOCK_USDT_ADDRESS = '{MOCK_USDT_ADDRESS}';

const mockERC20ABI = [
	'function faucet(uint256 amount) external',
	'function balanceOf(address account) view returns (uint256)',
];

const mockUSDT = new ethers.Contract(MOCK_USDT_ADDRESS, mockERC20ABI, wallet);
const amount = ethers.parseUnits('1000', 18);
const tx = await mockUSDT.faucet(amount);
await tx.wait();

console.log('Successfully obtained 1000 MOCK_USDT');

Method 2: Using Smart Contract Explorer

Visit BSC Testnet Explorer: https://testnet.bscscan.com/
Search for MOCK_USDT contract address: 0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91
Go to "Contract" tab and click "Write Contract"
Connect your MetaMask wallet (ensure you're on BSC Testnet)
Find the faucet function
Enter amount (Note: must include 18 decimals, e.g., 1000000000000000000000 for 1000 USDT)
Click "Write" button and confirm transaction

Important Notes

No quantity limit per faucet call, but obtain reasonable amounts based on testing needs
Ensure your wallet has sufficient testnet tokens to pay gas fees:
- BSC Testnet: Requires BNB testnet tokens, obtain from faucet: https://testnet.bnbchain.org/faucet-smart
- HashKey Testnet: Requires HSK testnet tokens
MOCK_USDC can be obtained the same way as MOCK_USDT, just replace the contract address
Different testnets have different token contract addresses, use the corresponding chain's contract address

Order Quantity Rules

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

Order Quantity Test Patterns

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

Quantity Patterns

1. PENDING to LOCKED (Quantity Starts with 1)

Pattern: Quantities starting with 1 (e.g., 1, 10, 100, 1000, 10000)

Expected Behavior:

Order is created and enters PENDING state
It then automatically transitions to LOCKED
No fills are executed
Order remains on the order book with LOCKED status

Use Case: Test order creation and order book listing, and verify PENDING → LOCKED transition for quantities starting with 1

Example Quantities:

1, 10, 100, 1000, 10000

2. LOCKED → Partially Filled (Quantity Starts with 2)

Pattern: Quantities starting with 2 (e.g., 2, 20, 200, 2000, 20000)

Expected Behavior:

Order is created and enters the LOCKED state
Upon cancellation, a portion of the order is filled (e.g., for an order of 200, 100 is filled and 100 is canceled)
The order status transitions to partially_filled and becomes a historical order
Fill records are generated for the executed quantity
The canceled quantity is released, and the order no longer appears on the order book

Use Case: Test partial execution via cancellation, remaining quantity tracking, and verify that the order history reflects the partially_filled status

Example Quantities:

2, 20, 200, 2000, 20000

3. PENDING Orders – Unfilled (Quantity Starts with 3)

Pattern: Quantities starting with 3 (e.g., 3, 30, 300, 3000, 30000)

Expected Behavior:

Order is created and enters the PENDING state
The order remains unfilled; no execution or fill occurs
The order is displayed on the order book with the PENDING status
The system does not automatically reject, lock, or fill the order

Use Case: Test order creation and verify that orders with quantities starting with 3 stay in PENDING status without being filled

Example Quantities:

3, 30, 300, 3000, 30000

4. PENDING → LOCKED → Partially Filled (Quantity Starts with 4)

Pattern: Quantities starting with 4 (e.g., 4, 40, 400, 4000, 40000)

Expected Behavior:

Order is created and initially enters the PENDING state
It then automatically transitions to the LOCKED state
Upon cancellation, a portion of the order is filled (e.g., for an order of 400, 300 is filled and 100 is canceled)
The order status transitions to partially_filled and becomes a historical order
Fill records are generated for the executed quantity
The canceled quantity is released, and the order no longer appears on the order book

Use Case: Test the full lifecycle from PENDING to LOCKED, cancellation with partial fills, remaining quantity tracking, and verify the historical order status is partially_filled

Example Quantities:

4, 40, 400, 4000, 40000

5. PENDING Orders – Unfilled (Quantity Starts with 5)

Pattern: Quantities starting with 5 (e.g., 5, 50, 500, 5000, 50000)

Expected Behavior:

Order is created and enters the PENDING state
The order remains unfilled; no execution or fill occurs
The order is displayed in the order records with the PENDING status
The system does not automatically reject, lock, or fill the order

Use Case: Test order creation and verify that orders with quantities starting with 5 stay in PENDING status without being filled

Example Quantities:

5, 50, 500, 5000, 50000

6. PENDING → LOCKED → Filled (Quantity Starts with 6)

Pattern: Quantities starting with 6 (e.g., 6, 60, 600, 6000, 60000)

Expected Behavior:

Order is created and enters the PENDING state
It then automatically transitions to the LOCKED state
The order is then fully filled through normal execution
The order status transitions to filled and becomes a historical order
Complete fill records are generated for the entire quantity
No remaining quantity stays on the order book

Use Case: Test the full order lifecycle from PENDING to LOCKED to fully filled, and verify complete execution and fill record generation

Example Quantities:

6, 60, 600, 6000, 60000

Testing Matrix

Quantity	First Digit	State Flow	Final Status	Filled Qty	Canceled Qty	Description
1	1	PENDING → LOCKED	`locked`	0	0	Auto transition to locked state
2	2	LOCKED → partially_filled	`partially_filled`	~half	~half	Partial fill after cancellation
3	3	PENDING (no change)	`pending`	0	0	Remains pending, unfilled
4	4	PENDING → LOCKED → partially_filled	`partially_filled`	~3/4	~1/4	Partial fill after cancellation
5	5	PENDING (no change)	`pending`	0	0	Remains pending, unfilled
6	6	PENDING → LOCKED → filled	`filled`	full	0	Complete Order Execution Lifecycle

Query Order Status

After creating orders, query their status using:

bash

curl -X GET "{API_BASE_URL}/api/v1/orders/{order_id}" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "X-Maker-Addr: YOUR_MAKER_ADDRESS" \
     -H "X-API-Timestamp: 1715100000000" \
     -H "X-API-Signature: GENERATED_SIGNATURE"

Or list all orders:

bash

curl -X GET "{API_BASE_URL}/api/v1/orders?status=pending" \
     -H "X-API-Key: YOUR_API_KEY"
     -H "X-Maker-Addr: YOUR_MAKER_ADDRESS" \
     -H "X-API-Timestamp: 1715100000000" \
     -H "X-API-Signature: GENERATED_SIGNATURE"

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:

bash

curl -X DELETE "{API_BASE_URL}/api/v1/orders/{order_id}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Maker-Addr: YOUR_MAKER_ADDRESS" \
  -H "X-API-Timestamp: 1715100000000" \
  -H "X-API-Signature: GENERATED_SIGNATURE"

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 first 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 starting in 2, 4, or 6 have fills in testing environment

Additional Resources

Authorization - API authentication
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.

Testing Guide ​

Overview ​

Purpose ​

Testing Environment ​

Supported Testnets ​

Obtaining Test Tokens ​

Test Token Contract Addresses ​

Method 1: Call faucet Function Using Web3 Libraries ​

Method 2: Using Smart Contract Explorer ​

Important Notes ​

Order Quantity Rules ​

Order Quantity Test Patterns ​

Quantity Patterns ​

1. PENDING to LOCKED (Quantity Starts with 1) ​

2. LOCKED → Partially Filled (Quantity Starts with 2) ​

3. PENDING Orders – Unfilled (Quantity Starts with 3) ​

4. PENDING → LOCKED → Partially Filled (Quantity Starts with 4) ​

5. PENDING Orders – Unfilled (Quantity Starts with 5) ​

6. PENDING → LOCKED → Filled (Quantity Starts with 6) ​

Testing Matrix ​

Query Order Status ​

Best Practices ​

1. Test All States ​

2. Verify State Transitions ​

3. Test Error Scenarios ​

4. Clean Up Test Data ​

Order Status Reference ​

Troubleshooting ​

Issue: Order not created ​

Issue: Unexpected order status ​

Issue: Cannot query order ​

Issue: Fill records missing ​

Additional Resources ​

Support ​

Testing Guide

Overview

Purpose

Testing Environment

Supported Testnets

Obtaining Test Tokens

Test Token Contract Addresses

Method 1: Call faucet Function Using Web3 Libraries

Method 2: Using Smart Contract Explorer

Important Notes

Order Quantity Rules

Order Quantity Test Patterns

Quantity Patterns

1. PENDING to LOCKED (Quantity Starts with 1)

2. LOCKED → Partially Filled (Quantity Starts with 2)

3. PENDING Orders – Unfilled (Quantity Starts with 3)

4. PENDING → LOCKED → Partially Filled (Quantity Starts with 4)

5. PENDING Orders – Unfilled (Quantity Starts with 5)

6. PENDING → LOCKED → Filled (Quantity Starts with 6)

Testing Matrix

Query Order Status

Best Practices

1. Test All States

2. Verify State Transitions

3. Test Error Scenarios

4. Clean Up Test Data

Order Status Reference

Troubleshooting

Issue: Order not created

Issue: Unexpected order status

Issue: Cannot query order

Issue: Fill records missing

Additional Resources

Support