minters 0.4.5

money maketh man.

minters

money maketh man

minters is the packaged, local-first Mint distribution. It gives you the Seal terminal UI, a writable Mint workspace on your machine, the contract runner, the harness, the farm server, and the same repository structure the regulator expects when it reads, edits, validates, and runs contracts.

This README is written as a cookbook. Start at the quick start, then jump to the recipe that matches what you want to do.

quick start

Install or upgrade the package:

pip install --upgrade minters

Before you send your first prompt, make sure your local workspace or shell has a NINETH_API_KEY available. Seal uses Nineth for model requests, and without that key the UI can start but requests cannot run.

Example:

export NINETH_API_KEY=your_api_key_here
minters run

Launch the Seal UI:

minters run

On first launch, minters creates or reuses a writable Mint workspace, seeds it with the packaged project tree, and starts the interface defined in regulator/seal.py.

The packaged install is intentionally lean. It brings in the core dependencies needed for Seal and the local regulator runtime. Broker-specific tools stay optional and can be installed only when you need them.

recipe 1: choose where your workspace lives

By default, minters run resolves the workspace in this order:

1. --workspace /path/to/mint
2. MINTERS_WORKSPACE or MINT_WORKSPACE
3. the current directory if it already looks like a Mint workspace
4. ~/.local/share/minters/workspace

Use an explicit workspace when you want full control over where the model reads and writes files:

minters run --workspace ~/trading/mint

Ask minters which workspace it will use:

minters workspace

Or resolve a specific target without launching the UI:

minters workspace --workspace ~/trading/mint

If you want the model to operate on an existing checkout of this repository, open a shell in that checkout and run:

cd /path/to/mint
minters run

That keeps file edits, contracts, .env, and generated artifacts inside that same filesystem tree.

recipe 2: launch Seal with a specific model

Override the default regulator model for a single session:

minters run --model 1984-m3-0421

Or make it your default for all sessions:

export REGULATOR_MODEL=1984-m3-0421
minters run

recipe 3: understand what gets created on first launch

The first bootstrap copies the packaged Mint runtime into your workspace, including:

• contracts/ for strategy files
• harness/ for the contract runner and broker-facing APIs
• farm/ for the local MT5 Farm server
• regulator/ for the Seal UI and local service logic

That means the model can inspect, create, modify, validate, and run contracts against the same workspace tree a human sees.

Your seeded workspace also gets a slim requirements.txt with the core runtime dependencies used by the packaged app. Install broker- or farm-specific extras only when your workflow needs them.

recipe 4: use the Seal interface day to day

Once Seal is open, type tasks directly into the prompt area and submit with Enter, Ctrl+Enter, or Ctrl+S.

Useful built-in examples:

Example 1: contract review and iteration

inspect the contracts folder and summarize the strategies
fix the gold contract and iterate until it runs healthy
grep the repo for all uses of regulator and explain the flow
write a new contract in contracts/demo/contract.py and validate it

Example 2: broker API exploration

hello, please can you do a thorough research on the current state of the world as regards the finance and then do some research on gold to find key important details about the asset.. then develop a dependency tree of all the nodes in the gold supply chain.. write the result of your research in a about.md file which you'll create in the `contracts/gold/` subdirectory... then the dependency graph should be a json and you should include it in the same path but with a name ` dep.json`.

Useful local commands inside Seal:

/help
/clear
/model 1984-m3-0421
/telemetry
/handoff contracts/con-05-13-26/contract.py RiskAdjustedCapitalContract
/handoff-live contracts/con-05-13-26/contract.py RiskAdjustedCapitalContract
/stop-run RUN_ID

These slash commands are entered inside the Seal interface prompt bar. They are not shell commands.

