AI / Agent Usage

This page documents how autonomous agents should interact with bitpilot tools, including deterministic call order, failure handling, and test-only helpers.

Deterministic Call Order

For reliable agent workflows, follow this sequence:

1. get_balance — verify funds are available before proposing.
2. estimate_fee — get current fee rates to set fee_rate_sat_vb.
3. propose_payment — create a payment proposal. Check status in the response:
4. "approved" — policy auto-approved; a human can now approve via CLI.
5. "pending" — policy requires human approval (above threshold).
6. "rejected" — policy denied the transaction. Check policy_decision for reason.
7. list_proposals — confirm the proposal was recorded.
8. Report the proposal details to the user and wait for human action.

Agents must never attempt to approve or broadcast directly. The CLI bitpilot approve --proposal-id is the only broadcast path.

Error Codes (OpenAI / MCP)

Tool errors return structured JSON:

{
  "error": {
    "code": "WALLET_SYNC_ERROR",
    "message": "Backend unreachable after 15s",
    "details": {}
  }
}

Policy Interaction

Agents receive the policy decision in the propose_payment response. They should:

• On "approved": inform the user the proposal is ready for CLI approval.
• On "pending": inform the user approval is required and explain the threshold.
• On "rejected": explain the reason and suggest adjustments (lower amount, different address).

MCP Runtime Status

The MCP adapter exposes a get_runtime_status tool that returns:

• Backend readiness (can the wallet reach the network?)
• Sync availability
• Current network mode (testnet/mainnet/signet)

Call this first in MCP contexts to verify the environment before making wallet calls.

Test-Only Helpers

The bitpilot.testing module provides utilities for tests and examples only:

from bitpilot.testing import seed_mock_utxos

seed_mock_utxos(wallet)  # Seeds 850,000 sats of deterministic mock UTXOs

This function directly mutates wallet._utxos and must never be used in production code. It exists to avoid requiring testnet funds for unit tests and demos.

Non-Production Boundaries