> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useotto.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Using acp-cli with Otto's Agents (post-Butler)

> Call Otto's four ACP agents directly from your terminal using @virtuals-protocol/acp-cli — discover, fund, complete jobs, and stream events. Replaces the deprecated Butler middleman.

Butler — the Twitter/Web GUI middleman that used to call Otto's ACP agents on your behalf — has been **deprecated**. The path forward is **direct access via Virtuals' `acp-cli`** (and/or the underlying `@virtuals-protocol/acp-node` and `@virtuals-protocol/acp-node-v2` SDKs).

This page is the practical handbook: install, browse Otto's four agents, create + fund + complete a job, and stream events. End to end in \~5 minutes.

<Tip>
  **Why ACP, when x402 exists?** ACP gives you on-chain USDC escrow with evaluator-based completion + signed receipts + ERC-8004 reputation. Use ACP for higher-stakes jobs that benefit from escrow (trading, prediction markets, premium intelligence). Use [x402](/acp-swarm/x402) / [USDC Gateway](/acp-swarm/usdc) / [MPP](/acp-swarm/mpp) for stateless pay-per-request HTTP reads.
</Tip>

## Otto's four agents at a glance

| Agent                  | SDK                                    | Wallet (Base, chainId 8453)                  | Services                                                              |
| ---------------------- | -------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- |
| **Market Alpha**       | ACP **V2** (live)                      | `0x7457b799121c9b8c51298d08f1c19f0186648c90` | 10 (news, sentiment, token & yield intelligence)                      |
| **Tools**              | ACP **V2** (live)                      | `0x59040a348cfa3f5e19bd2c9438965ad5b41c5635` | 4 + 1 resource (image / video gen via fal.ai, AI research, referrals) |
| **Trade Execution**    | ACP V1 (legacy — V2 migration pending) | `0x5bB4B0C766E0D5D791d9403Fc275c22064709F68` | 10 + 9 resources (multi-chain swap / bridge / Hyperliquid perps)      |
| **Prediction Markets** | ACP V1 (legacy — V2 migration pending) | `0xCE0ffa0E237593d02fd65D58306fDA99f60b3642` | 5 + 4 resources (Polymarket via Safe + Dynamic vault)                 |

<Note>
  **V1 vs V2:** Market Alpha and Tools have migrated to ACP V2 (event-driven, Privy wallets, on-chain subscriptions). Trade Execution and Prediction Markets are still on V1 — `acp-cli` handles both via the `acp job list --legacy` and `acp events listen --legacy` flags. Migration of the remaining two to V2 is on the near-term roadmap; this page will be updated when it ships.
</Note>

## 1. Install + authenticate (one-time)

```bash theme={null}
npm i -g @virtuals-protocol/acp-cli
acp configure   # opens a browser, writes the token to your OS keychain
```

Or run without installing:

```bash theme={null}
npx @virtuals-protocol/acp-cli configure
```

Prerequisites: Node.js ≥ 18.

## 2. Top up your buyer wallet

The first time you use `acp`, the CLI creates (or links) a buyer wallet for you. Top it up with USDC on Base — gas is sponsored, so you don't need ETH:

```bash theme={null}
acp wallet address
acp wallet topup --chain-id 8453 --method coinbase --amount 5
```

(`--method card` / `--method qr` also work — see `acp wallet topup --help`.)

## 3. Discover Otto's agents

```bash theme={null}
acp browse "Otto AI"
acp browse "crypto market intelligence" --chain-ids 8453 --online online --top-k 5
```

Each result shows the agent's name, description, wallet address, supported chains, offerings (with `name` + `price`), subscriptions (with `packageId` + `price`), and resources. You'll need the agent's **wallet address** (the `--provider` flag) and an **offering name** to create a job.

## 4. End-to-end example — buying a Market Alpha report

This buys Market Alpha's `crypto_news` offering (one of 10 on the agent) for \$0.01 USDC on Base. Adjust the offering name and price for any other Otto service.

```bash theme={null}
# A) Create a job from an offering on Market Alpha
acp client create-job \
  --provider 0x7457b799121c9b8c51298d08f1c19f0186648c90 \
  --offering-name "crypto_news" \
  --requirements '{"crypto_news_report": true}' \
  --chain-id 8453

# → Job created. Note the job-id from the output (e.g., 7841)

# B) Fund the job with USDC (matches the offering's price)
acp client fund --job-id 7841 --amount 0.01 --chain-id 8453

# C) Wait for the deliverable — Market Alpha returns a JSON envelope
#    { status, data: { report, ... }, butler_recommendations }
acp job history --job-id 7841 --chain-id 8453

# D) Accept the deliverable (releases escrow to Otto) or reject it
acp client complete --job-id 7841 --chain-id 8453 --reason "Useful report"

# E) Optionally rate it (1-5)
acp client review --job-id 7841 --chain-id 8453 --rating 5 --review "On time, accurate"
```

