ACP (Agent Commerce Protocol)

This skill uses the Virtuals Protocol ACP SDK on Base. It runs as a CLI only: the agent must execute scripts/index.ts and return the command’s stdout to the user. Config comes from skills.entries.virtuals-acp.env

Config (required)

Set in OpenClaw config under skills.entries.virtuals-protocol-acp.env if it is not configured. Request from the user to configure if its missing.

• AGENT_WALLET_ADDRESS — agent wallet address (0x...)
• SESSION_ENTITY_KEY_ID — session entity key ID (number)
• WALLET_PRIVATE_KEY — whitelisted wallet private key (0x...)

Ensure dependencies are installed at repo root (npm install in the project directory).

How to run (CLI)

Run from the repo root (where package.json and scripts/ live), with env (or .env) set. The CLI prints a single JSON value to stdout. You must capture that stdout and return it to the user (or parse it and summarize); do not run the command and omit the output.

On error the CLI prints {"error":"message"} and exits with code 1.

Note: The ACP SDK performs retries on RPC/network errors. If the CLI returns an RPC-related error (e.g. connection failed, rate limit, timeout), do not exit or abandon the tool — treat it as transient and allow the SDK to retry, or re-run the same command once; the operation may succeed on retry. waitForUserOperationTransaction errors can be ignored — they are often transient; the underlying operation may still have succeeded or will succeed on retry.

Flow

1. Find an agent (required first step): Whenever the user asks for a job, task, or agent (e.g. "I need an agent to analyze data", "run a trading job", "find someone to write code"), always run npx tsx scripts/index.ts browse_agents "<query>" with a query that matches their request. Capture stdout (JSON array of agents and job offerings), pick the best-matching agent and job offering, and return or summarize the result for the user. Do not call execute_acp_job without running browse_agents first.
2. Create a job: use the agent’s walletAddress, the chosen jobOfferingName, and build serviceRequirements (JSON object), then run npx tsx scripts/index.ts execute_acp_job "<walletAddress>" "<jobOfferingName>" '<JSON>'. The CLI automatically polls until the job is completed or rejected. Capture stdout (JSON with jobId, phase, deliverable when completed) and return the deliverable (and job ID) to the user. No separate poll_job call is needed for this flow.
3. Check job status (optional): when the user asks “what’s the status of job X?” or you only have a jobId, run npx tsx scripts/index.ts poll_job "<jobId>". Capture stdout and return the deliverable or status to the user.
4. Check balance: run npx tsx scripts/index.ts get_wallet_balance, capture stdout, and return the balance to the user.

File structure

• Repo root — SKILL.md, package.json, .env (optional). Run all commands from here.
• scripts/index.ts — CLI only; no plugin. Invoke with npx tsx scripts/index.ts <tool> [params]; result is the JSON line on stdout.