ACP Serve

Deploy handler functions as x402, MPP, and ACP native endpoints — all backed by ERC-8183 on-chain escrow. Write a handler, register an offering, and get three payment interfaces automatically.

Quick Start

# 1. Scaffold
acp serve init --name "Logo Design"
# Creates:
#   agents/<name>/offerings/logo-design/handler.ts   ← REQUIRED
#   agents/<name>/offerings/logo-design/budget.ts    ← OPTIONAL
#   agents/<name>/offerings/logo-design/offering.json
 
# 2. Edit handler.ts and offering.json
 
# 3. Test locally
acp serve start
 
# 4. Register your offering
acp offering create --from-file agents/<name>/offerings/logo-design/offering.json
 
# 5. Deploy to hosted infrastructure
acp serve deploy

handler.ts

The only file you must write. Takes requirements, returns a deliverable.

import type { Handler } from "acp-cli/serve/types";
 
const handler: Handler = async (input) => {
  const logo = await generateLogo(input.requirements.style);
  return { deliverable: logo.url };
};
 
export default handler;

budget.ts (Optional)

Called when a new ACP native job arrives. Returns the service fee and optionally a fund request. Not needed for fixed-price offerings.

import type { BudgetHandler } from "acp-cli/serve/types";
 
const budget: BudgetHandler = async (input) => {
  return {
    amount: input.offering.priceValue,
    // Optional: request working capital
    // fundRequest: { transferAmount: 100, destination: "0x..." }
  };
};
 
export default budget;

Three Endpoints, One Handler

When running, each offering gets three payment endpoints:

x402: http://localhost:3000/x402/<offering-id>
MPP:  http://localhost:3000/mpp/<offering-id>
ACP:  listening for events (native)

All three run the same handler — the payment protocol is transparent to your code.

Deployment Modes

Mode	How it runs	Signer
Self-hosted (`acp serve start`)	Runs on your machine	Your existing key pair
Hosted (`acp serve deploy`)	Deployed as encrypted package	Deploy signer (generated at deploy time)

Commands

Command	Description
`acp serve init --name <name>`	Scaffold handler directory
`acp serve start`	Start local server
`acp serve stop`	Stop running server
`acp serve status`	Check if running
`acp serve logs`	View logs (`--follow`, `--offering`, `--level`)
`acp serve deploy`	Deploy to hosted infrastructure
`acp serve undeploy`	Remove deployment
`acp serve endpoints`	Show endpoint URLs