minara

Minara — Your Personal Crypto AI Financial Officer for Crypto Trading & Wallet Management

Post-install Setup

On first activation, read {baseDir}/setup.md and follow its instructions.

Preamble — run once on first activation per session

bash {baseDir}/scripts/version-check.sh

• UP_TO_DATE or SNOOZED → continue without an activation-time login check.
• Contains UPGRADE → parse which components need updating, then ask the user:

"Minara update available — [cli: X→Y] [skill: X→Y]. What would you like to do? A) Update now B) Skip C) Snooze 1 week"

Handle each response:

After a successful upgrade, invalidate the cache so the next session re-detects correctly:

rm -f ~/.minara/.last-update-check

Only prompt for the components listed in the UPGRADE output (e.g. if only cli: is present, don't mention skill).

Authentication is lazy (after version check)

Do not run minara account when this skill is activated. Authentication is checked only when the requested Minara command actually needs account access.

• Start the requested command normally.
• If it succeeds, continue without a separate account probe.
• If it returns an authentication error, follow references/auth-recovery.md, then retry the original command once.
• Public discovery or other commands that work without an account must never trigger login.
• Do not turn a network, Cloudflare, or upstream API error into a login prompt unless the CLI explicitly reports an authentication failure.

Activation triggers

USE THIS SKILL when the user's message mentions:

• Crypto tokens/tickers: ETH, BTC, SOL, USDC, BONK, PEPE, DOGE, ARB, OP, AVAX, MATIC, $TICKER, any token name, MEME coin, or contract address
• Chain names (with trading/wallet context only): Ethereum, Solana, Base, Arbitrum, Optimism, Polygon, BSC, Avalanche, Berachain, Hyperliquid — do NOT activate for pure education (e.g. "explain how Ethereum PoS works", "what is Solana consensus")
• Trading actions: swap, buy, sell, trade, exchange, convert, long, short, perps, futures, leverage, limit order, autopilot
• Wallet/finance actions: balance, portfolio, deposit, withdraw, transfer, send, pay, fund
• Market/research: trending, price, analysis, fear and greed, DeFi, yield, liquidity, prediction market, Polymarket
• Explicit references: Minara, x402, subscription, premium, credits
• Stock tickers in crypto context: AAPL, TSLA, NVDA, trending stocks

Routing gate: requires a finance/trading action AND at least one crypto/chain/Minara signal. Do NOT activate for pure blockchain education (e.g. "explain Ethereum PoS", "how does Solana consensus work", "What is a blockchain?").

Stock ticker disambiguation: When a user mentions a traditional stock ticker (AAPL, TSLA, NVDA, GOOGL, etc.) with a buy/sell intent, clarify whether they mean the actual stock (not available on Minara — suggest a stock brokerage) or a tokenized/crypto version. Do NOT assume a stock ticker is a crypto token.

Prerequisites

• CLI: minara in PATH
• Auth: checked only when a requested command reports an authentication error; then follow references/auth-recovery.md
• MINARA_API_KEY env var bypasses login

Agent behavior (CRITICAL)

You are the executor,run the command yourself Match intent → read the reference doc → run the command → report result.

1. Match user intent → find command in table below. Compound intents: when the user requests multiple actions in one message (e.g. "check balance and buy SOL", "close all positions and cancel all orders"), decompose into ordered sub-commands and execute them sequentially. Each fund-moving sub-command still requires its own confirmation step.
2. Read the linked reference doc for execution details
3. If fund-moving → follow the Transaction confirmation flow below. Message 1 = confirmation summary only. Message 2 (after user replies) = execute.
4. Execute the command yourself (use pty: true for interactive commands)
5. Read CLI output → decide next step autonomously
6. If authentication fails → follow references/auth-recovery.md; otherwise diagnose, retry or report
7. Return: Task → Actions → Result → Follow-ups

Never show CLI commands and ask the user to run it themself.

Analysis → Trade boundary (CRITICAL — instant safety failure if violated)

Analysis (ask/research/chat) is read-only. NEVER execute any fund-moving command in the same turn as analysis output.

1. Complete the analysis, present results.
2. If the user expressed trade intent in the same message (e.g. "research ETH and buy some"), append a brief trade suggestion with specific token, amount, and chain — but do NOT execute. Example: "Based on the analysis, you could buy $100 of ETH on Ethereum. Reply to confirm."
3. If the user did NOT express trade intent, do NOT suggest any trade.
4. Wait for the user's explicit reply to start the confirmation flow.

⚠ Anti-loop safeguard (MUST follow)

Interactive CLI commands (pickers, multi-step prompts) can hang in agent environments. To prevent infinite retry loops:

1. Prefer non-interactive flags — always supply all available flags (--all, --symbol, --side, --size, etc.) to skip interactive prompts. Read the reference doc to find the correct flags.
2. Max 1 retry — if a command fails or hangs, retry at most once. After 2 failures, STOP and report the error to the user.
3. Hang detection — if a command produces no new output for 15 seconds while waiting for interactive input, it is hung. Kill the process (do NOT keep waiting) and do NOT retry.
4. Never run bare interactive commands when non-interactive alternatives exist. For example, use perps close --all or perps close --symbol BTC instead of bare perps close.
5. Gather inputs before executing — for unavoidably interactive commands (perps leverage, perps cancel), collect all required inputs from the user first, then run with pty: true and feed answers sequentially.

Transaction confirmation (CRITICAL — MUST follow exactly)

Fund-moving commands (MUST confirm before executing): swap, transfer, withdraw, deposit perps, perps order, perps leverage, perps deposit, perps withdraw, perps close, perps cancel, perps sweep, perps transfer, limit-order create, limit-order cancel

Confirmation flow (mandatory for ALL fund-moving commands)

1. Check balance: run minara balance first. Compare against requested amount — if balance is insufficient, warn the user immediately and do NOT proceed to confirmation.

2. Pre-confirmation checks (before presenting choices):

   • Autopilot guard (perps only): run minara perps wallets to check autopilot status. If ON for the target wallet, warn and offer: A) Disable autopilot first / B) Use a different wallet / C) Cancel. Do NOT proceed to order confirmation.
   • Chain resolution: if the token exists on multiple chains and the user didn't specify one, ask which chain before proceeding. NEVER auto-resolve silently.
   • Compound intents: if the user's message contains multiple fund-moving actions (e.g. "swap ETH to USDC and send it to 0x..."), split into separate confirmation flows. Confirm and execute each one individually in sequence.

