How IoWare reads, scores and executes.
IoWare is an on-chain market I/O engine. Market state goes in — liquidity, price, depth, fees, block state, route availability, execution risk — and a verifiable execution path comes out. Nothing on screen is invented: every value is read from the chain, a registered pool contract or a named API, and prints Unavailable when it cannot be.
Data sources
- RPC — JSON-RPC to the chain's node (failover, retries, DNS pin for local dev). Every batch is answered by one node and carries the block it was read at.
- Pool contracts — Uniswap V2 pairs (getReserves), Uniswap V3 pools (slot0, liquidity, tick bitmap), Pons bonding curves; discovered through registered factories, never assumed from an address.
- Explorer API — Blockscout for verification, names, proxies. Optional, server-side.
- Indexer API — GeckoTerminal for 24h volume and pool age. Optional, labelled, never used for prices or depth.
No off-chain price feed is consulted. USD references come from the USD-pegged quote (= 1) or the wrapped native's deepest USD pool at the same read.
Route Quality Score
Deterministic and transparent. It ranks candidates; it is not a guarantee of safety.
| Expected output | 35% | output ÷ best candidate output |
| Liquidity depth | 25% | min(1, shallowest-hop depth ÷ $250,000); 0 without a USD reference |
| Price impact | 15% | 1 − min(1, impact ÷ 5%) |
| Route simplicity | 10% | 1 hop = 1.0 · 2 hops = 0.5 |
| Quote freshness | 10% | 1 − min(1, age ÷ stale threshold), re-scored live in the browser |
| Fee efficiency | 5% | 1 − min(1, gas cost ÷ 0.2% of output value); neutral 0.5 when unknown |
Quote freshness
Age is measured from the provider's own timestamp. Thresholds are per integration:
| On-chain pool simulation | AGING ≥ 12s | STALE ≥ 30s → Execute disabled, Refresh Quote required |
| On-chain metadata | AGING ≥ 60s | STALE ≥ 300s → Execute disabled, Refresh Quote required |
| Block head | AGING ≥ 6s | STALE ≥ 20s → Execute disabled, Refresh Quote required |
| Indexer snapshot | AGING ≥ 120s | STALE ≥ 600s → Execute disabled, Refresh Quote required |
Depth classification
- DEEP — referenced depth ≥ $1,000,000 and a $10k execution moves the price ≤ 0.5%.
- NORMAL — depth ≥ $50,000 and a $1k execution moves the price ≤ 1% with a full fill.
- THIN — anything below, with the failing rule printed.
- INSUFFICIENT DATA — no USD reference for the quote token, or no simulation at the reference size.
Price impact excludes the LP fee (Uniswap convention). Every ladder row is a real simulation with the pool's own swap math at one block.
Execution safety
- Routes are executed only through routers whose factory() (and WETH9()) bindings were verified on chain; otherwise they are read-only.
- Before signing: wallet network, quote freshness, balance, decimals, slippage, route validity, destination router and an eth_call simulation from your address. A failing check disables Execute with the exact reason.
- Routes above 5% impact are rejected; above 1% they are THIN. Slippage above 3% is flagged.
- IoWare encodes calldata and simulates. The wallet signs and broadcasts. No seed phrase, no private key, no server-side signing.
Chains
| Robinhood Chain · 4663 | scan · quote · route · execute · poolDepth |
Add a chain in src/config/chains.ts with its factories and routers; features not listed print “Not available on this network yet.”
API
| GET | /api/status?chainId= | RPC head, chain match, venue router verification, explorer/indexer configuration |
| GET | /api/block?chainId= | Latest block, node latency, endpoint label |
| GET | /api/scan/:chain/:address | Contract + token metadata, registered pools, reserves, verdict, verification — with sources |
| GET | /api/token/:chain/:address | ERC-20 name / symbol / decimals / totalSupply read on chain |
| GET | /api/pool/:chain/:address | Raw state of one pool (Uniswap V2, V3 or Pons curve) |
| GET | /api/market/:chain/:token?sizes=&side= | Every pool for an asset, USD-referenced depth, depth ladder, verdict with reasons |
| GET | /api/route?chainId&tokenIn&tokenOut&amountIn&slippageBps | Normalized quote, every candidate, Route Quality Scores and the formula |
| GET | /api/quote?… | Best executable route with calldata when a recipient is given |
| GET | /api/price?chainId&asset | USD reference derived from registered pools only |
| POST | /api/simulate | eth_call dry run + gas estimate of prepared calldata from the sender |
| GET | /api/tx/:chain/:hash | Receipt from the node: status, block, fee, decoded ERC-20 transfers |
| POST | /api/rpc/:chain | Read-only JSON-RPC relay for the browser wallet client (allow-listed methods) |
All responses are JSON, no-store, stamped with block and time. Errors are { error: { code, title, message, status } }. Inputs are validated with zod; routes are rate-limited; secrets never leave the server.