Command	What it does	When to use it
/help	Shows the available Seal slash commands and their expected arguments.	Use it when you need a quick command reminder.
/clear	Clears the visible Seal conversation feed.	Use it when you want a clean screen without restarting Seal.
/model MODEL_NAME	Switches the active model for the current Seal session.	Use it when you want to change models without relaunching the app.
/telemetry	Lists recent managed remote runs and their latest status.	Use it after a handoff when you want the current run summary.
/telemetry RUN_ID	Shows telemetry for one specific managed run.	Use it when you want the detailed trace for a known run id.
/handoff PATH CLASS	Starts a remote managed run for a contract without forwarding your local broker env.	Use it when the remote Modal runtime already has the secrets and contract env it needs.
/handoff-live PATH CLASS	Starts a remote managed run and forwards the allowlisted local broker env and contract knobs.	Use it when your local workspace .env is the source of truth for the live settings.
/stop-run RUN_ID	Stops a managed remote run by id.	Use it when a remote contract should be terminated early.

The feed shows:

• your prompt block
• tool calls such as reads, searches, file edits, and contract runs
• success or failure observations for each local service action
• the final model response

recipe 5: create a contract manually

Every runnable contract is just a Python file under contracts/ with a class whose name ends in Contract and an async def run(self) method.

Example:

import asyncio


class DemoContract:
    async def run(self) -> None:
        while True:
            print("demo heartbeat")
            await asyncio.sleep(5)

Save that as contracts/demo/contract.py, then ask Seal to validate or run it, or run it yourself from the workspace.

recipe 6: run contracts from the workspace shell

From inside your Mint workspace, you can run a single contract file directly:

python contracts/demo/contract.py

Or run the contract discovery loop that continuously scans contracts/ and restarts workers when files change:

python -m harness.bundler

The bundler injects MINT_WORKSPACE and MINT_BUNDLER, and the runner loads your workspace .env before importing contract code.

That matters for autonomous contracts such as contracts/con-05-13-26/contract.py: when they see MINT_BUNDLER=1, they can stay in a guarded loop instead of doing a single research pass and exiting.

recipe 7: use the default local farm backend

The default operating mode is the local farm-backed flow.

Start the Farm server from the workspace:

python -m farm.main

Expected endpoints:

• API: http://localhost:8000
• Controller: tcp://127.0.0.1:8888

Quick status check:

curl http://localhost:8000/farm/status

Use this mode when your machine is hosting or controlling MT5 instances locally.

recipe 8: switch to MetaAPI or farm_ext

Use the MetaAPI-backed external mode when you want cloud account access instead of the local farm:

export BROKER_MODE=farm_ext
export METAAPI_TOKEN=your_metaapi_token
export METAAPI_ACCOUNT_ID=your_metaapi_account_id

Then launch Seal or run your contracts as usual.

If you want Mint to choose automatically, use:

export BROKER_MODE=auto

recipe 9: switch to Capital.com

Enable the Capital backend:

export BROKER_MODE=capital

Or:

export CAPITAL_ENABLED=true

Set credentials in your workspace .env or shell:

CAPITAL_API_KEY=your_api_key_here
CAPITAL_IDENTIFIER=[e-mail]
CAPITAL_PASSWORD=your_password
CAPITAL_DEMO=true

If you need the Rust bridge locally, build it from the workspace:

cd harness/capital
maturin develop

Then start Seal again and let the model work against the Capital-enabled workspace.

recipe 10: hand off an autonomous contract to Modal

Deploy the current API entrypoint first:

modal deploy entry.py

If harness/capital/target/wheels already contains a built Capital wheel, the deploy reuses it. Otherwise the Modal image builds the Capital extension from the checked-in Rust source during image build, so CI does not need a prebuilt local target/ artifact.

The deployed API keeps managed contract state under the named Modal volume minter-state, mounted at /data/minter, so remote runs can be resumed after container restarts.

Point Seal and the model at that deployment:

export MINTERS_REMOTE_URL=https://your-modal-endpoint.modal.run

Once the contract has been written and tested locally, hand it off from inside the Seal interface. The shell is used to deploy entry.py and export MINTERS_REMOTE_URL; the /handoff and /handoff-live commands are typed into Seal itself.

Useful Seal commands for the remote runtime:

/handoff contracts/con-05-13-26/contract.py RiskAdjustedCapitalContract
/handoff-live contracts/con-05-13-26/contract.py RiskAdjustedCapitalContract
/telemetry
/telemetry RUN_ID
/stop-run RUN_ID

The con-05-13-26 contract now supports a guarded autonomous loop. The most important knobs are:

