> ## Documentation Index > Fetch the complete documentation index at: https://docs.itoflow.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run a strategy under a mandate > Write a mandate and position limits, and an Itoflow agent runs a paper portfolio under them on its own schedule, recording each decision with its weights, reasoning and confidence. A live portfolio trades only after a person approves the exact list of trades. A strategy is an agent that runs a portfolio under a mandate you write. At each run it reads data as of that date, decides, records why, and sets when to wake next: on a date, on a move in a held name, or when a drawdown limit is hit. A paper portfolio can trade on its own. A live portfolio waits for you to approve each list of trades. **What you'll get:** a paper portfolio run by an agent, with each decision's target weights, reasoning and stated confidence, and the trades that followed. ```mermaid theme={null} flowchart LR Mandate[Mandate and limits] --> Strategy[Strategy, created paused] Strategy --> Run[Run as of each date] Run --> Decision[Decision with reasoning] Decision --> Paper[Paper trades] Decision --> Approval[Your approval of live trades] ``` ## Before you start * An Itoflow account. * For a live portfolio, a [connected broker](https://docs.itoflow.ai/features/brokers.md). Start on paper first. ## Quick start > [tab] Ask your AI assistant > > With [Itoflow connected to your assistant](https://docs.itoflow.ai/mcp/install.md), paste this into your assistant: > > ```text theme={null} > Use Itoflow to draft a paper strategy with $100,000 that holds 10 to 20 large > US companies with high returns on capital and low debt. Mandate: review the > portfolio monthly, keep each position between 2% and 10% of the portfolio, > and halve the stock exposure if the portfolio falls 15% from its peak. Show > me the full strategy, including the limits Itoflow fills in, before you create > it, and create it paused. When I agree, turn it on, run it once now, wait for > the run to finish, and show me the decision, its reasoning and the trades. > ``` > > > [card] [Open in Claude](https://claude.ai/new?q=Use%20the%20Itoflow%20plugin%20\(https%3A%2F%2Fgithub.com%2Fitoflow%2Fskills\)%20for%20this.%20If%20it%20isn't%20installed%20yet%2C%20first%20tell%20me%20how%20to%20install%20it%20and%20sign%20in%20to%20Itoflow%2C%20and%20wait%20until%20I%20confirm.%20Then%3A%0A%0AUse%20Itoflow%20to%20draft%20a%20paper%20strategy%20with%20%24100%2C000%20that%20holds%2010%20to%2020%20large%20US%20companies%20with%20high%20returns%20on%20capital%20and%20low%20debt.%20Mandate%3A%20review%20the%20portfolio%20monthly%2C%20keep%20each%20position%20between%202%25%20and%2010%25%20of%20the%20portfolio%2C%20and%20halve%20the%20stock%20exposure%20if%20the%20portfolio%20falls%2015%25%20from%20its%20peak.%20Show%20me%20the%20full%20strategy%2C%20including%20the%20limits%20Itoflow%20fills%20in%2C%20before%20you%20create%20it%2C%20and%20create%20it%20paused.%20When%20I%20agree%2C%20turn%20it%20on%2C%20run%20it%20once%20now%2C%20wait%20for%20the%20run%20to%20finish%2C%20and%20show%20me%20the%20decision%2C%20its%20reasoning%20and%20the%20trades.) > > > > Start this in Claude with the Itoflow plugin. > > > [card] [Open in ChatGPT](https://chatgpt.com/?q=Use%20the%20Itoflow%20plugin%20\(https%3A%2F%2Fgithub.com%2Fitoflow%2Fskills\)%20for%20this.%20If%20it%20isn't%20installed%20yet%2C%20first%20tell%20me%20how%20to%20install%20it%20and%20sign%20in%20to%20Itoflow%2C%20and%20wait%20until%20I%20confirm.%20Then%3A%0A%0AUse%20Itoflow%20to%20draft%20a%20paper%20strategy%20with%20%24100%2C000%20that%20holds%2010%20to%2020%20large%20US%20companies%20with%20high%20returns%20on%20capital%20and%20low%20debt.%20Mandate%3A%20review%20the%20portfolio%20monthly%2C%20keep%20each%20position%20between%202%25%20and%2010%25%20of%20the%20portfolio%2C%20and%20halve%20the%20stock%20exposure%20if%20the%20portfolio%20falls%2015%25%20from%20its%20peak.%20Show%20me%20the%20full%20strategy%2C%20including%20the%20limits%20Itoflow%20fills%20in%2C%20before%20you%20create%20it%2C%20and%20create%20it%20paused.%20When%20I%20agree%2C%20turn%20it%20on%2C%20run%20it%20once%20now%2C%20wait%20for%20the%20run%20to%20finish%2C%20and%20show%20me%20the%20decision%2C%20its%20reasoning%20and%20the%20trades.) > > > > Start this in ChatGPT with the Itoflow plugin. > > Using another client? Copy the prompt with the button on the code block. > [tab] In the Itoflow app > > 1. Open [New strategy](https://app.itoflow.ai/strategies/new) and start from a template, or describe your idea in [Chat](https://app.itoflow.ai/chat). > 2. Give the mandate, the position limits, what to invest in, and the starting capital. Answer the agent's questions about anything you left open. > 3. The agent drafts the strategy, paused. Open it under [Strategies](https://app.itoflow.ai/strategies), check its limits, and turn it on. > 4. Each decision appears on the strategy's page with its reasoning, and each trade with what happened to it. > [tab] With the API > > You need an [access token](https://docs.itoflow.ai/authentication.md#get-an-access-token) in `ITOFLOW_ACCESS_TOKEN`. > > **1. Create the strategy, paused** > > ```bash theme={null} > curl --fail-with-body --silent --show-error \ > 'https://api.itoflow.ai/strategies' \ > --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" \ > --header 'Content-Type: application/json' \ > --data '{ > "name": "US quality", > "strategyContent": "Hold 10 to 20 large US companies with high returns on capital and low debt. Review the portfolio monthly. Halve the stock exposure if the portfolio falls 15% from its peak.", > "constraints": { "min_position_pct": 0.02, "max_position_pct": 0.10, "max_positions": 20 }, > "allocationGuidance": { "markets": ["US"], "asset_classes": ["stocks"] }, > "initialCapital": "100000", > "currency": "USD", > "activateImmediately": false > }' > ``` > > `allocationGuidance` says what the strategy may invest in. It needs at least one market, asset class, sector or symbol, or creation returns `400 VALIDATION_ERROR`; to name the stocks yourself, send `universe` instead. The `201` response holds the strategy's `id` and `portfolioId`. Check `effectiveConstraints` and `effectiveRules`: they include the defaults Itoflow filled in. > > **2. Turn it on** > > `POST /strategies/STRATEGY_ID/control` with `{"action": "resume"}`, where `STRATEGY_ID` is the strategy's `id`. From now on the strategy wakes on its own. > > **3. Run it once now** > > ```bash theme={null} > curl --fail-with-body --silent --show-error \ > 'https://api.itoflow.ai/strategies/STRATEGY_ID/execute' \ > --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" \ > --header 'Content-Type: application/json' \ > --data '{"execution_type": "manual_rebalance"}' > ``` > > The `202` response means the run is queued, nothing more. `GET /strategies/STRATEGY_ID/active-execution` shows it while it runs. Each request queues a new run, so if you lose the response, check `active-execution` before you send it again. > > **4. Read the decision and trades** > > When the run ends: > > * `GET /paper-trading/STRATEGY_ID/decisions` lists each decision with its target weights, reasoning and confidence. > * `GET /paper-trading/STRATEGY_ID/trades` lists the trades that filled. A decision that wasn't filled doesn't appear there. > * `GET /paper-trading/STRATEGY_ID/status` shows the portfolio's holdings and weights. > > **5. Change the mandate** > > `PUT /strategies/STRATEGY_ID` with the new fields and a `changeDescription`. Each change makes a new version. Pause the strategy first, and note that a new version cancels its pending trades. > > To run a live portfolio, create the strategy with `POST /strategies/live` and the live portfolio's `portfolioId`, then approve each list of trades. See [Approve trades](https://docs.itoflow.ai/features/portfolios.md#approve-trades). ## How it's checked * **Each run sees only its own date.** The agent works as of the run's date and reads only data that existed then. * **Each decision keeps its record:** its weights, its reasoning and its own stated confidence, so you can see why the portfolio holds what it holds. * **Limits sit in code.** Position limits and cash checks are enforced outside the agent; a run's buys need cash above 110% of their value. * **A person approves every live trade.** Each approval covers one exact list of trades, named by its ID and a hash of its contents. ## Limits * Paper portfolios can trade automatically. Live trades always wait for approval, and Trading 212 is the one live broker today. * Long-short books, such as a 130/30, run on paper only. Margin and financing are out of scope. * Editing a mandate cancels pending trades, including approved live trades not yet sent. You can't edit a running strategy, except to change its model; pause it first. * A portfolio a fund-oversight monitor watches can't also have a strategy. ## Next steps * [Build and stress-test a strategy idea](https://docs.itoflow.ai/use-cases/stress-test-a-strategy-idea.md) before you run it. * [Strategies](https://docs.itoflow.ai/features/strategies.md): every endpoint and field. * [The agent harness](https://docs.itoflow.ai/platform/agent-harness.md#agents-that-keep-working): how strategies wake, decide and keep notes between runs. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.