feat(v2.2.0): support demo trading

[JJ-Cro]

PR Summary: BitMart API Updates - New Endpoints & Demo Trading Support

Overview

This PR implements updates from BitMart's API changelog (2025-11-18 to 2025-12-11), adding new endpoints, updating existing ones, and introducing demo/simulated trading environment support.

Changes

1. Updated /contract/private/trades Endpoint (2025-12-02)

Files Modified:

• src/types/request/futures.types.ts

Changes:

• Added optional order_id and client_order_id fields to FuturesAccountTradesRequest
• Made symbol field optional to support querying by order ID or client order ID
• Enables querying order trades by order ID or client order ID in addition to symbol

2. New Affiliate Rebate Endpoints (2025-12-11)

Files Modified:

• src/types/request/futures.types.ts
• src/types/response/futures.types.ts
• src/FuturesClientV2.ts

New Endpoints:

• getFuturesAffiliateRebateUser() - /contract/private/affiliate/rebate-user
  • Query contract rebate data for users (up to 60 days)
• getFuturesAffiliateRebateApi() - /contract/private/affiliate/rebate-api
  • Query contract API rebate data (up to 60 days)

New Types:

• FuturesAffiliateRebateUserRequest - Request type for user rebate data
• FuturesAffiliateRebateApiRequest - Request type for API rebate data
• FuturesAffiliateRebateUserResponse - Response type for user rebate data
• FuturesAffiliateRebateApiResponse - Response type for API rebate data

3. Simulated Trading / Demo Environment Support (2025-11-18)

Files Modified:

• src/types/request/futures.types.ts
• src/types/response/futures.types.ts
• src/lib/requestUtils.ts
• src/lib/websocket/websocket-util.ts
• src/types/websockets/client.ts
• src/FuturesClientV2.ts
• src/WebsocketClient.ts
• README.md

REST API Changes:

• Added useDemo option to RestClientOptions interface
• Updated getRestBaseUrl() to support demo environment
• Demo REST endpoint: https://demo-api-cloud-v2.bitmart.com
• Added submitFuturesSimulatedClaim() method for simulated account claim
• New types: SubmitFuturesSimulatedClaimRequest, FuturesSimulatedClaimResponse

WebSocket Changes:

• Added useDemo option to WSClientConfigurableOptions interface
• Updated WS_BASE_URL_MAP to include demo URLs for V2 Futures
• Updated getWsUrl() method to support demo environment
• Demo WebSocket endpoints:
  • Public: wss://openapi-wsdemo-v2.bitmart.com/api?protocol=1.1
  • Private: wss://openapi-wsdemo-v2.bitmart.com/user?protocol=1.1

Documentation:

• Added demo trading section to README.md
• Included examples for both REST and WebSocket clients
• Clarified that demo environment is only available for V2 Futures

Usage Examples

New Affiliate Rebate Endpoints

// Get user rebate data
const userRebate = await futuresClient.getFuturesAffiliateRebateUser({
  cid: 1000000,
  start_time: 1000000000,
  end_time: 2000000000,
});

// Get API rebate data
const apiRebate = await futuresClient.getFuturesAffiliateRebateApi({
  cid: 1000000,
  start_time: 1000000000,
  end_time: 2000000000,
});

Updated Trades Endpoint

// Query by order ID
const trades = await futuresClient.getFuturesAccountTrades({
  order_id: 123456789,
});

// Query by client order ID
const trades = await futuresClient.getFuturesAccountTrades({
  client_order_id: 'my-order-id',
});

Demo Trading Environment

// REST API
const demoClient = new FuturesClientV2({
  apiKey: API_KEY,
  apiSecret: API_SECRET,
  apiMemo: API_MEMO,
  useDemo: true,
});

// WebSocket
const demoWsClient = new WebsocketClient({
  apiKey: API_KEY,
  apiSecret: API_SECRET,
  apiMemo: API_MEMO,
  useDemo: true, // V2 Futures only
});

// Simulated claim
await demoClient.submitFuturesSimulatedClaim({
  currency: 'USDT',
  amount: '10',
});

Breaking Changes

None - all changes are backward compatible.

Notes

• Demo environment is only available for V2 Futures (not Spot or V1 Futures)
• The same API keys work for both production and demo environments
• Manual baseUrl/wsUrl override still takes precedence over useDemo flag
• All new endpoints follow existing code patterns and conventions

Testing

• All TypeScript types are properly defined
• Linter checks pass
• Code follows existing patterns and conventions
• Documentation updated with examples

[tiagosiebler]

Can you use the same property name as we have for other exchanges please? E.g.
https://github.com/tiagosiebler/bybit-api/blob/master/examples/demo-trading.ts#L26C3-L26C14

Suggested change

	useDemo: true, // Uses https://demo-api-cloud-v2.bitmart.com
	demoTrading: true, // Uses https://demo-api-cloud-v2.bitmart.com

[tiagosiebler]

Suggested change

	useDemo: true, // Uses wss://openapi-wsdemo-v2.bitmart.com
	demoTrading: true, // Uses wss://openapi-wsdemo-v2.bitmart.com

[tiagosiebler]

Suggested change

	useDemo?: boolean;
	demoTrading?: boolean;

[tiagosiebler]

Suggested change

	useDemo?: boolean;
	demoTrading?: boolean;

[tiagosiebler]

LGTM