Skip to main content
L RMN

DreamDex on Somnia: A Practical Guide for Users, Builders, and Agents

Posted on:  at 
Web3
Web3DreamDexSomniaMarketDataAgenticApps
Picture

Why I Started Looking at DreamDex

A few days after DreamDex launched, I opened the documentation with a fairly ordinary question: what does a fully onchain order book actually look like when you try to build around it?

That question led to several browser tabs, a lot of API responses, and eventually a small project of my own. I spend time around the Somnia community, I enjoy following what people are building there, and I am optimistic about the network. That is the extent of my connection. I am not part of the DreamDex team, DreamDEX S.A., or the Somnia team. This article is an independent community perspective, not an endorsement or an inside account.

I also do not want to repeat a product page in different words. DreamDex is interesting because it sits at the intersection of three things that are usually discussed separately: an onchain Central Limit Order Book, public market infrastructure, and software interfaces designed for both people and automated systems. Those pieces are useful to a trader, but they are equally useful to someone building a dashboard, a monitoring service, an agent, or a research tool.

The official documentation is a living document, so anything operational should be checked against the current DreamDex docs before being used in production. The descriptions below reflect the documentation available in early July 2026.

What DreamDex Actually Is

DreamDex is a spot exchange built on Somnia. Its core is a fully onchain Central Limit Order Book, usually shortened to CLOB. According to the DreamDex introduction, the order book exists at the smart-contract level and matching clears at the validator level. There is no separate private matching engine sitting between the user and the chain.

That structure is different from an Automated Market Maker. An AMM normally prices trades against a formula and token reserves inside a liquidity pool. A CLOB organizes explicit bids and asks. Buyers state the maximum price they will pay, sellers state the minimum price they will accept, and the matching engine pairs compatible orders.

For a regular user, this produces a familiar exchange view: best bid, best ask, spread, order-book depth, recent trades, and limit orders. For a builder, it exposes a more detailed state surface. You can measure how much liquidity sits within one percent of the midpoint, estimate slippage across price levels, watch aggressive buy and sell flow, or track how the spread changes over time.

The matching policy documented by DreamDex is price-time priority. Better prices are matched first. When two orders have the same price, the earlier order gets priority. Matching and settlement happen onchain. DreamDex also documents self-trade prevention, where an incoming order that would trade against the same user's resting order causes either the taker or maker side to be cancelled, depending on the selected option.

Every currently documented spot market uses USDso as its quote asset. That means a symbol such as SOMI:USDso describes SOMI as the base asset and USDso as the unit used to express its price. Builders should still discover symbols at runtime through the market API instead of treating a list copied from documentation as permanent.

Zero Trading Fees, but Not Zero Cost

The headline feature is straightforward: the DreamDex fee documentation lists maker fees at 0 percent and taker fees at 0 percent. That does not mean every interaction is free. Orders settle on Somnia, so network gas can still apply. The documentation also describes gas sponsorship for core SOMI and stablecoin pairs, but an integration should not assume that every market or every action is sponsored.

There is an important caveat here. The official fees page is marked as work in progress and contains unfinished gas-cost estimates. It is reasonable to state that the documented trading fee is zero. It is not reasonable to invent a precise dollar cost for placing or cancelling an order while the source itself has not published one.

The economic model is built around yield on resting collateral rather than a protocol charge on every fill. Makers place liquidity on the book. The documented collateral yield algorithm scores that liquidity using three main inputs:

  1. The notional size of the resting order.
  2. The amount of time it remains on the book.
  3. Its proximity to the current midpoint.

Orders closer to the midpoint receive more weight because they contribute more directly to a tight, usable market. The documentation describes a Gaussian proximity curve, with the highest weight at the midpoint and a declining weight deeper in the book. A maker's share of the available yield is proportional to the score accumulated by their resting orders.

This model does not turn market making into free money. A resting order can be filled when the market moves, liquidity can disappear, and the value of the assets can change. Yield is an incentive for supplying useful liquidity, not protection from inventory or price risk.

