API and tracking
The API origin is https://api.omnisea.io. Launch endpoints retain the /omniapps prefix; market data uses /omnipad. Reads and quote requests do not require a private API key. Wallet signatures are required for on-chain writes. Do not expose RPC, webhook or deployer secrets to clients.
Launch endpoints
| Method and path | Purpose |
|---|---|
GET /omniapps | Active configuration and availability |
POST /omniapps/uploads | Image and metadata upload |
POST /omniapps/pons/quote | Local or cross-chain launch quote |
POST /omniapps/requests/track | Verify a confirmed receipt; body {chainId, transactionHash} |
GET /omniapps/requests/{requestId} | One launch, including its deployment version |
GET /omniapps/launches | Successful public launches |
GET /wallets/{address}/omniapps/launches | That initiator's launches, including pending or failed requests |
Lists return {items, nextCursor} with up to 25 rows. Pass the opaque cursor unchanged for the next page. Supported filters: destinationChainId=4663, platform=pons, sort=new|fdv|volume, minFdv, maxFdv, minVolume, maxVolume. Metrics are USD values; volume is trailing 24 hours. Reset pagination when filters change. Unsupported destination/platform values are rejected. Unknown metrics remain null, not zero; show a dash rather than inventing a valuation.
Market endpoints
| Method and path | Parameters / result |
|---|---|
GET /omnipad/search | Required chainId; q matches name, symbol, token, curve, pool manager or pool ID; up to 30 items |
GET /omnipad/{chainId}/{token} | Token metadata, phase, curve, pool ID/manager, prices, FDV, volume and registration status |
GET /omnipad/{chainId}/{token}/trades | {items, nextCursor}, up to 50 rows; optional cursor |
GET /omnipad/{chainId}/{token}/series | range: 1D, 1W, 1M, 1Y, All; timestamp, closing sampled USD price and volume per bucket |
GET /omnipad/{chainId}/{token}/holders | Up to 100 indexed balances, not a live RPC balance proof |
POST /omnipad/{chainId}/{token}/quote | {account, side, amount}; see trading |
Series timestamps are Unix seconds. Prices and monetary amounts may be null or decimal strings. Pool IDs are not ERC-20 or pool contract addresses. An indexed launch can precede adapter registration or its first trade; tolerate missing metrics and temporary quote failures. Data covers tracked launches, not every Pons token.
State and event evidence
Store the request ID, deployment version, source chain, transaction hash and LayerZero GUID. The on-chain envelope version is separate from deployment version 2.
| API state | Meaning |
|---|---|
sent | Source Gateway request indexed |
queued | Destination Gateway received it; token creation is not complete |
succeeded | Composer emitted PonsLaunchSucceeded; token and curve exist |
failed | Composer recorded terminal failure; inspect refund credit |
Local launches emit PonsLaunchSucceeded in their Robinhood receipt with a zero GUID; there is no LayerZero transaction to track or retry. Cross-chain launches emit LaunchRequested on the source Gateway, LaunchQueued on the destination Gateway, and PonsLaunchSucceeded or PonsLaunchFailed on the composer. Filter logs by the pinned emitter, not just event signature.
The tracking endpoint verifies canonical receipts and confirmations and returns {requestIds}. 404 on request lookup can mean indexing is pending. An early tracking call can return 409; retry after confirmations with backoff. A source receipt is never proof of destination creation. Signed, filtered webhooks provide indexing; integrators can consume the API or index events themselves without creating Omnisea's operator webhooks.
Recovery and refunds
For an unresolved cross-chain request, read status(requestId) and consumedGuid(guid) on the correct composer. Composer status is 0 = None, 1 = Succeeded, 2 = Refunded (credit recorded, not necessarily claimed). Verify both Endpoint commitment and original payload before retrying receive or compose. A receive retry needs destination gas; a compose retry also resupplies the exact committed maxPonsFee + maxProtocolFee. Never replay a consumed GUID or resubmit a successful source launch.
External Pons errors leave compose retryable. Deadline expiry or fee-cap excess can be delivered as a terminal failure with credit. Use the configured successful-execution gas budget, not a low estimate from an early failure path. Do not confuse this recovery with Omniassets' retryFailedMessage or restoreFailedMessage functions.
Read refunds(requestId) and refundBeneficiary(requestId). Only that beneficiary can call the composer:
function claimRefund(bytes32 requestId, address payable recipient) external;Claiming transfers the outstanding native credit to the chosen payable address. Source gas and spent LayerZero fees are not refundable. A successful launch may also have excess fee credit. Index RefundCredited and RefundClaimed independently from launch success.