Agent Integration

Overview

AgentsWallets is designed for non-interactive, machine-driven workflows. When running inside an AI agent (non-TTY), the CLI automatically switches to JSON output mode and disables interactive prompts.

Environment variables

JSON envelope

All JSON responses follow a consistent envelope and are written to stdout — both success and failure. This lets agents read a single stream.

Success

{
  "ok": true,
  "data": { "id": "2b9123ea-...", "name": "bot", "address": "0x..." },
  "error": null,
  "meta": { "request_id": "req_abc" }
}

Failure

{
  "ok": false,
  "data": null,
  "error": {
    "code": "ERR_INSUFFICIENT_FUNDS",
    "message": "Need 10 USDC, have 2.3",
    "details": { "required": "10", "available": "2.3", "token": "USDC" },
    "recovery_hint": "Top up wallet. Check balance with `aw wallet balance <name>`."
  },
  "meta": { "request_id": "req_abc" }
}

• Both success and failure JSON are written to stdout
• Each response is a single line of JSON

Exit codes

Non-TTY auto-detection

When the CLI detects a non-TTY environment (piped output, subprocess), it automatically:

• Switches to JSON output mode
• Disables interactive prompts
• Suppresses third-party noise on stderr

You can override this with --output human to force human-readable output.

Wallet identifiers

Wallets can be referenced by name or EVM address in any command that accepts a --wallet flag:

aw wallet balance bot                                        # by name
aw wallet balance 0x4f3A...6a1                               # by EVM address

Note: Solana addresses cannot be used as wallet identifiers. Use the wallet name or EVM address instead.

Idempotency keys

Write operations (aw send, aw predict buy, aw predict sell, aw swap exec, aw bridge exec, aw perp open, aw perp close, aw perp cancel) support an optional --idempotency-key flag. This prevents duplicate transactions if your agent retries a command:

aw send --wallet bot --to 0x... --amount 10 --token USDC --idempotency-key transfer-001

If the same idempotency key is submitted twice, the CLI returns the original result without executing a second transaction. Keys are scoped per wallet and persisted in the local database.

When omitted, a random UUID is generated automatically.

Session management

The CLI uses time-limited sessions to protect write operations:

1. aw unlock creates a session token (default: 15 minutes)
2. The token is stored locally and verified on each write operation
3. Token comparison uses constant-time comparison (SHA-256 hash)
4. Each successful command automatically renews the session (sliding window), so active agents don't need to re-unlock
5. After expiry (no activity for the TTL duration), the agent must call aw unlock again

For continuous agent operation, check exit code 3 (authentication error) and re-run aw unlock before retrying the failed command.

Password priority

The CLI resolves the master password in this order:

1. AW_MASTER_PASSWORD environment variable
2. AW_MASTER_PASSWORD_ENV (indirect env var reference)
3. OS keychain (macOS Keychain, Linux secret-tool, Windows DPAPI)
4. Interactive prompt (TTY only)

For agent workflows, use AW_MASTER_PASSWORD or save the password to the OS keychain with aw keychain save.

Recovery hints

Every error response includes a recovery_hint field with an actionable message. Agents can use this to self-recover:

result = run("aw send --wallet bot --json")
if result.exit_code == 3:
    # Session expired — re-unlock and retry
    run(f"AW_MASTER_PASSWORD='{pw}' aw unlock --json")
    result = run("aw send --wallet bot --json")
elif result.exit_code != 0:
    error = json.loads(result.stdout)
    hint = error["error"]["recovery_hint"]
    # Use hint for self-recovery or report to operator

Dry runs

Use --dry-run to validate a transaction without broadcasting:

aw send --wallet bot --to 0x... --amount 10 --token USDC --dry-run --json

The CLI evaluates all policy rules and returns what would happen, without submitting the transaction on-chain.