How Trading Works

The order-type documentation covers the building blocks most exchange users will recognize.

A limit order sets a specific price and can rest until it fills or is cancelled. A market-style order prioritizes immediate execution. DreamDex implements this behavior as an Immediate-or-Cancel order with a crossing limit price. A buy must reach the best ask, and a sell must reach the best bid. Any amount that cannot fill immediately is cancelled.

The time-in-force options give a strategy more precise control:

  • Good-Till-Cancelled remains open until it fills or is cancelled.
  • Immediate-or-Cancel fills whatever is available immediately and cancels the remainder.
  • Fill-or-Kill requires the entire quantity to fill immediately or nothing happens.
  • Post-Only must rest as maker liquidity and is rejected if it would execute immediately.

DreamDex also documents stop-loss and take-profit orders. These use a mark price based on an EMA-smoothed midpoint. They are conditional instructions, not guarantees of a particular fill price. Once triggered, the resulting order still meets the available book.

That distinction matters whenever someone says "market order." If the visible best ask is 1.00, a large buy may consume asks at 1.00, 1.01, 1.03, and beyond. The average fill can be worse than the first price shown. A client should simulate book consumption and enforce a worst acceptable price rather than treating the top of book as a quote for unlimited size.

The Builder Surface

DreamDex exposes several routes into the same market infrastructure: public HTTP data, WebSocket subscriptions, authenticated order preparation, direct contract calls, a CLI, and an alpha CCXT integration.

For a read-only application, the public HTTP surface is enough to get started:

  • GET /v0/markets discovers active markets and their contract metadata.
  • GET /v0/currencies discovers supported assets and decimals.
  • GET /v0/orderbooks returns aggregated bids and asks.
  • GET /v0/tickers returns 24-hour OHLCV statistics.
  • GET /v0/markets/{symbol}/volume returns volume for a bounded time window.
  • GET /v0/markets/{symbol}/trades returns recent public executions.
  • GET /v0/markets/{symbol}/tickers returns one market ticker.
  • GET /v0/markets/{symbol}/candles returns OHLCV candles.

The first request should usually be market discovery. This example reads public data only and performs no wallet operation.

type DreamDexMarket = {
  symbol: string
  contract: string
  base: string
  quote: string
  baseDecimals: number
  quoteDecimals: number
  tickSize: string
  lotSize: string
  minQuantity: string
}

function isMarketList(value: unknown): value is { markets: DreamDexMarket[] } {
  if (!value || typeof value !== "object" || !("markets" in value)) return false
  return Array.isArray(value.markets) && value.markets.every((market) =>
    market &&
    typeof market === "object" &&
    "symbol" in market &&
    typeof market.symbol === "string" &&
    "tickSize" in market &&
    typeof market.tickSize === "string"
  )
}

const response = await fetch("https://api.dreamdex.io/v0/markets")
if (!response.ok) throw new Error(**DreamDex HTTP ${response.status}**)

const payload: unknown = await response.json()
if (!isMarketList(payload)) throw new Error("Unexpected DreamDex market payload")

for (const market of payload.markets) {
  console.log(market.symbol, market.tickSize, market.lotSize)
}

The complete application should validate every field, not only the fields inspected by this compact example. A schema library such as Zod is useful at this boundary.

Prices, quantities, costs, tick sizes, and lot sizes are returned as decimal strings. Keep those strings intact. JavaScript number is convenient for chart pixels and rough sorting, but it is not an authoritative financial representation. Final calculations should use decimal arithmetic, and raw onchain units should use integers or bigint.

Building with Real-Time DreamDex Data

Polling can populate a dashboard, but it is a poor fit for a live order book. The public DreamDex WebSocket endpoint is wss://api.dreamdex.io/v0/ws/public. The documented channels include orderbook, ohlcv, and trades, with an order channel available for order updates.

The protocol sequence is important. A successful subscription produces a confirmation, then an initial snapshot, then incremental updates. A client that applies updates before receiving a snapshot can build a book from incomplete state.

