> ## 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.

# Universal Commerce Protocol Handler

> Rust server that implements the Universal Commerce Protocol checkout flow and extensions

StateSet UCP Handler is a standalone Rust server that implements the Universal Commerce Protocol (UCP) checkout flow. It exposes discovery, checkout session lifecycle, tokenization, webhook delivery, and optional OAuth identity linking.

## Key capabilities

* Discovery at `/.well-known/ucp`
* Checkout session lifecycle endpoints
* Fulfillment and discount extensions
* Order webhooks and audit logs
* Tokenization endpoints (`/tokenize`, `/detokenize`)
* Optional OAuth 2.0 identity linking and AP2 mandate extension
* gRPC API with JSON payloads
* Optional iCommerce backend with SQLite persistence

## Quickstart

```bash theme={null}
cargo run
```

The HTTP server listens on `http://0.0.0.0:8081` by default. Run the demo flow:

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

## Required headers

By default the handler requires:

* `UCP-Agent` on all requests
* `Request-Signature` on `POST` and `PUT`

You can relax these for local testing with:

```bash theme={null}
UCP_REQUIRE_UCP_AGENT=false UCP_REQUIRE_REQUEST_SIGNATURE=false cargo run
```

Optional headers when enabled:

* `Request-Id` when `UCP_REQUIRE_REQUEST_ID=true`
* `Idempotency-Key` when `UCP_REQUIRE_IDEMPOTENCY=true`

## Create a checkout session

```bash theme={null}
curl -X POST https://yourapp.com:8081/api/checkout-sessions \
  -H "UCP-Agent: profile=\"https://platform.example/profile\"" \
  -H "Request-Signature: <detached-jws>" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [{ "item": { "id": "item_123" }, "quantity": 2 }],
    "currency": "USD"
  }'
```

## Core endpoints

| Method | Endpoint                              | Description           |
| ------ | ------------------------------------- | --------------------- |
| GET    | `/.well-known/ucp`                    | Discovery document    |
| GET    | `/api/checkout-sessions`              | List checkouts        |
| POST   | `/api/checkout-sessions`              | Create checkout       |
| GET    | `/api/checkout-sessions/:id`          | Retrieve checkout     |
| PUT    | `/api/checkout-sessions/:id`          | Update checkout       |
| POST   | `/api/checkout-sessions/:id/complete` | Complete checkout     |
| POST   | `/api/checkout-sessions/:id/cancel`   | Cancel checkout       |
| GET    | `/api/orders`                         | List orders           |
| GET    | `/api/orders/:id`                     | Retrieve order        |
| POST   | `/tokenize`                           | Tokenize credential   |
| POST   | `/detokenize`                         | Detokenize credential |
| GET    | `/metrics`                            | Prometheus metrics    |
| GET    | `/health`                             | Health check          |
| GET    | `/ready`                              | Readiness check       |

## Commerce backend

iCommerce is enabled by default and stores checkouts and orders in `./commerce.db`. Disable it for in-memory storage:

```bash theme={null}
COMMERCE_ENABLED=false cargo run
```

## Webhooks and audit trails

Set `UCP_ORDER_WEBHOOK_URL` to send order events when a checkout completes. The handler also exposes:

* `/api/audit-events`
* `/api/webhook-deliveries`

## OAuth and AP2 extensions

Enable identity linking with `UCP_OAUTH_ENABLED=true`. Enable AP2 mandate support with `UCP_AP2_ENABLED=true` and `UCP_AP2_MERCHANT_AUTH`.

## gRPC access

The gRPC server listens on `0.0.0.0:50051` by default and uses JSON payloads in `payload_json`. Auth can be provided via `authorization` or `x-api-key` metadata.