Your First Trade

This guide takes you from a freshly cloned repo to executing your first small trade through the agent. It hits every safety knob you should know about before moving real money and explains why each one exists.

If you want to skim: install → login → set hard caps → minara doctor → chat and trade. The rest of this page is why each step matters.

This is the terminal walkthrough. You drive every step from the interactive minara chat session (the REPL). Prefer a dashboard? Chat with the Agent runs the same first trade in the Web UI.

0. Prerequisites

Node.js ≥ 24.
A Minara account (login via device flow or API key).
One LLM provider configured (Anthropic API, Claude OAuth, OpenAI, or OpenRouter).
A small amount of funds you are willing to lose. The agent is designed to be safe, but any connected system can fail in unexpected ways. Treat your first trade like a fire drill rather than a production deploy.

See Installation for the clone-and-install step if you haven't done it yet.

1. Run the setup wizard

minara setup

The wizard detects which providers you have available, walks you through login for each, probes your existing ~/.minara/ directory for importable state, scaffolds the workspace (SOUL.md, AGENTS.md, USER.md), runs doctor, and prints a cheat sheet.

What the wizard actually does:

Creates ~/.minara/ (or $MINARA_DATA_DIR if set) with sandbox/files/, workspace/, logs/, and an empty minara.db.
Writes persisted settings (active model, gateway providers) to ~/.minara/env.
Stores encrypted auth profiles under ~/.minara/auth/.
Runs the full doctor check at the end so boot-time regressions surface immediately rather than on the first LLM call.

If you already have credentials in env vars, the wizard picks them up and skips the corresponding login step.

2. Verify configuration

minara doctor

Expected output has every check in green:

✓ data dir            /Users/you/.minara
✓ sqlite              minara.db  (WAL)
✓ llm provider        anthropic (api_key)
✓ minara auth         device flow
✓ tool registry       62 tools registered
✓ workspace           SOUL.md, AGENTS.md, USER.md
✓ env                 ANTHROPIC_API_KEY, MINARA_API_KEY set

Any yellow or red item is load-bearing. Do not proceed until doctor is clean. Common issues:

minara auth (not configured): run minara login minara and complete the device flow in your browser.
llm provider (no credentials): pick one from the wizard or export the env var directly.
tool registry (0 tools): usually means your env is missing a credential some factory depends on. Look at the missing-env warnings in the log.

3. Set hard caps before the first turn

This is the most important step on the page. The agent respects three hard-coded ceilings that are enforced by the permission tier hook chain regardless of what the LLM does:

# Per-transaction dollar cap. The agent cannot place a single
# trade larger than this.
minara config set safety.maxTransactionAmount 25

# Daily aggregate dollar cap. Atomic check-and-debit, so
# concurrent trades cannot exceed this by racing.
minara config set safety.dailySpendCap 100

# Blocklist. Add anything you absolutely do not want the agent
# to touch. The canonical-address layer already catches known
# scams, but this is the user-controlled layer.
minara config set safety.blockedTokens '["SAFEMARS","SQUID"]'

For a first trade, pick caps that make a mistake recoverable. $25 per tx and $100 per day means the worst plausible outcome is losing $100, which you can treat as tuition.

Verify the values stuck:

minara config list

See Finance Safety Stack for every knob the safety layer exposes.

4. Enable the emergency stop workflow

Keep /kill one keystroke away throughout the session. It sets a flag the BeforeToolCallHook chain checks on every single tool call, so activating it halts every tier-2-plus operation immediately.

Nothing to do for this step other than remember the command exists. Practice using it on the first turn:

> /kill
✓ emergency stop ACTIVE — all tier 2+ tools blocked
> /unkill
✓ emergency stop cleared

5. Drop into the REPL

minara

You'll see the identity banner, the cheat sheet, and a blinking prompt. Start with a read-only question to confirm the agent is behaving:

> what's BTC trading at?