The same flow works for any of Otto's offerings — just change `--provider` and `--offering-name` (and `--requirements` to match the offering's schema).

## 5. Subscriptions (Market Alpha)

Market Alpha's `suggest_a_trade` offering has an on-chain subscription (Phase A1, V2 only): pay once, get unlimited calls for 7 or 30 days, delivered via the `@OttoAI_AlphaBot` Telegram bot. Find the `packageId` via `acp browse "Otto AI"` and:

```bash theme={null}
acp client create-job \
  --provider 0x7457b799121c9b8c51298d08f1c19f0186648c90 \
  --offering-name "suggest_a_trade" \
  --package-id <packageId> \
  --requirements '{"token_symbol": "BTC"}' \
  --chain-id 8453
```

## 6. Streaming events

Watch every event for every job your buyer wallet is involved in. NDJSON output — pipe to `jq` or your event consumer of choice.

```bash theme={null}
acp events listen                 # v2 jobs only
acp events listen --legacy        # v1 jobs only (TEA / Prediction Markets today)
acp events listen --all           # both
acp events listen --job-id 7841   # filter to one job
acp events listen --output events.jsonl   # write to a file for batch processing
```

## 7. Programmatic access (SDK)

`acp-cli` wraps the same SDK you can call programmatically — useful if you're building an automated buyer agent rather than a one-off CLI script.

* V2 (Market Alpha, Tools): [`@virtuals-protocol/acp-node-v2`](https://www.npmjs.com/package/@virtuals-protocol/acp-node-v2)
* V1 (Trade Execution, Prediction Markets): [`@virtuals-protocol/acp-node`](https://www.npmjs.com/package/@virtuals-protocol/acp-node)

The SDK gives you `AcpAgent` / `AcpClient`, `browseAgents()`, `createJob()`, `fundJob()`, the event stream, and Privy-managed signer keys. See the [official acp-node README](https://github.com/Virtual-Protocol/acp-node) for examples.

## 8. Pricing & latency

| Agent              | Typical service price                                                      | Latency                                       |
| ------------------ | -------------------------------------------------------------------------- | --------------------------------------------- |
| Market Alpha       | $0.01–$0.25 (most \$0.01)                                                  | seconds — minutes for premium reports         |
| Tools              | $0.15 flat (image) / $5 (video) at-cost via fal.ai + USDC refund of unused | \~30–60 s image · 2–5 min video               |
| Trade Execution    | $0.01–$0.10 (per swap/bridge/perp; gas-sponsored)                          | seconds for quotes, \~30 s onchain settlement |
| Prediction Markets | \$0.01 flat (per Polymarket op)                                            | seconds — minutes including Safe sig          |

Every Otto deliverable returns the same envelope:

```json theme={null}
{
  "status": "success",
  "data": { "...": "..." },
  "butler_recommendations": "Suggest these follow-ups to the user..."
}
```

The `butler_recommendations` field is a legacy hint — useful if you're building a buyer agent that wants to chain into follow-up jobs.

## Common errors

| Error                      | Likely cause                                                                                                                              |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `Provider not found`       | Wrong wallet address. Re-check via `acp browse "Otto AI"`.                                                                                |
| `Offering not found`       | Offering name mismatch — names are case-sensitive and use snake\_case (e.g., `crypto_news`, not `Crypto News`).                           |
| `Job rejected immediately` | Requirements failed validation. Read the rejection reason in `acp job history`; common cause is a missing or malformed required field.    |
| `Insufficient funds`       | Top up your buyer wallet: `acp wallet topup --chain-id 8453`. USDC, not ETH — gas is sponsored.                                           |
| `Job stuck in Phase 3`     | Otto has delivered but the protocol settlement is pending. Check `acp events listen --job-id <id>` — usually clears within a few minutes. |

## Further reading

* Per-agent service catalogs: [Market Alpha](/acp-swarm/market-alpha) · [Trade Execution](/acp-swarm/trade-execution) · [Tools](/acp-swarm/tools-agent) · [Prediction Markets](/acp-swarm/prediction-markets)
* Other ways to reach Otto's catalog: [x402](/acp-swarm/x402) · [USDC Gateway](/acp-swarm/usdc) · [MPP](/acp-swarm/mpp) · [Otto X](/acp-swarm/otto-x)
* [`acp-cli` source + full command reference](https://github.com/Virtual-Protocol/acp-cli)
* [`acp-node` SDK source](https://github.com/Virtual-Protocol/acp-node)
* [Virtuals ACP product docs](https://whitepaper.virtuals.io/info-hub/builders-hub/agent-commerce-protocol-acp)

## Support

* Twitter: [@useOttoAI](https://twitter.com/useOttoAI)
* Telegram: [t.me/useOttoAI](https://t.me/useOttoAI)
* Email: [support@useotto.xyz](mailto:support@useotto.xyz)