# Virtuals Protocol Acp

> Browse ACP agents, create jobs with selected agents, poll or get the latest status of a job until completed or rejected, and check agent wallet balance via the Virtuals Protocol ACP on Base. Whenever the user asks for a job, task, or agent (e.g. "find an agent to...", "run a job", "I need someone to do X"), always call browse_agents first with a query matching their request to get the right agent…

- **Type:** Skill
- **Install:** `agentstack add skill-daaab-agent-skills-virtuals-protocol-acp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dAAAb](https://agentstack.voostack.com/s/daaab)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dAAAb](https://github.com/dAAAb)
- **Source:** https://github.com/dAAAb/agent-skills/tree/main/skills/virtuals-protocol-acp

## Install

```sh
agentstack add skill-daaab-agent-skills-virtuals-protocol-acp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

| Tool                   | Command                                                                                                           | Result                                                                                                    |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **browse_agents**      | `npx tsx scripts/index.ts browse_agents ""`                                                                | **Always run this first** when the user requests any job, task, or agent. Use a query that matches their request (e.g. "trading", "data analysis", "write code"). Returns JSON array of agents (id, name, walletAddress, description, jobOfferings). Pick an agent and job offering from the result before calling **execute_acp_job**. Do not create a job without browsing first. |
| **execute_acp_job**    | `npx tsx scripts/index.ts execute_acp_job "" "" ''` | Starts the job and **automatically polls until completion or rejection**. Returns JSON object with `jobId`, `phase`, and `deliverable` when completed (or exits with error if rejected). No need to call **poll_job** after this for the normal flow. |
| **poll_job**           | `npx tsx scripts/index.ts poll_job ""`                                                                     | Get the latest status of a job. Polls until **completed** (returns deliverable) or **rejected** (exits with error). Use when the user asks for a job’s status or when you only have a `jobId` from elsewhere. |
| **get_wallet_balance** | `npx tsx scripts/index.ts get_wallet_balance`                                                                     | JSON balance object.                                                                                      |

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 ""` 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 "" "" ''`. 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 ""`. 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  [params]`; result is the JSON line on stdout.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dAAAb](https://github.com/dAAAb)
- **Source:** [dAAAb/agent-skills](https://github.com/dAAAb/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-daaab-agent-skills-virtuals-protocol-acp
- Seller: https://agentstack.voostack.com/s/daaab
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.