> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic Commerce Protocol Handler

> Self-hosted server implementing the Agentic Commerce Protocol for ChatGPT Instant Checkout

Agentic Commerce Protocol (ACP) Handler is a Rust server that implements OpenAI's Agentic Commerce Protocol. It provides checkout session APIs, delegated payments, and optional gRPC access so you can keep orders and compliance in your own stack while enabling ChatGPT Instant Checkout experiences.

## Key capabilities

* Full checkout session lifecycle for the ACP spec
* Delegated payment endpoint with vault token support
* Optional Stripe PaymentIntent integration
* Idempotency keys and request tracing
* Swagger UI at `/docs` and OpenAPI JSON at `/openapi.json`
* gRPC API mirroring the HTTP endpoints

## Architecture overview

```mermaid theme={null}
graph LR
  ChatGPT[ChatGPT or client] -->|HTTP or gRPC| Handler[ACP Handler]
  Handler --> Redis[Redis or in-memory sessions]
  Handler --> Commerce[iCommerce or SQLite backend]
  Handler --> PSP[Payment service provider]
```

## Quickstart

```bash theme={null}
cargo build --release
cargo run --release
```

The HTTP server listens on `http://0.0.0.0:8080` by default. The gRPC server listens on `0.0.0.0:50051`.

To run the demo flow:

```bash theme={null}
./demo_test.sh
```

## Create a checkout session

```bash theme={null}
curl -X POST https://yourapp.com:8080/checkout_sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer api_key_123" \
  -H "API-Version: 2025-09-29" \
  -d '{
    "items": [{ "id": "item_123", "quantity": 2 }],
    "buyer": { "email": "buyer@example.com" }
  }'
```

## Core endpoints

| Method | Endpoint                             | Description                        |
| ------ | ------------------------------------ | ---------------------------------- |
| POST   | `/checkout_sessions`                 | Create a checkout session          |
| GET    | `/checkout_sessions/:id`             | Retrieve a checkout session        |
| POST   | `/checkout_sessions/:id`             | Update a checkout session          |
| POST   | `/checkout_sessions/:id/complete`    | Complete checkout and create order |
| POST   | `/checkout_sessions/:id/cancel`      | Cancel a checkout session          |
| POST   | `/agentic_commerce/delegate_payment` | Delegated payment (vault token)    |
| GET    | `/health`                            | Health check                       |
| GET    | `/ready`                             | Readiness check                    |
| GET    | `/docs`                              | Swagger UI                         |
| GET    | `/openapi.json`                      | OpenAPI spec                       |

## Delegated payments

The delegated payment endpoint accepts payment tokens from a PSP vault. Tokens are validated for allowance and expiry and are consumed after use.

## Stripe integration

Set the following environment variables before starting the server to process delegated payments with Stripe:

* `STRIPE_SECRET_KEY`
* `STRIPE_PUBLISHABLE_KEY` (optional)
* `STRIPE_WEBHOOK_SECRET` (optional, for webhook signature verification)

## gRPC access

The gRPC API mirrors the HTTP endpoints and uses the same API keys. Send `authorization: Bearer <api_key>` as gRPC metadata.

## Related components

The repository also includes:

* A Next.js dashboard for monitoring checkout sessions
* A ChatGPT widget server for MCP-based agent flows
* Kubernetes and Docker Compose deployment assets