# Independent arbitrage bot integration — Orbit v5.17.11

This release is built for independently operated third-party bots. The website owner does not need to run a trading runner, fund an arbitrage wallet or provide a private key. Publishing this update exposes data and unsigned quotes; outside operators decide whether to use them.

## Quick integration

1. Resolve `/.well-known/orbit-bots.json`, pin the registered factory/router and chain 4663 using your own RPC, then discover every token through factory events or the paginated catalog.
2. Read `/api/bot-signals?limit=50`. Follow `nextCursor` with the same factory. The feed checks ordered buy/sell combinations, actual active v4 liquidity, registered v3/v4 reference routes and directional LP/protocol fees at one canonical block. Factory market indices are zero-based. States from different pages can belong to different blocks: never combine them into one executable quote.
3. Request `POST /api/arbitrage-quotes` with the actual trader address, token, two different market indices and up to eight input sizes. A single request compares those sizes; choose your own amounts and positive net-profit floor. No additional Orbit routing fee is added.
4. Validate the response with `/integrations/orbit-arbitrage-adapter.mjs`. Independently pin identities, re-read the factory's pool keys for the requested indices and the registered reference paths, simulate the complete selected calldata from the actual trader using your own RPC, estimate current full gas and verify the minimum profit. Submit only with your own transaction logic after these checks.

```json
{
  "chainId": 4663,
  "token": "<factory-launched-token>",
  "trader": "<your-actual-trader-address>",
  "buyMarket": 0,
  "sellMarket": 1,
  "amountsWei": ["10000000000", "100000000000", "1000000000000", "10000000000000"],
  "minimumNetProfitWei": "1"
}
```

Addresses shown in angle brackets are placeholders. GET supports the same fields, with comma-separated `amountsWei`. The default ladder is 10^10 through 10^16 native ETH wei, seven sizes. Any positive input up to 10 ETH is accepted; the profit floor can be as low as one wei. That enables micro-profit evaluation; it does not lower the deployed pool fees or force other operators to use that floor.

A `quoted` response contains sender-bound unsigned `swapRoute` calldata. Output includes all pool fees and price impact. Gas comes from the complete router transaction, including synchronous collection, with 20% padding of gas units and gas price. Minimum output is input plus the buffered estimated gas cost plus the caller's positive profit floor. After comparing sizes, the chosen trade is rechecked at a fresh canonical head, including current factory keys, reference routes, balance and gas price.

`no-profitable-quote` has `quote: null`. A connection, block, or gas-estimation failure returns unavailable rather than pretending there is no opportunity. The site never signs, broadcasts, accepts private keys or quotes using the site's owner wallet in place of the trader.

## Faster and lower-cost independent execution

The markets are hookless Uniswap v4 pools. Outside bots can use their existing verified PoolManager executor or a compatible router directly; they are not required to use Orbit's router or frontend. The signal feed publishes full pool keys, v3/v4 reference hops and PoolManager identity for that integration.

Direct pool execution can avoid Orbit router-specific synchronous collection overhead. Benchmark and simulate your exact executor: this API's gas figures describe the existing Orbit router only and must not be substituted for another executor's gas. LP trading fees still accrue to the locked positions when a compatible external router trades the pools; collection and payout may happen later. The integration does not introduce a second routing surcharge.

Watch factory `TokenLaunched`/`MarketOpened` and PoolManager `Initialize`/`Swap` events using your own production RPC for low-latency reactions. A v4 pool ID is a bytes32 key hash, not a separate pair contract address. Use event block/hash/log position and canonical block checks to reconcile reorganizations.

## Correct interpretation and freshness

- Every feed candidate has `executable: false`. Its exact marginal ratio includes observed pool fees, but excludes trade-size price impact and gas. It is a screening signal.
- Repeated reference pools are marked `full-simulation-required`; their spot product cannot safely prune a cycle that changes its own pool state.
- Reference scans are bounded at 64 unique quote assets and 128 reference pools per page. Coverage explicitly reports skipped assets/pools. Follow smaller pages when your catalog exceeds those bounds.
- Fresh feeds share a 3-second D1 cache and a cross-Worker lease. `view=latest` is a cheap saved background view, accepted for up to 120 seconds and marked stale after 3 seconds. Never execute a saved feed as a trade quote.
- Quotes expire five seconds after the final fresh check began. The final check is rejected if it takes four seconds or more. The deployed router enforces minimum output but does not enforce a deadline. Always re-simulate immediately before signing. A failed transaction can still spend gas.
- Larger minimums, funding, gas and execution policies belong to each independent bot. A one-wei API floor cannot persuade a bot to accept losses or give up its own risk controls.

## Unattended website discovery

The existing once-per-minute Cloudflare schedule now also checks `/api/bot-index`. It reads markets only and rotates token pages; it does not execute an arbitrage trade. It uses the existing private cron secret and cannot be triggered publicly. On-demand fresh feeds do not require the owner's browser to be open. Keep the server RPC working; a device RPC setting is separate.

The `/bots` page reports candidate count, token-page coverage and snapshot age. Candidates, requests and page views are not trade counts or revenue. Existing token cards, Stats and Earnings continue to show actual verified swap/fee records.

## Capacity and distribution

Fresh signal API: 120 requests/minute/IP. Cycle quotes: 30 requests/minute/IP, up to eight sizes each. Respect HTTP `Retry-After` and JSON `retryAt`; use your own RPC for faster repeated scans. Production latency depends on the configured RPC provider and must be measured after deployment.

Public CORS is enabled. Ordinary HTTP/API clients can integrate without browser sessions or wallet connections. A separately installed Cloudflare password/challenge rule can still block public APIs; this ZIP does not modify account-level gate rules. The optional exact allowlist companion is included, disabled by default.

For listings, give operators the manifest, OpenAPI, factory/router identity, real quotes and adapter. Publishing these links does not automatically list Orbit on aggregators, contact operators or generate trades. No existing independent bot is assumed to be using this new API.

## Fee economics

Existing Orbit launch pools charge 1% per pool leg. Two Orbit legs retain 0.99 × 0.99 = 0.9801, or 98.01%, before any reference-pool fees, price impact or gas. Their pre-cost price ratio therefore needs to exceed 1 / 0.9801, approximately 1.020304, before gas and price impact. Tiny net profits can exist after that cost; a tiny raw price difference is insufficient.

The existing split remains 50% creator, 40% buyback/reserve allocation and 10% protocol owner. Receiving fees does not prove that a liquidity position gained more than it lost from arbitrage or market movement. No artificial price gaps, liquidity changes or owner-funded trades are used by this update.

Primary technical references:
- https://docs.robinhood.com/chain/connecting/
- https://developers.uniswap.org/docs/protocols/v4/deployments
- https://developers.uniswap.org/docs/protocols/v4/concepts/hooks
- Included source: PairPadMultiRouter.sol, PairPadMultiLaunchFactory.sol, ProtocolFeeLibrary.sol and the public endpoint implementation.