# Orbit Swap integration

Orbit Swap is an EVM swap and bridge interface powered by LI.FI aggregation.
Supported networks, token contracts, DEX venues and bridge routes are discovered
from the provider. A listing in the catalog does not guarantee a route for a
particular amount, pair or owner fee. Gas and other provider fees vary.

## Route through Orbit

Link to `https://orbitlaunch.io/?tab=swap` from your application. Optional draft
parameters are `fromChain`, `toChain`, `fromToken`, `toToken`, and `amount`.
`amount` is a human-readable decimal quantity. Tokens must be actual contract
addresses from the live catalog on their corresponding networks. Draft links
never request an approval or execute a transaction automatically.

An external app can request an unsigned quote through:

```
GET /api/swap?view=quote&fromChain=1&toChain=8453&fromToken=0x...&toToken=0x...&fromAddress=0x...&fromAmount=100000000&slippage=0.005&order=CHEAPEST
```

`fromAmount` is an integer in input-token base units. Resolve decimals and token
addresses with `/api/swap?view=tokens&chain=CHAIN_ID`. Supported metadata is at
`/api/swap?view=catalog`; fee capabilities are at `/api/swap?view=capabilities`.
Quote limits apply per IP. The recipient is always the requesting wallet. The
returned quote has a 2-minute validity period. Compare `CHEAPEST` and `FASTEST`
quotes, gas estimates, minimum output and the other provider fees before asking
the user to sign. Validate the chain, wallet, balance and fresh simulation again.

Partner apps can ask a user to complete a quote on Orbit, or sign the unsigned
transaction with their own wallet flow. Public GET views allow cross-origin
reads. To register a route in Orbit's public receipt feed, POST the action
`record` with its issued `ticket` and full transaction `hash`. This action also
allows partner origins because it independently verifies the actual on-chain
transaction before inserting a record; it cannot move funds or report a
successful receipt. Quote POST and read-proxy POST require the site origin. The transaction
must match the server-issued route, including wallet, contract, data and value.
GET `/api/swap?view=activity&id=CHAIN_ID:0xHASH` checks one registered route.

## Owner fee

Every supported quote requests a transparent additional **0.05% (5 basis points)**
of the input amount to the protocol owner wallet through LI.FI `distributionFees`.
The amount rounds down to input-token base units. Routes without compatible
FeeForwarder support, a matching Distributions quote entry and matching fee
calldata are unavailable. The new fee is separate from existing launchpad fees.
It is forwarded on the source chain in the input asset, including when a
subsequent bridge delivery needs recovery. No manual claim is needed for this fee.

The owner dashboard counts only matching, confirmed source FeeForwarder events.
It shows the most recent 32 registered Orbit routes, with exact token totals
grouped by chain and asset, rather than invented USD earnings. Quotes, unconfirmed
hashes and transactions made elsewhere do not count as revenue.

Other apps and users must choose to use Orbit's route. This integration cannot
intercept unrelated Uniswap, SushiSwap, KyberSwap or 1inch transactions or promise
that external aggregators will send traffic to Orbit. A new solver, liquidity
pool or external integration agreement would be separate work.

## Provider access and tracking

If provider access is denied, the owner can run `Set-Swap-Key.cmd` after updating
the existing Worker. It securely prompts for a LI.FI API key and stores
`LIFI_API_KEY` as a Cloudflare secret. Never paste a key into site settings,
source files, browser code or a URL. Obtain provider access at https://portal.li.fi.

New mobile wallet sessions offer common EVM networks as optional permissions.
An older or restricted session must be reconnected before using an unapproved
source network. A browser/in-wallet browser connection can support additional
networks if the wallet permits them. No mobile device transaction was verified
in the build environment.

Source and destination receipts require two confirmations for the displayed
completion state. Destination output is reported by the provider and paired
with a verified destination receipt. A partial delivery, provider-reported
refund or bridge failure remains distinct from completed delivery. Bridge/RPC
outages preserve the last verified state and retry. The live feed polls while
the tab is visible; it is not a zero-latency or always-on background indexer.

Rejecting a wallet request closes review with a cancellation message. Closing
review while a wallet request is waiting prevents further automatic steps.
Already submitted approvals/transactions cannot be canceled by closing a dialog;
their hashes remain available for checking. Approvals use exact quoted amounts,
with a reset step when required for an existing insufficient allowance.

## Official references

- https://docs.li.fi/api-reference/get-a-quote-for-a-token-transfer
- https://docs.li.fi/introduction/integrating-lifi/fee-forwarder
- https://docs.li.fi/api-reference/check-the-status-of-a-cross-chain-transfer
- https://docs.li.fi/introduction/lifi-architecture/smart-contract-addresses
- https://github.com/lifinance/contracts/blob/main/src/Periphery/FeeForwarder.sol

## Catalog and background fees

Worker requests use manual redirect handling. Network and token choices remain visible as cached or starter metadata during provider outages; actual quotes require live validated routes. Receipt and balance reads are independent of provider catalog availability. Swap connects any supported EVM wallet and requests its selected source network when executing.

Manage includes the [background fee hub](/fee-hub-guide.md) for fees generated by existing Orbit markets. Automatic collection is optional and off by default. It spends gas from a separate wallet under fixed limits and does not guarantee profit or redirect unrelated DEX trades.

## v5.17.4 route verification

Live same-chain and bridge quotes were captured as unsigned regression fixtures. Their executed fee-forwarder calls contain both a provider fee and the exact 0.05% owner distribution. The validator now accounts for both instead of rejecting otherwise valid quotes. It verifies gross input, network, router, recipient, fee and minimum. Same-chain calldata must finish in the requested output asset. Wallet submission still requires fresh balance, gas and exact-route simulation.

Token pickers preserve provider artwork, use bundled stablecoin/native images where known, and use a cached first-party artwork proxy for external tokens. RPC read recovery may use a connected wallet on the selected source chain; errors caused by an execution revert do not retry on another chain.