aibtc - Bitcoin & Stacks Blockchain Tools

Use the commands EXACTLY as shown below. Do not omit the --config flag - wallet state won't persist without it.

IMPORTANT: Daemon Mode for Wallet Persistence

The mcporter daemon MUST be running for wallet_unlock to persist between calls.

Before any transaction, ensure the daemon is started:

/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json daemon start

Check daemon status:

/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json daemon status

NEVER use CLIENT_MNEMONIC or environment variable mnemonics. Always use wallet_unlock with the daemon.

AUTONOMOUS SECURITY MODEL

This agent operates autonomously within configured limits. Security comes from spending caps and operation tiers, not from asking permission on every transaction.

Core Principles

1. •NEVER store, log, or echo the wallet password - Read it from file, use it, forget it
2. •NEVER use CLIENT_MNEMONIC or mnemonic environment variables - Always use wallet_unlock
3. •Unlock once per session, lock when done - Not per-transaction
4. •Respect spending limits - Track daily spending in state.json, stop when limit reached
5. •Never auto-execute Tier 3 operations - Some operations always require human presence
6. •Log every transaction - Amount, recipient, txid, tier, timestamp in journal.md

Operation Tiers

Every wallet operation is classified into one of four tiers:

Tier 0: Always Allowed (No Unlock Needed)

Safe read-only operations. Available to ALL users (including public).

Tier 1: Auto-Approved Within Limits

The agent executes these autonomously as long as:

• •The per-transaction amount is within the per-tx limit (default: $5 equivalent)
• •The daily cumulative spend has not exceeded the daily limit (from state.json authorization.dailyAutoLimit)
• •The wallet is unlocked for the current session

No password prompt. No confirmation prompt. Just execute, log, and report.

Before executing a Tier 1 operation:

1. •Check state.json for authorization.todaySpent vs authorization.dailyAutoLimit
2. •If adding this transaction would exceed the daily limit, escalate to Tier 2 (ask human to confirm)
3. •After execution, update state.json counters: increment todaySpent, totalTransactions, transactionsToday, lifetimeAutoTransactions
4. •Log the transaction in journal.md

Tier 2: Requires Human Confirmation

The agent explains what it wants to do and asks the human to confirm (yes/no). No password is needed -- the wallet is already unlocked for the session. Use this tier when:

• •A Tier 1 operation exceeds the per-tx or daily limit
• •The operation carries meaningful financial risk
• •The operation is irreversible and high-value

Tier 2 flow:

1. •Tell the human: "I'd like to [action] [amount] to [recipient]. This exceeds auto-approve limits. Confirm? (yes/no)"
2. •Wait for explicit "yes" confirmation
3. •Execute the operation
4. •Update state.json counters (increment lifetimePasswordTransactions)
5. •Log in journal.md

Tier 3: Never Autonomous (Always Requires Human + Password)

These operations are irreversible, dangerous, or expose secrets. The agent MUST ask the human to provide the password directly for these operations, even if the wallet is already unlocked. The agent must re-verify identity.

Tier 3 flow:

1. •Tell the human: "This is a high-security operation. I need you to provide the wallet password directly."
2. •Wait for the human to provide the password
3. •Show full details and get explicit confirmation
4. •Execute the operation
5. •Log in journal.md (but NEVER log the password)

SESSION-BASED OPERATION FLOW

Session Start (Do This Once)

At the beginning of each operating session:

1. •

   Start the daemon:

   bash

   /usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json daemon start
   

2. •

   Read the wallet password from the secure file:

   bash

   WALLET_PASSWORD=$(cat /home/node/.openclaw/config/.wallet_password)
   

3. •

   Unlock the wallet for the session:

   bash

   /usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_unlock password=$WALLET_PASSWORD
   

4. •

   Reset daily counters if needed - Check if state.json authorization.lastResetDate is before today. If so, reset todaySpent to 0 and transactionsToday to 0, update lastResetDate.

5. •

   The wallet is now unlocked. Operate freely within your tier limits.

During Session

• •Execute Tier 0 operations freely for any user
• •Execute Tier 1 operations autonomously (check limits)
• •Escalate to Tier 2 when limits are exceeded
• •Always escalate to Tier 3 for dangerous operations
• •Track spending in state.json after every transaction

Session End

1. •

   Lock the wallet:

   bash

   /usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_lock
   

2. •

   Save final state to state.json

SPENDING LIMITS

Spending limits are configured in state.json under authorization:

{
  "authorization": {
    "dailyAutoLimit": 10.00,
    "todaySpent": 0.00,
    "lastResetDate": "2026-02-03",
    "trustLevel": "standard",
    "lifetimeAutoTransactions": 0,
    "lifetimePasswordTransactions": 0,
    "lastLimitIncrease": null
  }
}

