Skip to content

Commit 9380d6e

Browse files
eliotjleeeliotjlee
committed
Initial public release
0 parents  commit 9380d6e

File tree

175 files changed

+44619
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

175 files changed

+44619
-0
lines changed

‎.gitignore‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Created by https://www.toptal.com/developers/gitignore/api/node
2+
# Edit at https://www.toptal.com/developers/gitignore?templates=node
3+
4+
### Node ###
5+
# Logs
6+
logs
7+
*.log
8+
npm-debug.log*
9+
yarn-debug.log*
10+
yarn-error.log*
11+
lerna-debug.log*
12+
.pnpm-debug.log*
13+
14+
# Diagnostic reports (https://nodejs.org/api/report.html)
15+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
16+
17+
# Runtime data
18+
pids
19+
*.pid
20+
*.seed
21+
*.pid.lock
22+
23+
# Directory for instrumented libs generated by jscoverage/JSCover
24+
lib-cov
25+
26+
# Coverage directory used by tools like istanbul
27+
coverage
28+
*.lcov
29+
30+
# nyc test coverage
31+
.nyc_output
32+
33+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
34+
.grunt
35+
36+
# Bower dependency directory (https://bower.io/)
37+
bower_components
38+
39+
# node-waf configuration
40+
.lock-wscript
41+
42+
# Compiled binary addons (https://nodejs.org/api/addons.html)
43+
build/Release
44+
45+
# Dependency directories
46+
node_modules/
47+
jspm_packages/
48+
49+
# Snowpack dependency directory (https://snowpack.dev/)
50+
web_modules/
51+
52+
# TypeScript cache
53+
*.tsbuildinfo
54+
55+
# Optional npm cache directory
56+
.npm
57+
58+
# Optional eslint cache
59+
.eslintcache
60+
61+
# Optional stylelint cache
62+
.stylelintcache
63+
64+
# Microbundle cache
65+
.rpt2_cache/
66+
.rts2_cache_cjs/
67+
.rts2_cache_es/
68+
.rts2_cache_umd/
69+
70+
# Optional REPL history
71+
.node_repl_history
72+
73+
# Output of 'npm pack'
74+
*.tgz
75+
76+
# Yarn Integrity file
77+
.yarn-integrity
78+
79+
# dotenv environment variable files
80+
.env
81+
.env.development.local
82+
.env.test.local
83+
.env.production.local
84+
.env.local
85+
86+
# parcel-bundler cache (https://parceljs.org/)
87+
.cache
88+
.parcel-cache
89+
90+
# Next.js build output
91+
.next
92+
out
93+
94+
# Nuxt.js build / generate output
95+
.nuxt
96+
dist
97+
98+
# Gatsby files
99+
.cache/
100+
# Comment in the public line in if your project uses Gatsby and not Next.js
101+
# https://nextjs.org/blog/next-9-1#public-directory-support
102+
# public
103+
104+
# vuepress build output
105+
.vuepress/dist
106+
107+
# vuepress v2.x temp and cache directory
108+
.temp
109+
110+
# Docusaurus cache and generated files
111+
.docusaurus
112+
113+
# Serverless directories
114+
.serverless/
115+
116+
# FuseBox cache
117+
.fusebox/
118+
119+
# DynamoDB Local files
120+
.dynamodb/
121+
122+
# TernJS port file
123+
.tern-port
124+
125+
# Stores VSCode versions used for testing VSCode extensions
126+
.vscode-test
127+
128+
# yarn v2
129+
.yarn/cache
130+
.yarn/unplugged
131+
.yarn/build-state.yml
132+
.yarn/install-state.gz
133+
.pnp.*
134+
135+
### Node Patch ###
136+
# Serverless Webpack directories
137+
.webpack/
138+
139+
# Optional stylelint cache
140+
141+
# SvelteKit build / generate output
142+
.svelte-kit
143+
144+
# End of https://www.toptal.com/developers/gitignore/api/node
145+
146+
.DS_Store

