How HarborDex works

What is real

Every figure in the application comes from a source that is named next to it: on-chain reads through the read-only RPC relay, the Robinhood Stock Token registry (identity by contract address), Chainlink feeds, the issuer’s quote API, and CoinGecko’s public API. When a source does not answer, the figure is shown as unavailable and a retry is offered. No sample numbers, timers or fabricated receipts exist anywhere in production screens.

• Discovery — reviewed metadata, registry metadata and imported (unreviewed) contracts are kept apart and labelled. A category is never inferred from a ticker.
• Trading — same-chain swaps on Robinhood Chain through KyberSwap’s aggregator, settled by a Sourcify-verified router that enforces the minimum received. Calldata is decoded in the browser before signing.
• Lending — Morpho Blue markets whose parameters, oracle and collateral were verified on-chain. Projections use the protocol’s integer math; HarborDex adds a borrow limit of 90 % of the liquidation threshold and pauses new borrowing when a feed is older than 1.5 × its heartbeat.
• Portfolio — balances and positions are read from the chain for the connected wallet or any inspected address. Totals are labelled partial when a price is missing; no P&L is invented.

Supported networks

3 networks are in the registry (2 mainnets). 3 support discovery, 1 supports trading, 1 supports lending and 0 support cross-chain execution. Wallets sign on Robinhood Chain only. A network counts for a capability only when that capability is verified; an architecture able to hold more networks is not evidence that more networks are live.

The Integration status page shows the same registry with live probes, the contracts on the signing allow-list and their verification records.

Integration status

• working Asset discovery: search, filters, sorting, pagination, shareable URL state — Reviewed list + Stock Token registry (by contract address) + Morpho collateral; prices from Chainlink feeds, issuer quotes and CoinGecko, each labelled.
• working Asset detail with issuer facts, verification, venue quote and real price history — History from CoinGecko (assets with a coin id) or Chainlink rounds (Stock Tokens with a feed); assets without a source say so.
• working Import any contract by address (unreviewed token) — On-chain metadata only; labelled “Unreviewed token”; never classified as a stock or commodity.
• working Same-chain swap via KyberSwap (quote, min received, slippage, impact, router, approval, expiry, gas) — KyberSwap Aggregator API (chain slug "robinhood") settled through the Sourcify-verified MetaAggregationRouterV2.
• working Supply collateral → borrow USDG → repay → withdraw (Morpho Blue) — Morpho Blue (Morpho Markets V1) — deployment by Morpho Labs.
• working Lend the loan asset (supply / withdraw) — Secondary action on the Lend & Borrow page.
• working Position health, projected LTV and liquidation price before each action — Same integer math as the contracts (verified in Vitest against Foundry-derived vectors).
• working Oracle freshness policy (pause new borrowing / withdrawal on stale feeds) — HarborDex rule; Morpho itself does not check feed age.
• working Portfolio: balances, valuations, lending positions, health, receipts, watch-only mode — Balances read on-chain per network; totals labelled partial when a price is missing.
• working Watchlist (local, persistent) — Stored in this browser only; no alerts (no scheduler or delivery channel exists).
• blocked Cross-chain execution — No cross-chain provider is configured. LI.FI and Relay list this chain and answered probes, but their settlement contracts are not verified here, so no route can pass the signing guard.
• blocked Trading and lending on Ethereum — KyberSwap lists Ethereum (slug "ethereum", router 0x6131…37b5, Sourcify runtime match) and answered a probe on 2026-09-29, but this deployment signs on one transaction network only; the adapter is not enabled here, so no Ethereum swap is offered. Morpho Blue is live on Ethereum (0xBBBB…FFCb, Sourcify exact match), but no Ethereum market has been curated and verified in this build; lending actions are not offered.
• blocked AAPL, SPCX, GOOGL / USDG markets — Live on Morpho with real liquidity, but their oracle contracts are custom and unverified on Sourcify; excluded until the source is published.
• blocked WalletConnect / mobile QR wallets — No project id configured and the connector bundle breaks the build; injected wallets only.
• unavailable Testnet (46630) trading and lending — Morpho, Chainlink and KyberSwap publish nothing for the Robinhood testnet.
• unavailable Price alerts — Deliberately omitted: no backend scheduler or delivery channel is implemented.

