Spot Wallet & Trading Overview

ZTDX Spot is a multi-token wallet plus an order-book (CLOB) trading venue running alongside (but isolated from) the perpetual exchange. The MVP supports the DF governance token on BSC, an internal USDT bridge between perp margin and the spot wallet, and one trading pair (DFUSDT).

Sub-systems

Sub-system	Gate	Purpose
Spot wallet	`SPOT_ENABLED=true`	Per-(user, token) balance ledger, deposits / withdrawals to BSC, internal USDT transfer between perp margin and spot.
Spot trading	`SPOT_TRADING_ENABLED=true` (in addition to `SPOT_ENABLED`)	In-memory CLOB engine + REST + WebSocket for `/spot/orders`, `/spot/trades`, `/spot/depth`, `/spot/klines`, `/spot/ticker/24hr`.

When trading is disabled, the routes still mount; place / cancel return 503 spot trading disabled and the public market-data routes reflect an empty state.

Where to start

If you want to…	Read
Understand auth, base URL, JSON conventions	General Info
Know what enum values are valid in requests / responses	Enums
Look up a string error code	Error Codes
Place an order	Trading REST → New Order
Stream live depth + trades	WebSocket → General
Understand deposits / withdrawals on BSC	Deposit Flow / Withdraw Flow

Service Endpoints

Environment	REST base	WebSocket
Testnet	`https://api-sepolia.p99.world/api/v1`	`wss://api-sepolia.p99.world/ws`
Mainnet	(not deployed yet)	(not deployed yet)

On-Chain Components

Item	Network	Address / Value
BSC chain id	BSC Testnet	`97`
Vault contract (`ZtdxSpotVault`)	BSC Testnet	`0x4Fe0b354c5865ee9deb979a99030d757ae47664a`
DF token (ERC-20)	BSC Testnet	`0x8063a43ed88397c1B10DA23dcC60ba1E7A0Bf555`
DF decimals	—	`18`
Perp collateral (USDT)	Arbitrum Sepolia (`421614`)	`0xfA70c5A9221d239Cd51DBf48967ABc79d7B9D61d`
USDT decimals	—	`6`

Trading subsystem at a glance

The engine is a single Tokio task owning an in-memory order book per market (MVP: only DFUSDT). Each fill commits to PostgreSQL in its own transaction. On restart, GTC limit orders are rebuilt from spot_orders; in-flight IOC and market orders are canceled with their lock refunded.

Tick size / lot size / min notional are per-market (see GET /spot/markets).
Self-trade prevention is DECLINE_TAKER: if your incoming order would cross your own resting order, the new order is rejected with SELF_TRADE.
Fees are configured per-market (maker_fee_bps / taker_fee_bps); both are 0 on testnet today.

Notes

The BSC listener catches up at ~30 blocks/sec from a cold start. After catch-up, deposits are credited within ~40 seconds (20 confirmations × ~2 s/block on BSC).
The WebSocket feed covers depth diff / trades / klines / ticker / per-user order + balance updates. REST polling still works as a fallback.

Sub-systems​

Where to start​

Service Endpoints​

On-Chain Components​

Trading subsystem at a glance​

Notes​