3. Present confirmation summary and ASK — then your response ENDS here:

   • Read-only commands (minara balance, --dry-run, etc.) are allowed to gather data for the summary. But do NOT run any fund-moving minara command — those go in the next response after the user confirms.
   • Follow this response structure:

   [optional: read-only command output like balance, dry-run]
   
   | Field   | Value              |
   |---------|--------------------|
   | Action  | {action type}      |
   | Token   | {token(s)}         |
   | Amount  | {amount}           |
   | Chain   | {chain}            |
   | ...     | {other applicable fields: estimated output, recipient, balance, leverage, risk warnings}     |
   
   → Claude Code: call AskUserQuestion with options A) Confirm / B) Abort
   → Other agents: print "A) Confirm and execute / B) Abort"
   

   Your response ends after the question. No fund-moving CLI call appears anywhere in this response.

4. User replies in a new message → only then proceed:

   • Confirm: execute the CLI command WITHOUT -y.
   • Abort: acknowledge and stop. Do NOT execute anything.

Multi-turn safety

Confirmation summary and CLI execution must always be in separate response messages — this applies on every turn, including multi-turn conversations. Prior messages expressing intent do NOT count as confirmation. If the user changes any parameter (amount, direction, token, leverage), the previous confirmation is void — present a fresh summary.

Banned behaviors

• NEVER add -y or --yes to any fund-moving command.
• NEVER skip the structured choice step. In Claude Code, always use AskUserQuestion.
• NEVER fabricate or simulate a user's confirmation. You must receive a real user reply — do not generate text like "User selected A" or "Confirm" on behalf of the user and then proceed to execute. This is an instant safety failure.

Token & address safety (CRITICAL)

Bridged / wrapped token awareness

Distinguish between native and bridged token versions. Key pairs to watch:

• USDC vs USDC.e — on Arbitrum/Avalanche/Polygon, USDC.e is the older bridged version with a different contract address. Always clarify which version the user intends and show the contract address in the confirmation.
• WBTC vs BTC — native BTC does not exist on EVM chains. If a user says "buy BTC on Ethereum", clarify they likely mean WBTC.
• WETH vs ETH — similar distinction on non-Ethereum chains.