‎.npmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
loglevel=error

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Locus Technologies Inc
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
2+
# Agentic Commerce Protocol (ACP) Demo Implementation
3+
<p align="center">
4+
<a href="https://paywithlocus.com">
5+
<img src="docs/locus-logo.png" alt="Locus Logo" width="120"/>
6+
</a><br/>
7+
<em>Built with ❤️ by <a href="https://paywithlocus.com">Locus</a> (YC F25)</em>
8+
</p>
9+
10+
11+
12+
On [September 29th](https://openai.com/index/buy-it-in-chatgpt/), OpenAI released the Agentic Commerce Protocol (ACP), which will be foundational for how agents transact with the outside world.
13+
14+
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.
15+
16+
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).
17+
18+
19+
## Quick Start
20+
21+
### Prerequisites
22+
23+
- Node.js 20+
24+
- Docker & Docker Compose
25+
- OpenAI and/or Anthropic API keys
26+
27+
### Setup
28+
29+
1. **Clone the repository**
30+
```bash
31+
git clone https://github.com/locus-technologies/agentic-commerce-protocol-demo
32+
cd agentic-commerce-protocol-demo
33+
```
34+
35+
2. **Install dependencies**
36+
```bash
37+
npm install
38+
```
39+
This installs all dependencies across all workspaces (demo services + chat client).
40+
41+
3. **Configure API keys for the chat client**
42+
```bash
43+
cd chat-client
44+
cp .env.example .env
45+
# Edit .env and add your OPENAI_API_KEY and/or ANTHROPIC_API_KEY
46+
cd ..
47+
```
48+
49+
4. **Start all services**
50+
```bash
51+
npm run dev
52+
```
53+
This will:
54+
- Start PostgreSQL databases (via Docker)
55+
- Start the Merchant API (port 4001)
56+
- Start the PSP API (port 4000)
57+
- Start the MCP server (port 3112)
58+
59+
5. **Start the chat client** (in a new terminal)
60+
```bash
61+
cd chat-client
62+
npm run dev
63+
```
64+
Open http://localhost:3000 in your browser.
65+
66+
6. **Try it out!**
67+
- Ask the agent: "Show me some shirts"
68+
- Add items to cart
69+
- Complete checkout with test payment info
70+
- Examine how the Client, Merchant, and PSP interact via terminal
71+
72+
## Repository Structure
73+
74+
```
75+
├── demo/ # Reference implementation of ACP
76+
│ ├── mcp-ui-server/ # MCP server with commerce tools
77+
│ ├── merchant/ # Merchant API (checkout sessions)
78+
│ └── psp/ # Payment Service Provider
79+
└── chat-client/ # MCP-UI compatible chat interface
80+
# (adapted from scira-mcp-ui-chat)
81+
```
82+
83+
84+
# Core Concepts & Definitions
85+
86+
ACP coordinates three modular systems:
87+
88+
- **Client**: The environment where users interact with an LLM (e.g., ChatGPT, Claude.ai, Ollama).
89+
- **Merchant**: A vendor (e.g., Etsy, eBay, Amazon) selling goods or services through the client.
90+
- **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.*
91+
92+
93+
<br/>
94+
<p align="center">
95+
<img src="docs/flow.png" alt="ACP Flow Diagram" width="400"/>
96+
</p>
97+
98+
## Implementation Details
99+
100+
### Client
101+
102+
- For ease of development, server logic is offshored onto an MCP server compatible with [MCP-UI](https://github.com/idosal/mcp-ui): an open-source extension of MCP that introduces UI components as tool return types.
103+
- For our chat client, we adapted [Ido Saloman's MCP-UI-compatible fork of Scira Chat](https://github.com/idosal/scira-mcp-ui-chat) (see `chat-client/` directory)
104+
- In our implementation, the chat client + MCP together constitute the Client entity in the ACP protocol.
105+
106+
### Merchant + PSP
107+
- Each service implements the endpoints required by the ACP spec.
108+
- **Merchant**: checkout session management.
109+
- **PSP**: delegated payment endpoint for minting tokens.
110+
111+
## Shopping Workflow
112+
113+
*See [OpenAI's docs](https://developers.openai.com/commerce/specs/checkout)*
114+
115+
##### Open a checkout session
116+
117+
When the user first adds an item to the cart, the Client calls:
118+
```http
119+
POST /checkout_sessions
120+
```
121+
- The request body includes the line items being added.
122+
- A checkout session state tracks line items, user contact info, and fulfillment address.
123+
124+
125+
##### Update session state
126+
127+
As the user shops, the Client updates the Merchant each time the cart, contact info, or fulfillment address changes:
128+
```http
129+
POST /checkout_sessions/{checkout_session_id}
130+
```
131+
- Per ACP spec, the Merchant returns its copy of the updated checkout state.
132+
- The Client treats this as the source of truth and updates the in-chat UI accordingly.
133+
134+
##### Cancel session (optional)
135+
Removing all items from the cart cancels the session. Alternatively, the Client can explicitly cancel by calling:
136+
```http
137+
POST /checkout_sessions/{checkout_session_id}/cancel
138+
```
139+
140+
##### Retrieve session details (optional)
141+
For implementations that need it, the Client can fetch details for a session:
142+
```http
143+
GET /checkout_sessions/{checkout_session_id}
144+
```
145+
146+
147+
## Payment / Checkout Workflow
148+
*See [OpenAI's docs](https://developers.openai.com/commerce/specs/payment)*
149+
150+
For transactions, we implemented the Delegated Checkout flow:
151+
1. When the user submits payment credentials, the Client passes them to the Merchant’s PSP.
152+
2. The PSP stores the credentials and mints a Shared Payment Token (a reference to the vaulted credentials).
153+
3. The PSP returns the token to the Client.
154+
4. The Client POSTs `/checkout_sessions/:checkout_session_id/complete` to the Merchant, including the token.
155+
5. The Merchant redeems the token with the PSP, which invalidates it and executes the transaction.
156+
157+
158+
##### Why delegated payments?
159+
- Merchants don’t want to handle raw card data (which would put them in PCI compliance scope).
160+
- 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.
161+
162+
163+
## Product Feed
164+
*See [OpenAI's docs](https://developers.openai.com/commerce/specs/feed)*
165+
- ACP also defines a spec: merchants must regularly provide product data (TSV, CSV, XML, JSON) to a secure endpoint.
166+
- 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.
167+
168+
## The Future
169+
All endpoints defined by the ACP spec adhere to the standard, including required headers, response formats, and idempotency handling.
170+
171+
That said, [ACP repo](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol) 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!
172+
173+
## About us
174+
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](https://paywithlocus.com).
175+
176+
</br>
177+
178+
---
179+
*Note: This repo is a demo sandbox. All transactions are mocked — no real payments occur.*

‎chat-client/.env.example‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# API Keys (Optional - can also be set via UI settings)
2+
ANTHROPIC_API_KEY=sk-ant-...
3+
OPENAI_API_KEY=sk-...

0 commit comments

Comments
 (0)