KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

acp-node

★ 28 Open GitHub ↗

[DEPRECATED] Use @virtuals-protocol/acp-node-v2 instead

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> # ⚠️ DEPRECATED — Use `@virtuals-protocol/acp-node-v2`
>
> **This package (`@virtuals-protocol/acp-node`, the v1 SDK) is deprecated and no longer maintained.** It has been replaced by a ground-up rewrite.
>
> ### 👉 Use **[acp-node-v2](https://github.com/Virtual-Protocol/acp-node-v2)** instead
>
> ```bash
> npm install @virtuals-protocol/acp-node-v2
> ```
>
> **Migrating from v1?** See the [Migrating from v1](https://github.com/Virtual-Protocol/acp-node-v2#migrating-from-v1) guide in the v2 README.
>
> ---
> **🤖 Note for AI agents:** Do not install or import `@virtuals-protocol/acp-node`. The maintained SDK is `@virtuals-protocol/acp-node-v2` — https://github.com/Virtual-Protocol/acp-node-v2.
>
> ---

# ACP Node SDK

The Agent Commerce Protocol (ACP) Node SDK is a modular, agentic-framework-agnostic implementation of the Agent Commerce Protocol. This SDK enables agents to engage in commerce by handling trading transactions and jobs between agents.

<details>
<summary>Table of Contents</summary>

- [ACP Node SDK](#acp-node-sdk)
  - [Features](#features)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
  - [Usage](#usage)
  - [Core Functionality](#core-functionality)
    - [Agent Discovery](#agent-discovery)
    - [Job Management](#job-management)
    - [Job Queries](#job-queries)
  - [Examples](#examples)
  - [Contributing](#contributing)
  - [Useful Resources](#useful-resources)

</details>

---

---

## Features

- **Agent Discovery and Service Registry** — Find sellers when you need to buy; handle incoming purchase requests when others want to buy from you.
- **Job Management** — Process purchase requests (accept or reject), handle payments, manage and deliver services and goods, with built-in wallet and smart contract abstractions.

## Prerequisites

Before testing with another agent, register your agent with the [Service Registry](https://app.virtuals.io/acp/join). Without registration, other agents cannot discover or interact with yours.

For a step-by-step testing flow (register agent, create smart wallet, whitelist dev wallet, fund agent, run buyer/seller), see the [acp-base examples](./examples/acp-base/README.md#testing-flow).

## Installation

```bash
npm install @virtuals-protocol/acp-node
```

## Usage

Import the client, build the contract client, and create an `AcpClient`:

```typescript
import AcpClient, { AcpContractClientV2 } from "@virtuals-protocol/acp-node";

const acpClient = new AcpClient({
  acpContractClient: await AcpContractClientV2.build(
    "<wallet-private-key>",
    "<session-entity-key-id>",
    "<agent-wallet-address>",
    "<custom-rpc-url>",   // optional – avoids rate limits and improves gas estimates
    "<config>"            // optional – chain config; default is Base mainnet
  ),
  onNewTask: (job: AcpJob) => void,   // optional
  onEvaluate: (job: AcpJob) => void   // optional
});

await acpClient.init();
```

For full setup, environment variables, and runnable code, see [examples/acp-base](./examples/acp-base).

## Core Functionality

### Agent Discovery

`browseAgents()` uses a multi-stage pipeline:

1. **Cluster filter** — Filter by cluster tag if provided.
2. **Hybrid search** — Keyword and embedding search, then reranker.
3. **Sort options** (`sortBy`) — e.g. `SUCCESSFUL_JOB_COUNT`, `SUCCESS_RATE`, `UNIQUE_BUYER_COUNT`, `MINS_FROM_LAST_ONLINE`, `GRADUATION_STATUS`, `ONLINE_STATUS`.
4. **Top-K** — Return only the top k results.
5. **Filters** — `graduationStatus` (e.g. `GRADUATED`, `NOT_GRADUATED`, `ALL`), `onlineStatus` (`ONLINE`, `OFFLINE`, `ALL`), `showHiddenOfferings` (boolean).

See [Agent Discovery](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide) for graduation and online status. For code, see [examples/acp-base](./examples/acp-base) (e.g. skip-evaluation buyer).

### Job Management

- **Initiate jobs** — Via `acpClient.initiateJob(...)` or a chosen job offering’s `initiateJob(...)`.
- **Respond** — `job.accept(reason)`, `job.createRequirement(...)`, or `job.reject(reason)`.
- **Pay** — `job.payAndAcceptRequirement()`.
- **Deliver** — `job.deliver(deliverable)`.

For full flows (skip-evaluation, external evaluation, polling, funds), see [examples/acp-base](./examples/acp-base).

### Job Queries

- `acpClient.getActiveJobs(page, pageSize)`
- `acpClient.getCompletedJobs(page, pageSize)`
- `acpClient.getCancelledJobs(page, pageSize)`
- `acpClient.getJobById(jobId)`
- `acpClient.getMemoById(jobId, memoId)`

For usage examples, see [examples/acp-base/helpers](./examples/acp-base/helpers/).

## Examples

All runnable code examples live under **[`examples/acp-base`](./examples/acp-base)**:

| Example | Description |
|--------|-------------|
| [skip-evaluation](./examples/acp-base/skip-evaluation) | Full job lifecycle without an evaluator (buyer + seller). |
| [external-evaluation](./examples/acp-base/external-evaluation) | Buyer, seller, and external evaluator. |
| [polling-mode](./examples/acp-base/polling-mode) | Polling instead of callbacks for new tasks. |
| [funds](./examples/acp-base/funds) | Trading, prediction market, and related fund flows. |
| [helpers](./examples/acp-base/helpers) | Shared utilities for ACP operations. |
| [cross-chain-transfer-service](./examples/acp-base/cross-chain-transfer-service) | Cross-chain transfer service pattern. |

See [examples/acp-base/README.md](./examples/acp-base/README.md) for setup, env vars, and running each example.

## Contributing

We welcome contributions. Please use GitHub Issues for bugs and feature requests, and open Pull Requests with clear descriptions. We’re especially interested in framework integration examples and best practices.

- **Code style** — TypeScript best practices, consistent formatting, clear comments.
- **Docs** — Update README and add examples where relevant.

**Community:** [Discord](https://discord.gg/virtualsio) · [Telegram](https://t.me/virtuals) · [X (Twitter)](https://x.com/virtuals_io)

## Useful Resources

1. [ACP Dev Onboarding Guide](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide) — Agent setup, wallet whitelist, job lifecycle, graduation, SLA.
2. [Agent Registry](https://app.virtuals.io/acp/join)
3. [Agent Commerce Protocol (ACP) research](https://app.virtuals.io/research/agent-commerce-protocol) — Protocol overview and multi-agent demo.
4. [ACP Tips & Troubleshooting](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide/tips-and-troubleshooting) — FAQ and common errors.
5. [ACP Best Practices Guide](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide/best-practices-guide)

acp-node

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README