forager
Try a plan
Docs

How Forager works, field by field

From the sentence you type to the transaction a keeper sends. Short version on the home page.

1. Reading a plan

Your text goes to Claude Haiku 5.5 (through OpenRouter) with a fixed rule schema (strict structured output), and the answer is checked against the same schema before use. The model only fills the form; it never sees prices and never trades. The three example plans on the home page have fixed rules and need no model call. Anything the form cannot hold (several stocks at once, indicators, news, leverage, shorting) is listed under "Left out".

2. The rule

  • symbol: one of ANT, NVDA, TSLA, GOOGL, QQQ, AMZN, MSFT.
  • budget_usdg, buy.usdg_per_buy, buy.max_open_lots: how much in total, per buy, and how many buys may be held at once.
  • buy.trigger: immediately, dip_from_ref, rise_from_ref, price_below, price_above, every_hours, after_nasdaq_close.
  • buy.ref (for dips and rises): friday_close, last_nasdaq_close, last_buy, high_24h, price_24h_ago. With last_buy the first buy happens at the start, then each further buy waits for the next drop.
  • sell: take_profit_pct, stop_loss_pct, max_hold_hours and at (never, next_nasdaq_open, next_nasdaq_close). Whichever comes first sells the lot.
  • only_when_nasdaq_closed: buys only at nights, weekends and holidays.

A live plan stores keccak256 of the rule's canonical JSON (keys sorted, no spaces) on-chain as ruleHash. GET /api/rules/<hash> returns that exact JSON, so anyone can hash it and compare. Example:

{"budget_usdg":100,"buy":{"every_hours":null,"max_open_lots":4,"pct":5,"price":null,"ref":"last_buy","trigger":"dip_from_ref","usdg_per_buy":25},"only_when_nasdaq_closed":false,"sell":{"at":"never","max_hold_hours":null,"stop_loss_pct":null,"take_profit_pct":8},"summary":"Buy $25 of ANT each time it drops 5% below the last buy; sell each lot at +8%.","symbol":"ANT","unsupported":null}

3. How a test runs

  • Prices: 5-minute candles built from every Swap event of the stock's Uniswap V3 USDG pool on Robinhood Chain, 24/7. Nasdaq opens and closes come from daily sessions (Yahoo chart) and are only used for Nasdaq-based steps.
  • Decisions happen at each candle's close, exits before entries. A fixed reference fires once per value, so a plan does not buy again on every candle under the same Friday close.
  • Every fill pays the pool fee (0.05% or 0.3%). Price impact is not modelled; for small sizes on these pools it is a fraction of the fee.
  • "Just holding" buys the whole budget at the first candle and holds to the end.
  • Same rule, same window, same result: there is no randomness and no model in the loop.

4. ForagerRails

0x26Ae485109cECF9bfEF9770b041708897d52D413 · source matched on Sourcify · checks on the verify page.

createPlan(token, fee, dailyCap, maxSlipBps, expiry, maxBuyPrice, minSellPrice, ruleHash)
setPrices(id, maxBuyPrice, minSellPrice)    // owner
setPaused(id, paused)                       // owner
cancelPlan(id)                              // owner, or anyone after expiry
buy(id, usdgIn)  /  sell(id, tokenIn)       // keeper only, inside every limit
leftToday(id) · buyFloor(id, usdgIn) · sellCharge(id, tokenIn) · capOf(user)
  • Prices are USDG (6 decimals) per whole share. 0 switches a side off.
  • Daily cap: $100 per plan; $500 when the owner holds 0.2% of $FORAG supply, $2,000 at 1%. Checked at each trade.
  • The keeper replays your rule with the same engine since the plan opened and sends a trade only for a step made in the last 15 minutes.

5. API and MCP

  • GET /api/stocks · GET /api/candles/<SYMBOL>?days=2 · GET /api/plans · GET /api/stats
  • POST /api/parse { text } → rule · POST /api/simulate { rule, days } → result + share id · GET /api/sim/<id>
  • POST /api/rules { rule } → ruleHash · GET /api/rules/<hash>

MCP (Streamable HTTP, read-only): tools list_stocks, parse_plan, simulate_plan.

{ "mcpServers": { "forager": { "url": "https://forager.pro/api/mcp" } } }