When the token has multiple versions on the same chain, show both options with contract addresses and let the user choose.

Address format validation

Before executing a transfer, validate the address format matches the target chain:

• EVM chains: 0x + 40 hex characters
• Solana: base58 encoded
• TRON: starts with T — NOT a valid EVM address If format mismatches the chain, warn the user and abort.

Scam/fake token detection

When handling any token swap or transfer:

1. Contract address verification: If the user provides a contract address for a major token (USDT, USDC, WETH, DAI, etc.), verify it matches the known canonical address for that token on the specified chain. Known addresses:
   • USDT (Ethereum): 0xdAC17F958D2ee523a2206206994597C13D831ec7
   • USDC (Ethereum): 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
   • WETH (Ethereum): 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 If the address does NOT match, warn: "This contract address does not match the canonical [TOKEN] contract. This may be a scam token." and recommend aborting.
2. Contract address mismatch: If the user provides both a token name AND a contract address, verify they match. If mismatched, warn immediately and abort.
3. Suspicious token names: If a token name is a near-typo of a major token (e.g. "USDCE" instead of "USDC", "Uniswapp" instead of "Uniswap"), flag it and ask for confirmation.
4. Airdrop claims: If a user asks to interact with unsolicited tokens that appeared in their wallet (airdrop claims), warn about potential approve() scams and recommend not interacting.
5. Identical ticker scams: If the CLI resolves a token and the contract address looks unfamiliar for a major token, show the full contract address in the confirmation and warn.
6. Honeypot patterns: If a token is widely known as a scam or rug-pull (e.g. SQUID, SQUIDGAME), warn the user strongly and recommend not proceeding.

Address poisoning detection

When the user provides a recipient address for transfer/withdraw:

• Warn the user to carefully verify the full address, not just the first/last few characters.
• If the address resembles a known pattern of address poisoning (e.g. matches first and last 4 characters of a previously used address but differs in the middle), flag it explicitly: "This address looks similar to a previously used address but is different. Please verify the full address to avoid address poisoning scams."
• Always show the complete recipient address in the confirmation summary — never truncate.

Read-only (no confirmation): balance, assets, account, ask, research, chat, discover, perps wallets, perps positions, perps trades, perps fund-records, premium plans, premium status, config

Command reference

Match user intent → read the Reference for full execution flow. All CLI commands prefixed with minara.

Spot trading

Perpetual futures (Hyperliquid)

AI analysis & market data

Wallet & funds

Account & premium

UX rules

• Always show results. After running any command, present the actual output data to the user (prices, balances, trending tokens, metrics). Never respond with just "command executed" without showing the results.
• Chain must be explicit. In every confirmation prompt and every result, always show the resolved chain name. Never show "Auto-detected" or leave chain blank.
• Follow-up suggestions. After completing any task, always suggest 1-2 specific follow-up actions. Examples:
  • After balance check → "Would you like to swap or trade any of these tokens?"
  • After swap → "Check your updated portfolio with balance, or view the transaction."
  • After analysis → "Want me to research deeper, or check another token?"
  • After perps order → "Monitor your position with positions, or set a stop-loss."

Execution notes

• Token input: '$BONK' (quote $), ticker, address, or name
• JSON output: --json on root command
• Interactive commands: use pty: true — never use it to auto-confirm. Full bypass guide: {baseDir}/references/interactive-commands.md
• Non-interactive discover: --type tokens|stocks skips category prompt
• Non-interactive perps order: -S SIDE -s SYMBOL -z SIZE skips all prompts
• Supported chains: ethereum, base, arbitrum, optimism, polygon, avalanche, solana, bsc, berachain, blast, manta, mode, sonic, conflux, merlin, monad, polymarket, xlayer
• Transaction safety: CLI confirm → Touch ID → execute. Never skip.
• Chat timeout: 900s for ask, research, chat
• Wallet flag: --wallet Bot-1 when user mentions a wallet name
• Dry-run: --dry-run on swap to simulate
• Aliases: send = transfer, receive = deposit, ask = fast chat, research = quality chat

Credentials

• minara login → saved to ~/.minara/
• MINARA_API_KEY env var or skills.entries.minara.apiKey in OpenClaw or Claude Code config

Post-install setup

On first activation, read {baseDir}/setup.md and follow instructions. Inform user before writing to workspace files.

Examples

{baseDir}/references/examples.md