​
Quickstart: your first sweep

A sweep searches a parameter space: you describe a strategy template plus the ranges to explore, and the Oracle engine generates its own candidates, backtests each in the cloud, and ranks the results. You don’t hand it a list of strategies — you describe the space and it does the search.
A sweep is not “screen a list, then run the survivors.” Generating a fixed candidate list and screening it cheaply is a different workflow — SIEVE → bulk backtest. This quickstart is the parameter search.

​
1. Get a developer account + API key

  1. Create a developer account and grab an API key (prod_…) — see Authentication.
  2. Sweeps require an Oracle quota on your tier. Individual Pro ($29.99/mo) unlocks real sweep usage (20 launches/mo, up to 5,000 backtests per sweep). The free/beginner tiers get only a small teaser. Team (org) tiers raise the per-sweep size and concurrency.
export MANGROVE_API_KEY="prod_..."

​
2. Two ways to drive it

Clone the agent template and let the /sweep skill drive the whole lifecycle for you: 
git clone https://github.com/MangroveTechnologies/mangrove-agent
cd mangrove-agent   # add your MANGROVE_API_KEY to the server config
Then just describe the search in natural language:
“Sweep MACD fast 8→16 and slow 21→30 on BTC 1h, momentum signals, and rank them.”
The skill orients on the catalog, builds the config (with the binary SIEVE pre-filter on by default), validates it, reports the run count + cost, and — after you confirm — launches and ranks the results.

​
B) The HTML config builder

The /sweep skill ships a lightweight sweep-config.html builder. The agent embeds the live signal + dataset catalog into it; you pick a dataset, choose signals (filterable by category — momentum / trend / volume / volatility / patterns), set the parameter ranges, and Download config.json. Hand that file back to the agent and it validates + launches (after confirming with you). The page makes no API calls itself — it only builds the JSON.

​
3. The raw API lifecycle (what the skill does under the hood)

create ──▶ validate ──▶ launch ──▶ poll ──▶ results
 draft      total_runs   async      status    ranked
  1. Orient (free): GET /api/v1/oracle/datasets, GET /api/v1/oracle/signals (each signal carries a category), GET /api/v1/oracle/exec-config/defaults.
  2. Create: POST /api/v1/oracle/experiments with the ExperimentConfig — datasets holds whole dataset OBJECTS, each signal has a signal_type, entry needs ≥1 filter, and params_sweep defines the space. See Experiments for the full body.
  3. Validate: POST /api/v1/oracle/experiments/{id}/validate → { valid, total_runs, errors }. Required before launch. Your tier’s max_backtests_per_sweep is enforced here (403 if the size exceeds it) — there is no fixed 99 limit (that 99 is SIEVE’s per-call cap, a different feature).
  4. Launch: POST /api/v1/oracle/experiments/{id}/launch (async, runs as a cloud job). A 429 means you’ve hit your tier’s concurrent-sweep cap — wait, then launch. Launch is non-idempotent and may return a 504 gateway timeout even though it succeeded server-side — do not re-launch on a 504; poll GET /api/v1/oracle/experiments/{id} and treat any status past validated as success. (The SDK’s launch_experiment_and_wait() does this for you.)
  5. Read: GET /api/v1/oracle/results?experiment_id=<id> — paginated, ranked metrics per strategy.

​
4. Control the sweep size

You decide how many backtests run:
  • grid (search_mode: "grid"): grid_signals.n_param_combos caps how many combinations are drawn from the space (it does not run the full cross-product by default).
  • random (search_mode: "random"): n_random = number of Monte-Carlo samples.
Pick the size deliberately — it’s bounded above by your tier’s max_backtests_per_sweep.

​
5. Read the results

Each result row carries ranked metrics. Two gotchas:
  • irr_annualized, total_return, win_rate, max_drawdown are percents (35 = 35%), not fractions.
  • Sort by sortino_ratio (downside-aware), tie-break on sharpe_ratio. A row with total_trades < 10 is insufficient trades, not a winner.
  • benchmark_asset_return / benchmark_btc_return let you check whether the top config actually beat buy-and-hold.
Treat the top sweep result as a candidate, not a verdict: confirm it with a full single-strategy backtest on a properly sized window before paper/live.

​
Costs

create + launch are 1 billable Oracle unit each (the fan-out children are not billed individually); each GET /results is 1 unit — page large, don’t tight-poll.