This browser example connects to the public order-book channel, keeps the connection active, and reconnects with a bounded delay. It logs messages rather than mutating a book so the state model remains explicit in the application that consumes it.

const wsUrl = "wss://api.dreamdex.io/v0/ws/public"

function connectToOrderBook(retryMs = 1_000): void {
  const socket = new WebSocket(wsUrl)
  let heartbeat: number | undefined

  socket.addEventListener("open", () => {
    socket.send(JSON.stringify({
      operation: "subscribe",
      channel: "orderbook",
      params: { symbols: ["SOMI:USDso"] },
    }))

    heartbeat = window.setInterval(() => {
      socket.send(JSON.stringify({ operation: "ping" }))
    }, 25_000)
  })

  socket.addEventListener("message", ({ data }) => {
    try {
      const message: unknown = JSON.parse(String(data))
      console.log("DreamDex WebSocket message", message)
    } catch {
      console.warn("Rejected malformed DreamDex WebSocket message")
    }
  })

  socket.addEventListener("close", () => {
    if (heartbeat !== undefined) window.clearInterval(heartbeat)
    window.setTimeout(
      () => connectToOrderBook(Math.min(retryMs * 2, 30_000)),
      retryMs,
    )
  })
}

connectToOrderBook()

DreamDex documents a ping at least every 30 seconds and a 60-second inactivity timeout. Production code also needs schema validation, subscription confirmation tracking, snapshot resets, update sequencing, duplicate handling, and resubscription after reconnect. If the server closes a slow consumer with code 4001, reconnecting to a fresh snapshot is safer than assuming the missed updates can be reconstructed.

A Working Example: DreamDex Market Data

I built DreamDex Market Data to test what could be made from these public interfaces without asking users to connect a wallet. It is an independent, read-only project, not an official DreamDex product.

The browser displays live order books, recent executions, candles, trade flow, spread, depth, and a local slippage simulation. A Cloudflare Worker serves the React application and its GET-only API. Scheduled jobs collect public snapshots into Cloudflare D1, which makes historical reports and gap reporting possible even when nobody has the page open. Read-only Somnia RPC calls compare selected pool parameters with API metadata.

The Whale Radar is deliberately described as an analytical label. DreamDex does not publish an official definition of a whale. The project marks a fixed large trade at a configured USDso threshold and a relative whale against the historical P99 for that market. Those labels describe unusual public executions, not wallets or identities.

This is one possible composition of the data, not a required architecture. A mobile alert service, tax export tool, liquidity monitor, spread scanner, research notebook, or public market API could use the same underlying endpoints in a different way.

The application is live at dmd.lrmn.wtf, and the complete source is available in the DreamDex Market Data repository.

Making the Documentation Available to AI Agents

An AI coding agent can write an API call quickly. The harder question is whether it used the real path, the current field names, and the right security assumptions. Model memory is a weak source for details that can change.

The community-maintained DreamDex Docs Agent Skill packages a checked snapshot of the official documentation with routing instructions and local citations. It supports several coding agents and tells them to report missing information instead of filling gaps with guesses. It is documentation-only. Installing it does not create a wallet, expose a private key, or authorize a trade.

For OpenAI Codex, add the marketplace:

codex plugin marketplace add lrmn7/dreamdex-docs-agent-skill
codex

Then open /plugins, select DreamDex Docs, install dreamdex-docs, and start a new thread. The skill can be invoked as $dreamdex-docs.

For Gemini CLI:

gemini skills install https://github.com/lrmn7/dreamdex-docs-agent-skill.git --path skills

Use /skills list to verify the installation. In both cases, the checked snapshot is a grounding aid, not a replacement for verifying the current official DreamDex documentation before production deployment.

Can an Agent Trade Automatically?

Technically, yes. DreamDex documents enough infrastructure to build an automated trading system. The dangerous version is an LLM with unrestricted access to a funded key. The useful version separates observation, decision making, policy enforcement, and signing.

A safer architecture looks like this:

