API and recovery

Use https://api.omnisea.io as the API origin. Public quote and read endpoints need no private integration key. On-chain submission still requires the sender's wallet signature. Check GET /omnigas for hosted API availability; the direct contract flow does not depend on the indexer.

Quote API

POST /omnigas/quote
Content-Type: application/json

{
  "sourceChainId": 8453,
  "destinationChainId": 4663,
  "initiator": "0xYOUR_WALLET",
  "recipient": "0xDESTINATION_WALLET",
  "amount": "1000000000000000"
}

Replace the placeholders with valid addresses. recipient may be omitted to use initiator. amount is a positive decimal integer string in destination base units and must fit uint128. For programmatic hooks, add {target, data, value, gasLimit} under hook; value is an integer string and gasLimit a number. The API rejects transport addresses as recipient or hook target.

The response contains version, sourceChainId, destinationChainId, contract, destinationEid, request, value and expiresAt. expiresAt is Unix milliseconds, currently 30 seconds after the quote. request.deadline is Unix seconds, currently one hour ahead. value is source native payment, not destination amount.

Before sending:

1. Pin version 1, chain IDs, EIDs and deployed addresses from Bridge gas.
2. Compare the quoted recipient, amount and every hook field with the original inputs; reject unexpected execution data.
3. Convert request.amount, request.deadline, request.hook.value and value to bigint. Keep hook gasLimit as a number.
4. Read quote(destinationEid, request) from the pinned source contract using the sender account. Require equal native payment and zero lzTokenFee.
5. Simulate bridge(destinationEid, request) with that payment, then ask the wallet to submit. Refresh stale quotes instead of adding a payment buffer.

Tracking endpoints

Pass the returned cursor unchanged. Poll individual pending requests with bounded backoff. 404 can mean not indexed yet; an early tracking request may return 409 until confirmations are reached. Webhooks validate signatures and re-read canonical receipts; do not send unsigned fake webhook events. One contract-address/topic-filtered operator webhook per chain is sufficient; no background polling service is required.

Rows include requestId, guid, version, initiator, recipient, source/destination chain IDs, request, paid/credited amounts, claimed flag and available source/destination transaction hashes. outcome describes hook execution, not overall business success. A hook failure can still be a successfully delivered gas transfer.

Indexing events directly

The integration ABI includes:

event GasRequested(bytes32 indexed requestId, bytes32 indexed guid, address indexed initiator, bytes envelope);
event GasQueued(bytes32 indexed requestId, bytes32 indexed guid, bytes envelope);
event GasDelivered(bytes32 indexed requestId, bytes32 indexed guid, bytes envelope, uint8 outcome, uint256 paid, uint256 credited);
event CreditClaimed(bytes32 indexed requestId, address indexed recipient, address to, uint256 amount);

envelope is abi.encode(Envelope), with fields (uint8 version, bytes32 requestId, uint32 srcEid, uint32 dstEid, address initiator, Request request). Request and Hook layouts are on Bridge gas. Destination events carry the full envelope so indexing can start there even if the source webhook was missed. Validate emitter and route, use canonical block hashes, and deduplicate by chain/transaction/log index. Handle out-of-order events and reorgs.

Claim rejected payouts

Read credits(requestId) on the destination Omnigas contract. Only its recorded recipient may claim; the payout address can be another payable address:

// destinationGas is an ethers Contract connected to the credit recipient's
// signer on the destination, using the downloaded Omnigas ABI.
const credit = await destinationGas.credits(requestId);
if (credit.amount === 0n) throw Error("No credit remains");
const tx = await destinationGas.claim(requestId, payableRecipient);
await tx.wait();

Claims require destination gas. A failed claim rolls back the credit deduction. There is no owner override of the recipient or credit sweep.

Retry delivery, not the source send

For pending delivery, first read completed(guid) on destination Omnigas. If true, do not compose again; inspect payout or credit instead. Otherwise verify the original LayerZero payload, source peer, destination receiver, request ID and Endpoint commitment.

An Endpoint receive retry uses no destination value. An Endpoint compose retry uses index 0, with Omnigas as both from and to, the identical envelope, and exactly request.amount as destination msg.value plus transaction gas. This resupplies native funding; it is not a gas-only operation. Do not construct retry calldata from unverified API or explorer input, and do not call the application callback directly instead of the Endpoint.

Provide enough gas for both the hook and payout bookkeeping. If the commitment is absent or differs, stop rather than inventing a payload. Source gas and spent LayerZero fees are not refundable. Omnigas has no Omniassets-style restore operation.