The agent should activate the market.spot skill, call get_price, and return a number. Check the tool call in the log with /logs 20 if you want to see the full chain.

Try a few more read-only queries to build confidence:

> show my portfolio
> trending tokens on solana
> what's my daily spend so far

All of these stay in tier 1 and never move money.

6. Stage a small swap

Now ask for the smallest possible trade that matches your configured cap. For a $25 per-tx cap:

> swap $10 of USDC into ETH on base

Expected flow:

The agent activates the market.spot skill via activate_skills.
It calls token_safety_check to resolve USDC and ETH on Base to canonical addresses.
It calls position_sizer which computes a size of $10 and returns clipped: false (under the cap).
It calls exposure_limit_check against your current portfolio.
It calls a simulation of the swap to get the estimated output and price impact.
It presents the simulation to you along with the price impact and asks for confirmation.
Only after you type yes does it call the actual swap tool.

The confirmation step is real. Each tier-3 tool with requires_user_confirmation is blocked at the L3 risk gate until you confirm. You should see the pending confirmation block in the system prompt on the next turn:

<pending_confirmation>
  skill: market.spot
  action: swap
  summary: "$10 USDC → ETH on base, est output 0.0028 ETH, price impact 0.3%"
</pending_confirmation>

If the price impact exceeds the slippage threshold for small trades (default 2%), the swap is rejected before you even confirm. This is slippage protection doing its job.

7. Confirm and watch the audit log

Say yes. The agent executes the swap and reports back with the Minara transaction id. Immediately pull the audit rows for this turn:

sqlite3 ~/.minara/minara.db \
  "SELECT tool_name, blocked, substr(result_json, 1, 80)
     FROM audit
    WHERE session_id = (SELECT session_id FROM sessions ORDER BY created_at DESC LIMIT 1)
    ORDER BY created_at DESC LIMIT 20;"

You should see a clean chain of tool calls ending in the swap row with blocked = 0. Each prior call is a check that ran before the swap: token safety, sizing, exposure, slippage simulation.

This is the paper trail you'll use every time you investigate unexpected behavior. If something goes wrong on a future turn, this query is the first thing you run.

8. Review and iterate

A few follow-ups to try once the first swap is in:

/status: Emergency stop state, today's spend, number of tools registered, active skill session. Becomes your at-a- glance dashboard.
/budget: LLM spend for today, broken out by task. Useful for understanding what a single session actually costs.
/prompt: Dumps the current system prompt blocks. Look at the cacheable-vs-dynamic boundary and the active skill fragments. Useful for understanding what the LLM sees.
/history 20: Last 20 history entries with role and content preview.
/compress: Run this if the session gets long. It summarizes older turns via Haiku and keeps the prompt cheap.

What NOT to do on day one

Don't start autopilot. Autopilot adds an extra hop where the LLM makes decisions without a human in the loop. It's a fine tool once you trust the setup, but it is the wrong shape for "verifying the agent works."
Don't disable the emergency stop in a workflow. It's never the right answer.
Don't raise the daily cap above your pain threshold. The point of the cap is to bound the blast radius of mistakes. Set it based on "how much am I willing to lose to a bug," not "how much I think today's trades will total."
Don't share your audit log publicly. The redactor masks known sensitive keys, but trade history plus timestamps can be enough to deanonymize some patterns. Treat it as private operational data.
Don't skip doctor after upgrades. Schema migrations are idempotent, but a version with a new tool set or env var can trip up an old config. minara doctor catches these in seconds.

Next steps

Read Finance Safety Stack to understand the 6-stage safety path that every trade goes through.
Read Sandbox & Permissions to understand the hook chain behavior.
Read Observability to learn the audit queries that matter.
When you're ready for automation, read Workflows and Autopilot.
Prefer a dashboard over the terminal? Chat with the Agent walks the same flow in the Web UI.

Your first trade should feel boring. That's the point. If it felt exciting, the safety layer has a bug and we want to hear about it.

On this page