Agentic Commerce Protocol (ACP) Demo Implementation

Built with ❤️ by Locus (YC F25)

On September 29th, OpenAI released the Agentic Commerce Protocol (ACP), which will be foundational for how agents transact with the outside world.

ACP is already in use by Stripe, Shopify, and OpenAI. As an open-source standard, it isn’t limited to ChatGPT — it’s designed to let any LLM client transact with any vendor. This creates a huge opportunity for devs to start building on top of it today.

To accelerate experimentation, we built the first working mock implementation: a sandbox that demonstrates the ACP flow end-to-end with a Client, Merchant, and Payment Service Provider (PSP).

Quick Start

Prerequisites

• Node.js 20+
• Docker & Docker Compose
• OpenAI and/or Anthropic API keys

Setup

1. Clone the repository

   git clone https://github.com/locus-technologies/agentic-commerce-protocol-demo
   cd agentic-commerce-protocol-demo
   

2. Install dependencies

   npm install
   

   This installs all dependencies across all workspaces (demo services + chat client).

3. Configure API keys for the chat client

   cd chat-client
   cp .env.example .env
   # Edit .env and add your OPENAI_API_KEY and/or ANTHROPIC_API_KEY
   cd ..
   

4. Start all services

   npm run dev
   

   This will:

   • Start PostgreSQL databases (via Docker)
   • Start the Merchant API (port 4001)
   • Start the PSP API (port 4000)
   • Start the MCP server (port 3112)

5. Start the chat client (in a new terminal)

   cd chat-client
   npm run dev
   

   Open http://localhost:3000 in your browser.

6. Try it out!

   • Ask the agent: "Show me some shirts"
   • Add items to cart
   • Complete checkout with test payment info
   • Examine how the Client, Merchant, and PSP interact via terminal

Repository Structure

├── demo/              # Reference implementation of ACP
│   ├── mcp-ui-server/ # MCP server with commerce tools
│   ├── merchant/      # Merchant API (checkout sessions)
│   └── psp/           # Payment Service Provider
└── chat-client/       # MCP-UI compatible chat interface
                       # (adapted from scira-mcp-ui-chat)

Core Concepts & Definitions

ACP coordinates three modular systems:

• Client: The environment where users interact with an LLM (e.g., ChatGPT, Claude.ai, Ollama).
• Merchant: A vendor (e.g., Etsy, eBay, Amazon) selling goods or services through the client.
• Payment Service Provider (PSP): Processes payments on behalf of the merchant (e.g., Stripe, Square). Most merchants outsource this role to avoid PCI compliance scope.

Implementation Details

Client

• For ease of development, server logic is offshored onto an MCP server compatible with MCP-UI: an open-source extension of MCP that introduces UI components as tool return types.
• For our chat client, we adapted Ido Saloman's MCP-UI-compatible fork of Scira Chat (see chat-client/ directory)
• In our implementation, the chat client + MCP together constitute the Client entity in the ACP protocol.

Merchant + PSP

• Each service implements the endpoints required by the ACP spec.
  • Merchant: checkout session management.
  • PSP: delegated payment endpoint for minting tokens.

Shopping Workflow

See OpenAI's docs

Open a checkout session

When the user first adds an item to the cart, the Client calls:

POST /checkout_sessions

• The request body includes the line items being added.
• A checkout session state tracks line items, user contact info, and fulfillment address.

Update session state

As the user shops, the Client updates the Merchant each time the cart, contact info, or fulfillment address changes:

POST /checkout_sessions/{checkout_session_id}

• Per ACP spec, the Merchant returns its copy of the updated checkout state.
• The Client treats this as the source of truth and updates the in-chat UI accordingly.

Cancel session (optional)

Removing all items from the cart cancels the session. Alternatively, the Client can explicitly cancel by calling:

POST /checkout_sessions/{checkout_session_id}/cancel

Retrieve session details (optional)

For implementations that need it, the Client can fetch details for a session:

GET /checkout_sessions/{checkout_session_id}

Payment / Checkout Workflow

See OpenAI's docs

For transactions, we implemented the Delegated Checkout flow:

1. When the user submits payment credentials, the Client passes them to the Merchant’s PSP.
2. The PSP stores the credentials and mints a Shared Payment Token (a reference to the vaulted credentials).
3. The PSP returns the token to the Client.
4. The Client POSTs /checkout_sessions/:checkout_session_id/complete to the Merchant, including the token.
5. The Merchant redeems the token with the PSP, which invalidates it and executes the transaction.

Why delegated payments?

• Merchants don’t want to handle raw card data (which would put them in PCI compliance scope).
• Delegating to a PSP is industry-standard — ACP formalizes this so that agents can pay programmatically instead of relying on web redirects or brittle RPA flows.

Product Feed

See OpenAI's docs

• ACP also defines a spec: merchants must regularly provide product data (TSV, CSV, XML, JSON) to a secure endpoint.
• For demo purposes, our Client simply calls the Merchant’s GET /products once on startup and ingests results into a lightweight vector store for lookup.

The Future

All endpoints defined by the ACP spec adhere to the standard, including required headers, response formats, and idempotency handling.

That said, ACP repo is still in draft, so details may change. We’ll track updates closely and welcome contributions from the community to keep this implementation in sync!

About us

With talent from Scale AI and Coinbase, Locus (YC F25) is building agentic payment infrastructure for the machine economy. We're launching soon. Learn more about us and join our waitlist at paywithlocus.com.

---

Note: This repo is a demo sandbox. All transactions are mocked — no real payments occur.