> For the complete documentation index, see [llms.txt](https://docs.surgecardano.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.surgecardano.com/strategies/rule-based.md). # Rule-based strategies A rule-based plan is a set of price **levels** you draw on one token's chart. Each level says "buy this much ADA worth when the price is at X or better" or "sell this many tokens when the price is at Y or better", how many times it may fire, and how long to wait between firings. Surge checks the levels against live quotes and fires them when the market reaches them. A level's price is enforced on chain, not just used as a trigger: **a fill can be better than the level, never worse.** ### What it is and when to use it Rule-based is for when you have specific prices in mind. Typical plans: * **Ladder buy the dip** — four buy levels at falling prices, 100 ADA each, one execution each. * **Scale out** — three sell levels at rising prices, each selling a third of your holding. * **Repeating range trade** — one buy at the bottom of a range and one sell at the top, each allowed 20 executions with a 10-minute wait, so they cycle as the price oscillates. Each level is independent. There is no "if this then that" between levels, no indicator conditions and no time-of-day conditions — price only. ### How it works **Quotes at size.** For each armed level, on every price tick for the pair (and at least once a minute regardless), Surge asks each allowed DEX's deepest pool what your exact order size would receive right now, including that pool's fee and price impact. The level is **eligible** when: * the effective price at size satisfies the level (buy: at or below the level; sell: at or above), rounded in your disfavour so a borderline never fires; * the level has executions left; * its wait time since its last attempt has elapsed; * if it failed to build recently, its retry back-off (1, 2, then 4 minutes) has elapsed. **Which DEX.** Among eligible venues, the one that pays the most **net of fees** (batcher, network and Surge fee converted into the same unit) wins. **Which level.** If several levels are eligible at once, the one furthest past its line fires first; ties go to the oldest level. **One at a time per wallet.** A wallet fires at most one order per **2 minutes**, and never while another level on that wallet is being built, awaiting signature or open on chain. **Minimum received.** The order's floor is the higher of the level-implied amount (your size converted at the level price, rounded up) and expected output × (1 − slippage). Whichever is higher protects you. **Funding check.** Just before building, Surge checks the wallet holds the size plus the DEX's deposit and batcher fee. If not, the level is skipped with "insufficient ADA/token" and stays armed. **Executions are spent at submit.** A level's execution count goes down when the order reaches the chain — not when it fills. A refund or a cancelled parked order does **not** give the execution back. **Build failures.** A level that fails to build three times in a row is handled by your **failure policy**: **Disable level** (only that level stops; re-enable it from the Levels tab) or **Pause plan** (the whole plan pauses; click Resume). ### Set up a rule-based strategy | Field | What it means | Default | Limits and guidance | | ----------------------- | ------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------- | | Name | Label | — | Up to 60 characters | | Pair | The token, against ADA | — | | | Venues | Which DEXes may quote and fill | All that host the pair | Any of Minswap, SundaeSwap, WingRiders, Splash; each toggle shows a live status | | Levels — Side | Buy or sell | Buy if placed below the market, sell if above | | | Levels — Price (₳) | ADA per token at which the level fires | — | Positive; up to 18 decimal places | | Levels — Size | **ADA to spend** for a buy; **tokens to sell** for a sell | — | Must be at least one smallest unit of the token/ADA | | Levels — Executions | How many times the level may fire | `[VERIFY: default]` | 1 or more | | Levels — Wait (minutes) | Minimum time between two firings of the same level | 2 | Minimum 2 | | Slippage tolerance | Second input to the minimum-received floor | `[VERIFY: default]` | 0.1%–5% | | Failure policy | What three consecutive build failures do | Disable level | Disable level / Pause plan | | Wallet | The strategy wallet that funds, signs and receives everything | — | | | Acknowledgement | Required checkbox | — | | You can also **click on the chart** to place a level and **drag** to move it. **Preview.** Shows the projected ADA in, ADA out, tokens in and out, fees, and the P\&L *if every level filled at exactly its own price* — with the honest caveat that a plan that accumulates tokens projects a negative ADA figure. Each level also shows its expected price impact. A buy placed above the current price is flagged: it will fire on the first check. **Required balance.** ADA for all buy sizes plus fees and deposit; tokens for all sell sizes. **Levels can be edited live.** Add, edit or delete levels on the Levels tab of a running plan. Raising a spent level's execution count re-arms it. Editing a level does not reset its wait timer. Deleting a level is permanent, but orders it already placed keep their history. `[VERIFY: very small prices (below 0.000001 ADA) and sizes that round to zero units are rejected by the server with a validation message; the builder may not warn beforehand.]` ### While it runs Plan status (`[VERIFY: exact on-screen wording]`): | Status | Meaning | | ------------------------- | ----------------------------------------------------------------------------------- | | Running | Evaluating levels | | Awaiting levels | Every level is spent, disabled or deleted — add or re-enable one | | Paused — socket down | Your tab is closed or disconnected; resumes on reconnect | | Paused — price feed stale | The price feed is not live; resumes when it is | | Paused — circuit breaker | Your failure policy paused the plan after repeated build failures. Click **Resume** | | Stopped | You stopped it | Level states on the **Levels** tab: armed, pending build, pending sign, submitted, spent (executions used up), failed (will retry after back-off), disabled. The **Executions** tab lists every attempt with its venue, size, expected and received amounts and fees. The **Overview** shows realized P\&L over filled orders (ADA received from sells − ADA spent on buys − fees) and a separate "fees paid" total over every attempt that reached the chain. ### Fees example A buy level of 100 ADA at 0.50 ADA per token on SundaeSwap (V3 pool): | | On-chain cost | Shown in preview and history | | ---------------------------------- | ---------------------- | ---------------------------- | | Surge fee 0.2% × 100 | 0.20 ADA | 0.978 ADA (recorded minimum) | | Batcher fee | 1.00 ADA | 1.00 ADA | | Network fee | \~0.20 ADA | 0.20 ADA | | Pool fee \~0.3% (inside the quote) | \~0.30 ADA | — | | Deposit | 2 ADA locked, returned | — | The venue choice already accounts for these: a DEX quoting 0.5% better but charging 1.5 ADA more in batcher fee loses on a 100 ADA order. See [Fee breakdown](/fees-tiers-and-staking/fee-breakdown.md). ### Wallet interaction One strategy wallet funds every buy (ADA), holds the tokens for every sell, signs every order and receives every fill. Sell proceeds are recorded net of the returned deposit. Do not share the wallet with another plan or strategy: the one-order-per-wallet rule is enforced per wallet, so a second plan on the same wallet would simply wait behind the first. ### Edge cases and failure modes * **Price reaches the level but nothing fires.** Check the wait timer, the 2-minute wallet gap, an order still open on the wallet, funding, and whether *any* venue quotes at the level *at your size* — a thin pool may quote worse than the mid price you see on the chart. * **Order refunded.** Recorded as "refunded — minimum unreachable at execution"; the execution is spent; the level re-arms (if executions remain) after its wait. * **Order parked (non-Minswap).** After 5 minutes Surge builds a cancel and shows **Cancel ready**. Until you sign it, that wallet fires nothing else. * **Ambiguous fill.** If one batcher transaction consumed this order and another of yours at once, Surge cannot attribute the proceeds and leaves the level in flight until you check it — deliberately, rather than guessing. * **Tab closed while awaiting signature.** After 2 minutes the attempt is released and the level re-armed; its execution is *not* spent (it never reached the chain). * **Archiving.** Stop first; archive requires nothing in flight. Delete removes the plan and its history. ### FAQ **Does a sell level fire when the chart touches the price?** Only if a pool will actually pay that price *for your size*. Large sizes into thin pools quote below the mid. **Can a level fire twice in a row?** Only after its wait (minimum 2 minutes) and only if it has executions left. **Why was my execution used up by a refund?** Because the order reached the chain. "Reached the market" is the test; a refund still cost a network fee. **Can I use RSI or moving averages as conditions?** No. The chart can display them, but levels trigger on price only. **What does "pause plan" protect me from?** A wallet that has run dry or a token whose pool vanished — rather than each level burning three attempts in turn, the whole plan stops until you look. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.surgecardano.com/strategies/rule-based.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.