• CON051326_AUTONOMOUS=true to keep the contract cycling
• CON051326_ENABLE_LIVE=true to allow real order submission
• CON051326_CONFIRM_BARS=3 for multi-bar confirmation
• CON051326_MIN_PAIR_SCORE=3.0 to require a stronger selected pair
• CON051326_MIN_CONFIDENCE=0.60 to require stronger model conviction
• CON051326_MAX_DAILY_LOSS_PCT=0.02 to stop live trading after a daily drawdown breach
• CON051326_STOP_ON_DAILY_LOSS=true to exit the loop when the daily loss guard trips
• CON051326_FORWARD_BROKER_ENV=true to let contract-driven self-handoff forward the allowlisted Capital credentials into the remote worker
• CON051326_REMOTE_ENV_KEYS=... to tune exactly which broker-related variables may be forwarded during self-handoff or /handoff-live

Use /handoff when the deployed remote runtime already has the credentials and contract env it needs.

Use /handoff-live when your local workspace .env is the source of truth for the live Capital credentials or the current CON051326_* runtime knobs. That command forwards the local CON051326_* settings, forces CON051326_REMOTE_HANDOFF=0 in the remote worker to prevent nested handoffs, and forwards only the broker env names in the allowlist.

The runtime exposes these over the API as:

• GET /terminal/contracts/runs
• GET /terminal/contracts/runs/{run_id}
• POST /terminal/contracts/handoff
• DELETE /terminal/contracts/runs/{run_id}
• GET /terminal/telemetry?run_id=...

The regulator model can use the same remote surfaces through the local services remote_contract_runs, remote_contract_run, remote_contract_handoff, remote_contract_stop, and remote_contract_telemetry.

deep dive: full contract design lifecycle

This section is intentionally pedantic. It describes the full working loop from the first line of a new strategy to a managed remote handoff that you can observe and stop safely.

1. Decide the contract boundary before you write code

Every runnable strategy in Mint is a file under contracts/ containing a class whose name ends with Contract and exposes async def run(self).

The smallest valid shape is:

import asyncio


class ExampleContract:
    async def run(self) -> None:
        print("hello from mint")


if __name__ == "__main__":
    asyncio.run(ExampleContract().run())

Choose the contract directory first. A practical layout looks like this:

contracts/my_strategy/
  contract.py
  about.md
  policy.md
  report.md
  bench/
    test_contract.py

Use about.md for research and market context, policy.md for guardrails and execution rules, report.md for generated findings, and bench/ for contract-specific tests or replay fixtures. The runtime only requires contract.py, but the extra files are what keep a trading strategy understandable after the first draft.

2. Pick the backend explicitly

When you already know the target broker, prefer the explicit engine handles:

from harness import capital
from harness import farm
from harness import farm_ext

This avoids ambiguity about which backend a contract is written for. capital is the clearest path for Capital.com workflows. farm is for the self-hosted MT5 controller. farm_ext is for MetaAPI-backed MT5.

If the contract must switch brokers by environment, use the generic root-level dispatcher helpers instead, but do that on purpose. Do not accidentally mix broker-specific assumptions with the generic dispatcher surface.

3. Define the env contract as part of the strategy design

Before adding trading logic, decide which knobs must be adjustable without editing code. In practice that means environment variables.

For example, the con-05-13-26 contract uses knobs such as:

• CON051326_AUTONOMOUS
• CON051326_ENABLE_LIVE
• CON051326_CONFIRM_BARS
• CON051326_MIN_PAIR_SCORE
• CON051326_MIN_CONFIDENCE
• CON051326_MAX_DAILY_LOSS_PCT
• CON051326_STOP_ON_DAILY_LOSS

Design these variables early and keep the naming consistent. A good pattern is one stable prefix per contract. That gives you three benefits:

1. You can tune behavior from .env without patching the strategy.
2. You can forward a small, intentional set of values during remote handoff.
3. You can understand the live runtime state by reading the env contract, not reverse-engineering the code.

4. Separate research, selection, guards, and execution

The most maintainable Mint contracts do not mix every decision into one block. Treat the strategy as four stages:

