Sparky Developer Docs
Welcome to the Sparky developer documentation. Sparky is a perpetual-contract DEX on EVM chains: order matching runs off-chain in a Rust engine, collateral sits in an on-chain Vault contract, and every fill is anchored on-chain through a TradeRecorder contract. This site covers the platform's core concepts and the full API reference.
Map
Core concepts
- EVM chains & accounts — supported networks, EIP-712 wallet login, Privy embedded wallets, one account per chain
- Deposits & withdrawals — Vault
deposit()/withdraw()flow, backend signatures, balance states
API reference
- Perpetual Contracts — Binance USDT-M compatible
/fapi/v1/*+/fapi/v2/*REST API, WebSocket streams, and Sparky-specific extensions - Referral — referral codes, tiered rebates, off-chain and on-chain claims
Supported chains
Sparky runs one backend deployment per chain. Each deployment has its own base URL, its own database, its own Vault, and therefore its own account balances, positions and API keys. A key created on Avalanche does not work on Arbitrum.
| Network | Chain ID | Native gas | Settlement asset | Status |
|---|---|---|---|---|
| Avalanche C-Chain | 43114 | AVAX | USDT (6 decimals) | Mainnet |
| Arbitrum One | 42161 | ETH | USDT (6 decimals) | Mainnet |
| BNB Chain | 56 | BNB | USDT | Mainnet |
| Avalanche Fuji | 43113 | AVAX (test) | test USDT | Testnet |
| Arbitrum Sepolia | 421614 | ETH (test) | test USDT | Testnet |
The API base URL for each deployment is listed in Basic Information › Base URLs.
On-chain contracts
Contract addresses are injected into each backend deployment through environment variables (VAULT_ADDRESS, TRADE_RECORDER_*, REFERRAL_*); they differ per chain and are not hard-coded anywhere in this documentation. Fetch the live addresses from the API instead of copying them from a page:
| Contract | Role | Where to get the address |
|---|---|---|
| Vault | Holds user collateral. Users call deposit(amount, referralCode); withdrawals require a backend EIP-712 signature (withdraw(user, amount, nonce, expiry, signature)). The backend indexes Deposit / Withdraw events to credit and release balances. | POST /api/v1/deposit/prepare → contract_address; POST /api/v1/withdraw/request → vault_address |
| TradeRecorder | Append-only on-chain record of every fill. The backend batches fills into an onchain_trade_records outbox and a recorder worker writes them to the contract, giving an auditable trade ledger. | Not exposed by an endpoint today; read from the deployment's TRADE_RECORDER_* configuration |
| ReferralStorage / ReferralRebate | On-chain referral registry (codes, relationships, tier) and rebate ledger. The backend syncs accrued rebates hourly (batchSyncRebates); users claim with a backend signature via claimRebate(amount, deadline, signature). | GET /api/v1/referral/on-chain/operator-status → contract_address |
Dual-engine architecture
Sparky's backend serves two trading engines behind a single API host:
| Engine A — Orderly gateway | Engine B — Sparky native engine | |
|---|---|---|
| Markets | Deep mainstream pairs listed on Orderly Network | Long-tail, RWA and custom pairs not listed on Orderly |
| Matching | Orderly's off-chain engine | Sparky's lock-free in-memory order book |
| Settlement | Orderly Vault | Sparky Vault on the deployment's chain |
| Client path | ANY /api/v1/dex/* transparent proxy (client-signed Orderly auth headers are renamed and forwarded byte-for-byte; strict path allow-list; fund-moving routes are never proxied) | /api/v1/* native JSON API and the Binance-compatible /fapi/* API |
| On-chain record | POST /api/v1/orderly/record-fill → TradeRecorder | onchain_trade_records outbox → TradeRecorder |
Both engines share the same wallet identity (the user's EOA address). Which engine serves a market is decided by the market metadata's engine field — clients must not guess from the symbol format. This documentation covers Engine B only: everything under /fapi/* and /api/v1/* (excluding /api/v1/dex/*) hits Sparky's native engine.
Status
🚧 Work in progress. Base URLs are placeholders until DNS is assigned; endpoint pages are reconciled against the backend route table and mark anything Binance defines but Sparky does not serve as Not yet implemented.