# The Citadel — Agent Integration Contract

Machine-first integration guide for autonomous agents and developer tool-calling frameworks.

## Base Discovery
- Base URL: `https://thecitadelapp.com`
- OpenAPI: `https://thecitadelapp.com/api/openapi`
- Agent Card: `https://thecitadelapp.com/.well-known/agent.json`
- UCP Profile: `https://thecitadelapp.com/.well-known/ucp.json`
- Product Feed (JSON): `https://thecitadelapp.com/products.json`
- Product Feed (XML): `https://thecitadelapp.com/products.xml`

## Protocols
- `mcp` (Model Context Protocol): `POST /api/mcp/server` (streamable HTTP, stateless POST mode)
- `headless commerce`: `GET/POST /api/commerce/headless`
- `x402 settlement`: `POST/GET /api/commerce/x402/settle`
- `ucp`: `POST /api/ucp/purchase`, `POST /api/ucp/redeem`, `GET /api/ucp/key`

## Product Identifiers
- UCP SKUs: `CITADEL-ROAST-001`, `CITADEL-FD-001`, `CITADEL-VICE-001`
- Headless product IDs: `roast`, `flake-detector`, `vice`, `agentic_roast`, `agentic_flake`, `agentic_vice`

## Fastest Transaction Path (Headless)
1. `GET /api/commerce/headless` to discover catalog and payment methods.
2. `POST /api/commerce/headless` with:
   - `product`
   - `payment_method` in `credits | x402 | mandate`
   - plus method-specific fields:
     - `credits`: `user_id`
     - `x402`: `tx_hash`, `network`
     - `mandate`: `mandate_jwt`
3. On success, store `job_id`, `poll_url`, and `receipt`.
4. Poll `GET /api/commerce/jobs/{id}` until terminal status: `complete | failed | canceled | expired`.

## UCP + x402 Handshake Notes
- `GET /api/ucp/purchase?product={SKU}` may return `402 Payment Required`.
- Machine-readable headers currently emitted by runtime:
  - `X-Payment-Required`
  - `X-Payment-Amount`
  - `X-Payment-Currency`
  - `X-Payment-Address`
- After checkout, use `POST /api/ucp/redeem` with `key`.

## MCP Notes
- Endpoint: `POST /api/mcp/server`
- Auth: `Authorization: Bearer <MCP_SECRET_KEY|GATEWAY_KEY>`
- Transport behavior: GET/DELETE return `405`; send MCP JSON-RPC requests via POST only.

## Error Handling Expectations
- Treat `401` as auth failure (refresh key/token and retry once).
- Treat `402` as payment required (complete payment, then retry or poll).
- Treat `400` as schema/payload issue (do not blind retry; fix payload).
- Treat `500` as transient platform error (retry with exponential backoff).