1. Research: gather candles, macro context, watchlists, sentiment, or market metadata.
2. Selection: rank assets, pairs, or setups and decide which candidate is best.
3. Guards: apply risk checks, exposure checks, schedule checks, and kill-switch conditions.
4. Execution: place, modify, or skip orders based on the previous stages.

That separation matters because the same contract may run in three different modes:

1. research-only
2. paper-guarded but not live
3. live execution enabled

If research and execution are tightly coupled, it becomes much harder to run safe dry runs locally or remotely.

5. Emit artifacts and telemetry deliberately

Do not rely on stdout alone. A contract should leave behind artifacts that explain what it decided.

Good outputs include:

• a latest run artifact such as latest_contract_run.json
• state files for autonomous loops
• cached research inputs such as macro snapshots
• structured telemetry with a run_id when running under the managed runtime

This is what lets you answer questions later like "why was no trade submitted?" or "which guard blocked the order?" without rerunning the strategy under a debugger.

6. Run the contract directly first

Before you hand a strategy to the bundler or to Modal, run it in the narrowest possible way:

python harness/_runner.py contracts/my_strategy/contract.py MyStrategyContract

That path matters because harness/_runner.py is the real contract entry surface used by the managed runtime. It adds the workspace root to sys.path, loads the workspace .env, imports the target file, looks up the class name, and executes asyncio.run(cls().run()).

If the contract cannot survive the runner, it is not ready for bundler discovery or remote handoff.

7. Add tests at two levels

A complete strategy usually needs both root-level tests and contract-local tests.

Root-level testsuite/ tests are for integration points such as:

• router behavior
• remote runtime registration
• env forwarding
• bundler restart and handoff control
• model-visible local services

Contract-local bench/ tests are for strategy behavior such as:

• scoring logic
• risk guards
• portfolio selection
• macro overlays
• replaying canned price histories

Use the lightest command that proves the slice you changed:

pytest testsuite/test_my_feature.py -q
pytest contracts/my_strategy/bench/test_contract.py -q

If the contract has autonomous behavior, add tests for both the single-pass path and the loop path. That distinction is where a lot of trading regressions hide.

8. Exercise local deployment before remote deployment

In Mint, "local deployment" usually means one of two things:

1. running the contract directly through harness/_runner.py
2. letting the bundler discover and supervise it

To run the whole contract set together:

python -m harness.bundler

The bundler scans contracts/, launches matching contract classes through the runner, and keeps rescanning for changes. This is the correct environment for contracts that are supposed to stay alive, emit telemetry repeatedly, or react to file changes during iteration.

If your strategy depends on the farm backend, start the local farm service as part of local deployment:

python -m farm.main

If your strategy depends on Capital, make sure the bridge imports locally and the Capital credentials are present in .env or the shell.

9. Package or deploy the runtime only after the contract is stable locally

The remote runtime is not a substitute for local validation. Use remote handoff after these are already true:

1. the contract imports cleanly
2. the runner path works
3. the narrow tests pass
4. the contract writes sensible artifacts locally
5. you know which env vars must exist remotely

When you are ready, deploy the API:

modal deploy entry.py

Then point the local workspace at the deployed runtime:

export MINTERS_REMOTE_URL=https://your-modal-endpoint.modal.run

10. Choose the right handoff path

There are now three distinct handoff patterns in this repository.

Pattern 1: plain manual handoff

/handoff contracts/my_strategy/contract.py MyStrategyContract

Use this when the remote runtime already has the required credentials and runtime knobs.

Pattern 2: live manual handoff with local env forwarding

/handoff-live contracts/con-05-13-26/contract.py RiskAdjustedCapitalContract

Use this when your local workspace .env is the authoritative source for the live Capital credentials or for the current CON051326_* runtime settings. This command forwards the current local CON051326_* values, excludes path-specific state keys that should not be copied blindly, forces CON051326_REMOTE_HANDOFF=0 in the remote worker so it will not recurse into another handoff, and forwards only the allowlisted broker variables.

Pattern 3: contract-driven self-handoff

Set the contract knobs in .env, including:

