Developers

This section covers everything you need to integrate with dreamDEX programmatically. New here? Start with the Quick Start guide for a hands-on walkthrough of placing your first order.

• Contracts — Solidity reference for the on-chain order book: functions for placing and managing orders, events emitted during matching, and the types used across both.
• HTTP API — REST endpoints for market data, authentication, trading, and vault operations. The API returns unsigned transactions that you sign and broadcast yourself.
• WebSocket API — Real-time streaming interface for order book updates, trade feeds, and order status changes.
• Libraries — Client libraries wrapping the dreamDEX APIs, including the CCXT integration for TypeScript/JavaScript.

Choosing between REST and WebSocket

Use the HTTP API for request/response work: discovering markets, preparing orders, and one-off balance or order queries. Use the WebSocket API for anything continuous: streaming order book and trade updates, and tracking an order's lifecycle without polling.

As a rule of thumb, poll REST for occasional snapshots and subscribe over WebSocket once you need live updates or sub-second latency — a streaming subscription avoids the rate-limit and staleness pitfalls of tight polling loops. The CCXT binding wraps the REST endpoints (and WebSocket where supported) behind a standard interface, so existing CCXT bots work with minimal changes.

The public feed carries market-wide data only - it does not attribute fills to your account. For your own fills, use the per-order order channel or reconcile balances over REST.

Reliability: polling, retries, and backup RPCs

A bot that runs 24/7 should assume individual requests will occasionally fail (a node hiccup, a transient ConnectionError under sustained load, a shutdown-and-cycle). Design for it:

Polling cadence. Prefer a WebSocket subscription over a tight REST loop for anything continuous - one subscription replaces thousands of polls and avoids rate limits. When you must poll REST, poll no faster than you actually consume: roughly 1 request/second per endpoint for market data is plenty; back off further for data that changes slowly. Do not poll a per-order status in a hot loop - subscribe to the order channel instead.

Retries and backoff. Treat timeouts, 5xx, rpc_unavailable, and connection errors as retryable; treat 4xx validation errors as terminal (fix the request, do not retry). Use exponential backoff with jitter - e.g. base 500 ms, doubling, capped at ~30 s - and cap the number of in-flight requests so a backlog cannot stampede a recovering node. For submitted transactions, retry idempotently: re-query the receipt before re-broadcasting, since the first attempt may have landed.

Backup RPCs. The order-preparation HTTP API is centralized, but broadcasting and on-chain reads go through a Somnia RPC endpoint you choose - keep more than one configured and fail over on error:

The current, authoritative provider list (including WSS endpoints) is at Somnia network-info. Rotate to a backup on repeated failures rather than hammering one endpoint.