Asset disclosures

Tokenized stocks and ETFs on Robinhood Chain are Stock Tokens issued under the Robinhood Stock Token programme and identified here by the contract address published in the issuer registry. Holding a token does not confer direct ownership of the underlying share; mint, redemption, eligibility and transfer restrictions are governed by the issuer’s terms (the contract’s terms() points to them). The issuer can pause transfers, blocklist addresses, burn balances and upgrade the contract. Feeds price one token, 24/5, so readings age over weekends and US market holidays. HarborDex shows the token reference price, the issuer’s token and underlying-share quotes, and the venue quote separately because they are different numbers.

Commodity-backed tokens listed on Ethereum (Paxos Gold, Tether Gold) and the commodity trusts among the Stock Tokens (gold, silver, oil funds) are classified from their issuers’ own documentation and registry names. Redemption is available only through the issuer, to its onboarded customers, subject to minimums and fees. HarborDex holds nothing and guarantees nothing about backing.

Stablecoins are shown at their feed or market price, never at an assumed 1.00. The venue quote uses USDG as its output asset and labels it as such.

Imported tokens are read from the chain by address and labelled “Unreviewed token”. No category, backing, issuer or price source is assigned to them, however familiar their symbol looks.

Lending positions can be liquidated when collateral value falls below the market’s liquidation threshold. HarborDex never labels a position “safe” and never guarantees a return; rates are the protocol’s current per-second rates compounded over a year.

The reviewed Ethereum list currently holds 7 assets; 6 lending markets are curated on Robinhood Chain. Nothing on this site is investment advice.

$HARBOR token

$HARBOR is HarborDex’s community token. It has no role in discovery, trading or lending: holding it does not change prices, routes, rates, limits or access, and HarborDex makes no statement about its price or supply beyond what the contract itself reports.

Contract address: Soon. The address is not published yet, and the site says so everywhere the token is mentioned. It is published with pnpm token:ca 0x…, which refuses an address unless the chain confirms a contract on Robinhood Chain that answers like an ERC-20 with the symbol HARBOR and that is none of the protocol, market or base-asset contracts HarborDex already uses; the command then redeploys and reads the live address back. pnpm token:ca SOON clears it again.

Once live, the token page shows only what the contract reports (name, decimals, total supply at a block), its Sourcify verification and whether the verified venue has a trade route. No price, holder count or market cap is stated unless it is read from a named source. The address is announced on @HarborDexRH at the same time.

Setup and deployment

1. pnpm install, then copy .env.example to .env.local. Nothing is required for the default configuration; optional private RPC URLs and a CoinGecko key raise rate limits.
2. pnpm verify:config re-checks every pinned address, feed and market against live sources. Run it before a deploy.
3. pnpm dev (port 18500), pnpm test, pnpm typecheck, pnpm build.
4. pnpm e2e:fork rehearses the lending and swap calldata on an Anvil fork of Robinhood Chain; no real funds are ever used by the test suite.
5. Deploy with the Next.js preset on Vercel (or any Node host). API keys, if any, stay server-side.

Security model

• No private keys or seed phrases are ever requested or stored; wallets sign and broadcast.
• Only two contracts may ever be a transaction target or spender: the Morpho Blue singleton and the KyberSwap router on the transaction network.
• Every swap payload is decoded before signing and refused if the recipient, tokens, amount, minimum, fee lines, permits or flags differ from what was reviewed.
• Approvals are exact-amount by default; unlimited approval is an explicit opt-in.
• Amounts are integers end to end (bigint / base units); floats appear only in display.
• Server routes talk only to configured hosts, validate every response with schemas, apply timeouts, retries, caching and per-IP rate limits, and never log secrets.