# Vendling Commerce API

> UCP-aligned commerce interface of vendling-core, the AI agent that runs a real vending
> route (two machines in Beijing). Supplier SKU catalog, machine inventory, wholesale
> purchase checkout, sales ledger, live price changes, replenishment, approvals, events.
> Spec version 2026-09-09, aligned with UCP 2026-08-25. Amounts are integer CNY fen;
> ids are `<vendor>-<role>:<vendor_sku>`; the live namespaces come from GET /ucp/v1/namespaces.

Routes live at `https://vendling.xiaopingfeng.com/ucp/v1/*`; discovery at
`GET https://vendling.xiaopingfeng.com/.well-known/ucp` (public). Everything else is
behind `Authorization: Bearer <VENDLING_AUTH_TOKEN>`. The docs never name a vendor: machines
and suppliers plug in through adapters and the docs use the placeholder vendor `acme`. Two actions spend real money or
change a live price and require the JSON boolean `confirm: true`. Staging (mock data, no
supplier credentials): `https://vendling-core-staging.fxp007.workers.dev`.

## Docs

- [Guide (Chinese, normative)](https://vendling.dev/api/): capabilities, entities, status machines, guardrails, the adapter contract (appendix A), capability × device matrix (appendix B)
- [Full guide as markdown](https://vendling.dev/api/llms-full.txt)
- [OpenAPI 3.1](https://vendling.dev/api/openapi.yaml) · [rendered reference](https://vendling.dev/api/reference)

## Agent setup and skill

- [Agent setup prompt](https://vendling.dev/api/agent-setup/prompt.md): one instruction that installs the skill, configures the token and verifies the connection
- [SKILL.md](https://vendling.dev/api/skill/SKILL.md): how to integrate safely, with recipes
- [ucp-endpoints.md](https://vendling.dev/api/skill/references/ucp-endpoints.md): every endpoint with request/response shapes
- [ids-and-units.md](https://vendling.dev/api/skill/references/ids-and-units.md): sku_id namespaces, sale units (EA/BX), aliases
- [errors.md](https://vendling.dev/api/skill/references/errors.md)
- [vendling_client.py](https://vendling.dev/api/skill/scripts/vendling_client.py): stdlib Python client + CLI
- [zip](https://vendling.dev/api/skill/vendling-commerce-api.skill.zip)

## Related

- [Portal index](https://vendling.dev/llms.txt)
- [Docs source on GitHub](https://github.com/fxp/vendling-api)
- [UCP specification](https://ucp.dev/2026-08-25/specification/overview/)
- [Vendling project page](https://xiaopingfeng.com/apps/vendling/)