market feed -> strategy -> risk engine -> transaction preparation
-> eth_call simulation -> isolated signer -> broadcast
-> receipt verification -> order monitoring

The market feed can use public REST and WebSocket data. A strategy can produce a proposed action, but it should not be the final authority. A deterministic risk engine should check the symbol, maximum notional, position limits, available balance, price bounds, slippage, data freshness, and daily loss limits. A kill switch should be able to stop new orders without waiting for the model to agree.

For authenticated HTTP operations, DreamDex uses Sign-In with Ethereum. The documented flow requests a single-use nonce, signs an ERC-4361 message in the wallet boundary, and exchanges the message and signature for a bearer token. That token can request transaction preparation. It is not a private key and it does not sign an onchain transaction.

The order-preparation endpoint returns an unsigned EVM transaction containing fields such as to, data, value, and chainId. The client remains responsible for simulation, signing, broadcasting, and checking the result. DreamDex recommends simulating the call first and verifying an OrderPlaced event after confirmation. A transaction receipt with a successful status but no expected event should not be treated as a placed order.

The signer should be isolated from the general agent runtime. It can expose a narrow policy-controlled interface rather than raw key material. The allowlist should contain known chain IDs and contract addresses. Logs should record the proposed action, policy decision, simulation result, transaction hash, receipt, and resulting order state without recording secrets.

Automated systems also need boring operational controls: nonce coordination, retry limits, idempotency, stale-feed rejection, reconnect and resubscribe logic, rate-limit handling, and alerts when observed positions do not match expected positions. These controls are less exciting than a strategy prompt, but they are what stop a transient network problem from becoming repeated orders.

DreamDex also documents a CCXT integration for familiar bot interfaces. As of the documentation snapshot used here, it is alpha software installed from a GitHub branch rather than npm. Its createOrder method returns an unsigned EVM transaction, not a confirmed order. That boundary should remain visible in any agent design.

Testnet is the right place to validate the plumbing. DreamDex documents Somnia Shannon with chain ID 50312 and staging API and WebSocket endpoints. A successful testnet run still does not prove a strategy is profitable or production-safe, but it can catch schema, signing, decimal, nonce, and lifecycle mistakes before real funds are involved.

Risks and Current Limitations

An onchain exchange removes some trusted intermediaries, but it does not remove risk. The DreamDex risk documentation names smart-contract vulnerabilities, blockchain downtime or congestion, upgradeable contracts, liquidity risk, price risk, protocol upgrades, and parameter changes.

Liquidity is especially relevant to automation. An order book can look healthy at the top while offering little depth behind it. A fast strategy can still receive a poor average price if its size walks through several levels. A delayed cancellation can still fill. A parameter such as tick size, lot size, or minimum quantity can change and invalidate a previously accepted assumption.

The official audit page states that the DreamDex spot protocol completed a Hacken audit in April 2026, covering core contracts and supporting libraries. That is a dated status, not a permanent guarantee. The same page described the USDso swap-contract audit with Sherlock as a separate ongoing engagement at the time of the snapshot. Readers should check the current audit page rather than treating this paragraph as a live status feed.

An audit can identify classes of problems and document remediation. It cannot prove that no undiscovered bug exists, that an upgrade will behave as expected, or that a market will always have enough liquidity. Use only funds you can afford to lose, and give automated systems less authority than they appear to need.

Explore DreamDex and Build Around It

For a regular user, the simplest next step is to open DreamDex and look at the live book. For a builder, start with market discovery and a read-only prototype before adding any wallet boundary. For an agent builder, ground the agent in current documentation and keep execution behind deterministic policy.

Official resources

Unofficial resources

The following projects are personal, unofficial community work. They are not affiliated with, endorsed by, maintained by, or supported by DreamDEX S.A. or the Somnia team.

DreamDex provides the market infrastructure. What builders do with the public data can be as simple as a price panel or as involved as a monitored execution system. The sensible place to begin is the same place I began: read the docs, make one public request, and keep the first version read-only.

Share