Autonomy Presets

Limit Enforcement

1. •Before every Tier 1 operation, read state.json and check:
   • •todaySpent + transactionAmount <= dailyAutoLimit -- if false, escalate to Tier 2
2. •After every transaction (any tier), update:
   • •todaySpent += transactionAmount
   • •transactionsToday += 1
   • •totalTransactions += 1
   • •Increment lifetimeAutoTransactions (Tier 1) or lifetimePasswordTransactions (Tier 2/3)
3. •Daily reset: When lastResetDate < today, set todaySpent = 0, transactionsToday = 0, update lastResetDate

Read-Only Operations (Tier 0 - Available to EVERYONE)

These operations are safe, don't require wallet unlock, and can be used by any user:

# Check balances
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.get_btc_balance
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.get_stx_balance
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.sbtc_get_balance

# Get wallet info (addresses only, no sensitive data)
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.get_wallet_info

# Check fees
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.get_btc_fees
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.get_stx_fees

# Network status
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.get_network_status

# BNS lookups
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.lookup_bns_name name=example.btc

# DeFi info (read-only)
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.alex_list_pools
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.zest_list_assets
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.zest_get_position

# x402 endpoints list
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.list_x402_endpoints

Write Operations (Tier 1/2)

Tier 1 operations execute autonomously within limits. Tier 2 operations require human confirmation (but not password).

Transfers

# Transfer BTC (amount in satoshis) - TIER 2: always requires confirmation
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.transfer_btc recipient=bc1... amount=50000

# Transfer STX (amount in micro-STX) - TIER 1 if within limits, TIER 2 if over
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.transfer_stx recipient=SP... amount=1000000

# Transfer sBTC - TIER 1 if within limits, TIER 2 if over
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.sbtc_transfer recipient=SP... amount=100000

DeFi Operations

# ALEX swap - TIER 1 if within limits
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.alex_swap tokenX=STX tokenY=ALEX amount=1000000

# Zest supply - TIER 1 if within limits
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.zest_supply asset=sBTC amount=100000

# Zest borrow - TIER 2: always requires confirmation (creates debt)
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.zest_borrow asset=aeUSDC amount=1000000

Smart Contracts

# Call contract (write) - TIER 2: always requires confirmation
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.call_contract contractAddress=SP... contractName=contract functionName=do-something functionArgs='[]'

Wallet Management

# Check wallet status - TIER 0
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_status

# List wallets - TIER 0
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_list

# Unlock wallet (session start - read password from file) - SESSION FLOW
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_unlock password=$WALLET_PASSWORD

# Lock wallet (session end) - SESSION FLOW
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_lock

High-security wallet operations (TIER 3 - always requires human + password):

# Export wallet - TIER 3
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_export

# Delete wallet - TIER 3
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_delete name=wallet-name

# Create new wallet - TIER 3
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_create password=USER_PROVIDED_PASSWORD name=wallet-name

# Switch wallet - TIER 3
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_switch name=wallet-name

# Import wallet - TIER 3
/usr/local/bin/mcporter --config /home/node/.openclaw/config/mcporter.json call aibtc.wallet_import mnemonic=USER_PROVIDED_MNEMONIC password=USER_PROVIDED_PASSWORD

Unit Conversions

Example: Autonomous Operation

User: "Keep an eye on ALEX pools and swap 5 STX to ALEX if the rate looks good."

Agent (internal):

1. •Check ALEX pools (Tier 0 - no unlock needed)
2. •5 STX = 5,000,000 uSTX ~ $2.50 -> within Tier 1 daily limit
3. •Session wallet is already unlocked
4. •Execute swap autonomously
5. •Update state.json: todaySpent += 2.50, transactionsToday += 1
6. •Log to journal.md

Agent (to user):

"Found a good rate on ALEX/STX pool. Swapped 5 STX for 142.3 ALEX. TxID: abc123..." Daily spend: $2.50 / $10.00 limit.

Example: Limit Exceeded Escalation

Agent wants to execute a 20 STX transfer (~$10) but dailyAutoLimit is $10 and todaySpent is $3:

Agent (to user):

"I'd like to send 20 STX ($10.00) to SP1ABC... but this would put today's spend at $13.00, exceeding the $10.00 daily auto-limit. Please confirm this transaction. (yes/no)"

User: "yes"

Agent: Executes transfer, logs as Tier 2 (lifetimePasswordTransactions += 1).

Example: Tier 3 Operation

User: "Export my wallet"

Agent:

"Wallet export is a high-security operation that exposes your private key. I need you to provide your wallet password directly to proceed."

User: "mypassword123"

Agent: Executes export, shows result, logs operation (never logs password).