API

The Omnisea API exposes indexed protocol data for the app and for external integrations. It is useful for discovery, dashboards, asset pages, transfer history, leaderboard rankings, order tables, wallet activity, and wallet points.

On-chain state remains authoritative. API responses can lag behind the latest block, may be affected by reorgs, and may evolve during beta.

Base URL

Use the API origin configured for the current environment. Production integrations should use the public Omnisea API origin exposed by the app environment.

Pagination

List endpoints use cursor pagination.

Common query parameters:

Common response shape:

{
  "items": [],
  "page": {
    "nextCursor": "cursor-value",
    "hasMore": true
  }
}

Status

GET /status

Returns API health and basic service status.

Chains

GET /chains

Returns supported chains, chain IDs, LayerZero endpoint IDs, RPC-facing metadata, and explorer links used by the Omnisea app.

Contracts

GET /contracts

Optional filters:

Contract detail

GET /contracts/:chainId/:address

Returns one indexed contract record by chain and address when it is known to Omnisea.

Asset resolution

GET /assets/resolve?chainId=8453&token=0x...

Resolves a token address on a given chain into Omnisea asset context when available.

Resolution may identify:

• the original chain and original token
• the representation address for the current chain
• deterministic route metadata
• asset page context

Assets

GET /assets

Returns indexed Omnisea asset routes.

Common filters:

Asset page data

GET /assets/:chainId/:address

Returns indexed asset data for a token route, including transfer history and representation context when available.

Common query parameters:

Transfers

GET /transfers

Common filters:

Transfer status is derived from indexed core actions, Router transport state, LayerZero message state, destination execution, retry, and restore events. Core and Router contracts are indexed separately on every active EVM chain. lzCompose application execution remains independent from the bridge-credit status.

Transfer leaderboard

GET /leaderboards/transfers

Returns the seasonal wallet ranking by unique, successfully completed transfer GUIDs.

Common query parameters:

Each completed GUID counts once for its source-sender wallet. Pending, failed, and restored transfers are excluded.

Orders

GET /orders

Returns indexed Omnibook orders.

Common filters:

Expired status is materialized by the API from the order expiry timestamp. The Omnibook contract remains authoritative for fills and cancellations.

Order rows are keyed by settlement chain, contract address, and order ID. They include quote-token metadata, cumulative fill and taker-fee amounts, lastFillTxHash, and the cancellation transaction when indexed.

Omnibook orderbook snapshot

GET /orders/book

Returns up to 500 active orders for one exact indexed Omnibook market. For an independently deployed book, use this endpoint as its indexed initial state and verify the contract address separately.

Required parameters:

limit is optional and cannot exceed 500. The response contains items and an asOf timestamp. It excludes cancelled, filled, expired, and zero-remaining orders.

Realtime Omnibook updates

wss://<api-origin>/ws/omnibook

The WebSocket feed tells a client when an indexed book has changed. Connect and subscribe first, then load /orders/book as the initial snapshot:

{
  "type": "subscribe",
  "chainId": "8453",
  "contractAddress": "0x..."
}

After the subscription is accepted, the API sends an orderbook.changed message whenever an OrderCreated, OrderAssetResolved, OrderFilled, OrderCancelled, or TradeExecuted event is committed for that book. Removed logs caused by a reorg also produce an update with removed: true.

{
  "type": "orderbook.changed",
  "sequence": 42,
  "chainId": "8453",
  "contractAddress": "0x...",
  "eventNames": ["OrderFilled"],
  "transactionHashes": ["0x..."],
  "blockNumber": "12345678",
  "removed": false,
  "publishedAt": "2026-07-30T12:00:00.000Z"
}

Treat this message as an invalidation signal and reload the affected snapshot. Also reload after the server confirms a subscription, including after reconnecting. REST remains canonical, which keeps clients correct across partial fills, batched fills, matching, duplicate webhook deliveries, and chain reorganizations.

The server sends application-level ping messages. Reply with {"type":"pong"} to keep the connection active. Reconnect with backoff after a disconnect.

Omnibook market quote

GET /orders/market-quote

Builds a best-price fill plan for one atomic market order.

Required parameters:

maxOrders is optional, defaults to 32, and cannot exceed the contract maximum of 64.

The response includes fills, filledAmount, quoteAmount, and complete. Each fill contains the exact orderId, raw fillAmount, and raw quoteAmount selected by the planner. Prices are ordered exactly with integer arithmetic; equal-price orders use the oldest order ID first. Oversized all-or-none orders are skipped.

This endpoint does not reserve liquidity. Refresh the plan immediately before submission, read the live taker fee from the contract, and pass a suitable quoteBound to batchFillOrders. If the indexed plan is stale, the on-chain batch reverts atomically.

Omnibook trades

GET /orders/trades

Returns cursor-paginated TradeExecuted records for one exact market. Required parameters are chainId, contractAddress, originalChainId, and originalToken. Each row includes raw fill and quote units, fee, participants, transaction metadata, token decimals, and quote-token metadata.

One crossed-order match produces one trade record.

Omnibook candles

GET /orders/candles

Returns OHLCV buckets derived from indexed trades. It requires the same exact-market parameters as /orders/trades.

Prices are adjusted for Omniasset and quote-token decimals. Volume and quote volume remain raw integer token units.

Crossed Omnibook orders

GET /orders/crossed

Returns candidate buy/sell pairs for a permissionless matcher. Required parameters are chainId and contractAddress; limit is optional.

The endpoint excludes self-matches, expired orders, non-crossing prices, and incompatible all-or-none sizes. It does not reserve either order. A matcher must call previewMatch and simulate batchMatchOrders before submitting.

Wallet points

GET /wallets/:address/points

Returns the indexed Points balance for a wallet address.

Points are program accounting, not on-chain balances. See Points & rewards.

Wallet transactions

GET /wallets/:address/transactions

Returns indexed transfer activity associated with a wallet address.

Common query parameters:

Operational notes

The API is intended for reasonable public use. We may rate-limit, restrict, change, or discontinue endpoints during beta. Integrations that need strong settlement guarantees should verify final state on-chain.