---
title: "UCP Discovery Document"
description: "Universal Commerce Protocol discovery profile — a single endpoint describing every real, live AINative payment capability"
canonical: "https://docs.ainative.studio/docs/web3/ucp-discovery"
last-updated: "2026-10-28T06:34:16.301Z"
---

# UCP Discovery Document

Source: https://docs.ainative.studio/docs/web3/ucp-discovery

> Universal Commerce Protocol discovery profile — a single endpoint describing every real, live AINative payment capability

# UCP Discovery Document

**Endpoint:** `GET /.well-known/ucp`
**Auth:** None — public discovery document
**Cache:** `Cache-Control: public, max-age=3600`

:::tip Live & Public
Try it right now, no API key needed:

```bash
curl https://ainative-browser-builder.up.railway.app/.well-known/ucp
```
:::

## What it's for

UCP (Universal Commerce Protocol) is a `.well-known` discovery convention that lets an agent or a commerce-aware crawler ask one question — "how can I pay you?" — and get back a single machine-readable document instead of having to probe individual endpoints. AINative's `/.well-known/ucp` document lists every payment capability the platform actually supports today: Stripe subscriptions, x402 crypto micropayments, and AP2 mandate verification.

It follows the same discipline as the platform's other `/.well-known/*` discovery documents (`/.well-known/x402`, `/.well-known/provisioning`): **every entry describes a real, working path, never a planned or aspirational one.** The subscription plan names are read directly from the same `STRIPE_PRICE_IDS` map that the real checkout flow (`plan_catalog_service.py`) uses, so this document can't advertise a plan that doesn't actually exist. The x402 network/asset fields are read from the same `x402_subscription_service.py` settings that back the live `/.well-known/x402` document, so the two stay consistent with each other and with what a real payment attempt observes.

## Response shape

```http
GET /.well-known/ucp
```

Returns `200 OK` with a JSON body shaped like this:

| Field | Type | Description |
|-------|------|-------------|
| `version` | `string` | Document version, formatted as an ISO date (`YYYY-MM-DD`) of the last revision. |
| `capabilities` | `array` | List of payment capability objects. Each entry's `type` determines which other fields are present (see below). |

### `capabilities[]` — common field

| Field | Type | Description |
|-------|------|-------------|
| `type` | `string` | One of `"subscription"`, `"x402"`, or `"ap2"`. |
| `description` | `string` | Human-readable summary of the capability. |

### `type: "subscription"`

Real Stripe-backed subscription plans — the same plan catalog the platform's checkout flow uses.

| Field | Type | Description |
|-------|------|-------------|
| `plans` | `array` of `{name: string}` | Every subscription plan currently sold, by display name. |

### `type: "x402"`

HTTP 402-based crypto micropayments. Mirrors the platform's dedicated [`/.well-known/x402`](https://ainative-browser-builder.up.railway.app/.well-known/x402) discovery document.

| Field | Type | Description |
|-------|------|-------------|
| `asset` | `string` | Settlement asset, currently `"USDC"`. |
| `network` | `string` | Settlement network (e.g. `"circle"` for USDC via Circle). Configurable via `X402_SETTLEMENT_NETWORK`. |

### `type: "ap2"`

[Agent Payments Protocol](https://github.com/google-agentic-commerce/AP2) (Google) mandate verification — real server-side SD-JWT verification at `POST /agentic_commerce/ap2/verify`.

| Field | Type | Description |
|-------|------|-------------|
| `mandate_types_supported` | `array` of `string` | AP2 mandate types this endpoint can verify: `"intent"`, `"cart"`, `"payment"`. |

## Example response

```json
{
  "version": "2026-10-27",
  "capabilities": [
    {
      "type": "subscription",
      "description": "Real Stripe-backed subscription plans.",
      "plans": [
        { "name": "Hobbyist" },
        { "name": "Starter" },
        { "name": "Pro" },
        { "name": "Business" },
        { "name": "Enterprise" },
        { "name": "Cody — Your Virtual CTO" }
      ]
    },
    {
      "type": "x402",
      "description": "HTTP 402-based crypto micropayments. See /.well-known/x402.",
      "asset": "USDC",
      "network": "circle"
    },
    {
      "type": "ap2",
      "description": "Agent Payments Protocol (Google) mandate verification. See POST /agentic_commerce/ap2/verify.",
      "mandate_types_supported": ["intent", "cart", "payment"]
    }
  ]
}
```

:::info Plan names can change
`plans[].name` reflects whatever plans are live in `STRIPE_PRICE_IDS` at request time — treat this list as authoritative over anything cached in documentation, including the example above.
:::

## curl example

```bash
curl -s https://ainative-browser-builder.up.railway.app/.well-known/ucp | python3 -m json.tool
```

## Related discovery documents

| Document | Purpose |
|----------|---------|
| [`/.well-known/x402`](https://ainative-browser-builder.up.railway.app/.well-known/x402) | x402-specific payment requirements (scheme, `pay_to` wallet, per-plan `resource` URIs) |
| `/.well-known/jwks.json` | Public keys for verifying AINative-issued JWTs |
| `/.well-known/openid-configuration` | OpenID Connect discovery |

See also: [Agent402 API](./agent402) for agent-side x402 wallets and the Cloudflare wire-format payment flow.