Read API reference

Use the API for discovery and indexed history. Use on-chain reads for current balances, permissions, fees and the transaction you are about to sign.

Download the OpenAPI 3.1 reference for the public asset-router read routes. It excludes legacy and operator APIs. Its release is a source-tree preview, not a claim that the hosted service has rolled out these routes.

Base URL and authentication

The hosted base URL is https://api.omnisea.io; local development defaults to http://localhost:8788. These public GET routes require no API key. Browser CORS origins are configured by the API operator; a successful command-line request does not guarantee an arbitrary browser origin is allowed. Use your server if needed. Webhook ingestion and internal administration are separate, authenticated operator interfaces—not public integration endpoints.

curl -f https://api.omnisea.io/version
curl -f https://api.omnisea.io/chains
curl -f 'https://api.omnisea.io/assets?limit=25&q=USDC'

Endpoints

Message list filters: assetId, wallet, chainId, status, kind, txHash, fromDate, toDate, limit, cursor. chainId matches either side. Dates use YYYY-MM-DD; filters apply to indexed creation time, with the end date inclusive. status accepts pending, delivered, failed, restored. kind accepts transfer, restore, sync, owner. A sync filter on /transfers will return no rows by design.

Pagination

/assets, /messages, /transfers and wallet activity return the same page envelope:

{ "items": [], "page": { "nextCursor": null, "hasMore": false } }

limit defaults to 25 and accepts 1–100. Send nextCursor unchanged and URL-encoded as cursor on the next request; keep all other filters fixed. Stop when hasMore is false. Restart pagination when filters change. Lists sort newest first by indexed time and an ID tie-breaker, not source block time.

New or corrected rows can arrive while you page. Deduplicate assets by assetId and messages by guid, then refresh page one. Treat the index as eventually consistent, not a snapshot or finality guarantee.

Data types and identity

Asset summaries include assetId, originEid, originChainId, originToken, originTokenAddress, creator, creatorAddress, name, symbol, decimals, sharedDecimals, complianceMode, preEnabledEids, descriptor, creation metadata and counts. The canonical identities are bytes32; the ...Address fields are EVM projections and may be null. Do not choose the first asset of an original token as its official issuer.

Asset detail adds tokens (actual registered facades), enabledEids (origin approval) and chainViews (what each router has learned). They are different sets. A destination can be enabled but not deployed; a remote router can need a sync.

Message fields include guid, kind, status, assetId, source/destination chain IDs and EIDs, sender/recipient, amountSentLD, amountReceivedLD, amountDeliveredLD, flatFee, feeLD, transaction hashes, timestamps, restoreGuid, restoreOfGuid, failureReason, failureError and layerZeroScanStatus. Missing observations can be null. Amounts and large identifiers are decimal strings; parse monetary values as BigInt. Token amounts use local token decimals; flat fees use source native base units. Never assume all fees are ETH or all tokens use 18 decimals.

Status semantics

OwnerActionRejected and StaleConfigIgnored can occur in a delivered message. The API does not expose a dedicated applied/rejected status, so inspect receipt events and current state. layerZeroScanStatus is supplemental; do not overwrite a router failure with transport-level delivery.

Errors and polling

Errors use { "error": "message", "details": ... }; details can be absent. Invalid filters or cursors return 422. A valid but not-yet-indexed identity or GUID returns 404. Rate limiting returns 429 and Retry-After; use it with bounded jittered backoff. Inspect RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (Unix seconds) and RateLimit-Policy instead of hardcoding a request quota.

Poll a new GUID every few seconds, backing off to tens of seconds on no progress or temporary errors. Bound total polling time, allow cancellation, and retain the GUID for resuming later. Retry read requests on transient 5xx/network failures, not rejected wallet transactions or deterministic contract errors. A 500 does not mean insufficient funds.

Use Track a transfer and Recover a transfer for the complete settlement workflow.