CON051326_REMOTE_HANDOFF=1
CON051326_FORWARD_BROKER_ENV=1
CON051326_REMOTE_ENV_KEYS=CAPITAL_API_KEY,CAPITAL_IDENTIFIER,CAPITAL_PASSWORD,CAPITAL_DEMO,CAPITAL_BASE_URL,CAPITAL_DEMO_URL

Use this when the contract itself decides to move into the remote runtime. The contract will forward the allowlisted broker vars automatically when CON051326_FORWARD_BROKER_ENV=1.

11. Observe the remote run instead of guessing

After handoff, always inspect the managed run and the telemetry.

Inside Seal:

/telemetry
/telemetry RUN_ID
/stop-run RUN_ID

Over HTTP:

GET /terminal/contracts/runs
GET /terminal/contracts/runs/{run_id}
GET /terminal/telemetry?run_id=...
DELETE /terminal/contracts/runs/{run_id}

The remote run record tells you the current status, the latest structured payload, and whether the process failed, completed, or is still running. The telemetry stream tells you why.

12. Iterate by changing the smallest surface that explains the failure

A disciplined Mint workflow looks like this:

1. inspect the latest artifact or telemetry
2. identify the exact failing surface
3. patch the smallest responsible code path
4. rerun the narrowest test or runner command
5. only then promote the change back through the bundler or the remote runtime

Do not use the remote runtime as the first place you discover basic import, env, or guard logic errors. Use it after the local lifecycle is healthy.

recipe 11: keep secrets local

minters does not need your broker credentials baked into the package. Keep them in one of these places on your own machine:

1. a workspace-local .env
2. exported shell environment variables
3. platform-specific secret storage used by your local runtime

Typical knobs you may set locally include:

• NINETH_API_KEY
• BROKER_MODE
• METAAPI_TOKEN
• METAAPI_ACCOUNT_ID
• CAPITAL_API_KEY
• CAPITAL_IDENTIFIER
• CAPITAL_PASSWORD
• CAPITAL_DEMO
• REGULATOR_MODEL
• MINTERS_REMOTE_URL

recipe 12: upgrade minters safely

To get the latest package version:

pip install --upgrade minters

Your existing workspace is not wiped. minters only seeds files that are missing, so your contracts, edits, and .env stay local.

recipe 13: build and test the package locally

From the repository root:

python -m pytest testsuite/test_workspace.py -q
python -m pytest testsuite/test_bundler.py testsuite/test_runtime_control.py testsuite/test_router_managed_contracts.py testsuite/test_regulator_remote_services.py testsuite/test_con_05_13_26_autonomy.py -q
python -m pytest contracts/con-05-13-26/bench/test_contract.py -q
python -m build

Install the built wheel locally for a smoke test:

python -m pip install --force-reinstall --no-deps dist/minters-0.2.11-py3-none-any.whl
minters workspace --workspace /tmp/minters-smoke

recipe 14: troubleshoot the common cases

If Seal opens but edits land in the wrong place:

minters workspace

Then relaunch with an explicit path:

minters run --workspace /path/to/your/mint

If a contract cannot import the runtime, make sure you are running inside a real Mint workspace that contains harness/, contracts/, and regulator/.

If Seal starts but every prompt fails immediately, check the model credentials first:

echo "$NINETH_API_KEY"

If that is empty, add NINETH_API_KEY to your workspace .env or export it before launching minters run.

If you see a client-library compatibility error mentioning default_service, upgrade the runtime package or the Nineth client:

pip install --upgrade minters 'nineth>=0.5.16'

If Capital mode fails with an import error for the Rust bridge, rebuild it:

cd harness/capital
maturin develop

If /telemetry or /handoff fails inside Seal, verify the remote runtime endpoint first:

echo "$MINTERS_REMOTE_URL"
curl "$MINTERS_REMOTE_URL/terminal/contracts/runs"

If a remote handoff succeeds but you do not see trades, inspect the guard state from telemetry. The autonomous contract blocks live submission when pair-score, confidence, macro alignment, multi-bar confirmation, or daily loss thresholds are not satisfied.

If farm mode is selected but no local server is reachable, start the farm process first:

python -m farm.main

If you want the model to work on this repository itself instead of a seeded copy, launch minters run from the repository root or set MINTERS_WORKSPACE to that path before starting Seal.