Introduction

Docs

Documentation: limit-orders.0xo.in (mirror: saucerswap-limit-orders-docs.vercel.app).

Limit and stop orders for SaucerSwap V2 on Hedera, with no keeper bot. A Scaffold-HBAR template: Foundry contracts and a Next.js frontend for Hedera testnet.

Placing a stop-loss in the UI and watching the Hedera Schedule Service fill it, with the order's mirror-node trail

Live on testnet: a 0.1 DAI stop-loss placed in the browser, filled by the Schedule Service with no bot, and its trail on the order page — every step links to HashScan.

You escrow tokens in OrderVault together with a small HBAR budget. The vault mints you an HTS NFT that is the order, and asks the Hedera Schedule Service to call it back. From then on the network itself runs a sweep over each market. Each sweep waits as long as the price needs to reach the nearest trigger, and fills orders whose trigger is met, but only while a guard confirms the pool's TWAP agrees with Chainlink. Nothing off-chain has to stay online.

Sequence diagram between Maker, OrderVault, Schedule Service, Chainlink + pool TWAP, SaucerSwap V2.
Hedera serviceWhat it does here
Schedule Service, 0x16b (HIP-1215)The vault schedules each market's next sweep itself and pays for it from order budgets. No bot, no cron.
Token Service, 0x167Each order is an NFT in a collection the vault controls. Whoever holds the NFT can cancel and receives the fill; the vault wipes it at settlement.
Exchange rate, 0x168Converts gas priced in USD cents to tinybar, so budgets follow the live HBAR rate.
Mirror nodeThe frontend reads order history, NFT holdings and associations from it; no indexer to run.

See it work on testnet

The vault is 0.0.10809822 (0xc265045C65d0114109072d60b3A60231427a06a9), its order NFTs are 0.0.10809825, and the read-only lens is 0.0.10809847. The order types are limit 0.0.10809832, stop 0.0.10809835 and trailing stop 0.0.10809842. All of them, and the four libraries, are verified on Sourcify, so HashScan shows their source. Every row below was executed on testnet and is checked on the mirror node by node scripts/gate-check.mjs --proofs-only. "Scheduled" means the transaction was run by the Schedule Service, not sent by anyone.

What happenedTransaction
Stop-loss filled by the Schedule Service. Order #2 (sell 0.1 DAI at or below 1.0000), placed by a script with its trigger already met, brought the market's next check forward; that scheduled sweep filled it: 0.100175 USDC out against a 0.099478 minimum, Chainlink 0.99979, pool TWAP 1.00230placed 1790870656.011161104, filled (scheduled) 1790870954.024028208
The same through the frontend. Order #3 placed on the Trade page (Playwright driving the real UI and signing with a testnet key) and filled by the next scheduled sweep: 0.100175 USDC out against a 0.099478 minimumplaced 1790871019.550469104, filled (scheduled) 1790871319.125050208
A trailing stop, run by the Schedule Service. Order #1 (0.1 DAI, 0.5% trail, orderType 2) placed from a testnet burner account; its first scheduled check set the peak (OrderStateUpdated), from which the trigger trailsplaced 1790869442.280121132, peak set (scheduled) 1790870954.024028208
Guard refuses a manipulated-looking pool. Order #4's trigger was met, but the HBAR/USDC pool TWAP (2.0151) was ~19.6x Chainlink (0.10299), so the fill was held; the retry backed off from 5 to 10 minheld (scheduled) 1790871684.039916208 and 1790872282.009223208
Orders share a sweep. The sweep that filled #2 also checked trailing stop #1: one run, two orders, each charged 0.7475 HBAR instead of a solo 1.4363(scheduled) 1790870954.024028208
Cancel by the NFT holder. Order #4 cancelled by its holder; 1 HBAR of escrow and 7.04 HBAR of unused budget refunded1790872335.349111575
The order follows its NFT. Order #5's NFT was transferred to another account; the original owner's cancel would revert with NotHolder, and the new holder cancelled and received the 1 HBAR escrow and its 10 HBAR budgettransfer 1790871419.739922428, cancel by the new holder 1790871432.524922728
Keeperless recovery when the network is congested. A third party reserved every second of the Schedule Service's per-second gas capacity in the 64-second window the vault probes, so the sweep could not rebook (SweepScheduleFailed, response 370 SCHEDULE_EXPIRY_IS_BUSY) and the market stalled; a third account's permissionless restartSweep resumed the chainstalled (scheduled) 1790874158.019936208, restarted by a third account 1790874210.109869176

The frontend ships pointed at this vault, so yarn next:dev works without deploying anything. It runs the exact contracts in this repo, and a payer float keeps its scheduled calls funded; a residual stall like the one above is recoverable by anyone with restartSweep.

What testnet can't show, and where it is shown instead.

  • An HBAR fill. The only testnet HBAR/USDC pool trades far from Chainlink, so its guard holds every fill (above). On a fork of mainnet the same guard opens: yarn foundry:fork-guard read Chainlink 0.10271 against a pool TWAP of 0.10265 on 2026-10-01, 4 bps apart.
  • A trailing stop's fill. The testnet DAI and USDC feeds update about once a day, and the DAI/USDC cross moved less than 0.05% over the last month, while the smallest trail is 0.5%; the HBAR market's guard holds every fill; and HTS tokens can't be swapped on a fork. So testnet shows a trailing stop's placement and the Schedule Service's checks setting and raising its peak. The fill itself is covered by test_trailingStop_ridesUpThenFillsOnPullback, the fuzz test testFuzz_trailingStop_triggerNeverFallsAndFiresBelowPeak and the differential campaign against v1.0.1.

From README.md at v1.1 (cee2d4e) · View source

On this page