A trust gateway that lets AI purchasing agents order from a food wholesaler. The agent asks, code decides, and a person approves when the rules say so. Every price is signed and every step is logged.
Built at Junction 2026 for the Valio Aimo "Trusted Trade Agents" challenge.
Status: the event is over. The Valio Aimo challenge mock APIs have been offline since Junction, so the live agent flow can no longer get prices or stock. The screenshots show the real UI in its fixture mode, which runs with no backend.
Professional kitchens are starting to let AI agents do their purchasing. A wholesaler that accepts those orders has to answer three questions:
- How does the agent find the right product at a price it can rely on?
- What may the agent order alone, and what needs a person?
- After the fact, how do both sides prove who decided what, and why?
Valtuus answers them with a gateway on the seller side. The agent never touches the webshop or the backend, and it sees only what its key allows.
| What | How much |
|---|---|
| Pull requests merged during the event | 123 |
| Automated tests | 1,395 backend, 14 frontend |
| Products the agent can search | 17,546 |
| Agent tools over MCP | 12, plus the same flow over REST |
| Reason codes, each with a plain sentence | 32 |
| Language model calls in a decision | 0 |
A hotel kitchen manager talks to a Claude Code agent that runs our purchasing skill.
- "1,000 litres of lactose free milk for Tuesday." The agent searches, gets ranked offers with a reason for each product it rejects, and builds a cart. The total is over the auto limit, so the manager gets an approval link, approves on the phone, and a signed order comes back.
- "20 litres." The same milk, inside the limit and inside the usual quantity. The agent orders alone, with no person involved.
- "Valio Eila for Monday." The order deadline has passed. The agent refuses and says what can still arrive.
- "800 litres." Over the limit again. The manager raises the limit, and checkout goes through under mandate version 2. The audit shows which version allowed it.
From the frontend's fixture mode (VITE_USE_FIXTURES=true). Fixture data is not signed, so the
trust mark shows "Not signed (development)" where the live system shows a verified signature.
Approvals inbox. Every cart that waits for the manager, with the reason and the time left.
Approval on a phone. The first cart waits because it is over the limit. The second waits because the agent offered a substitute. The third shows that the agent changed the cart, so the manager must review the change before approval.
A denied order. The product contains an allergen that the buyer does not allow. The record under it shows each step with its time.
The record. What happened to one order, in the words the gateway wrote at the time.
Agent permissions. The limits, the product rules, what always needs a person, and the agents with a stop button for each.
Agent interface
- MCP server at
/api/mcpfor AI agents and a REST API at/api/v1for other systems. Both call the same services, so the rules cannot differ between them. - A per agent key with scopes. An agent key can never approve, reject or change the rules.
wait_for_decisionholds the call until a person decides, so the agent needs no timer.- Errors always have the shape
{error, message, next_step}, and the agent followsnext_step. A line with no quantity getsNEEDS_CLARIFICATION, so the agent asks instead of guessing. - A
valio-purchasingskill that teaches Claude Code the flow.
Catalog and offers
- Search over 17,546 products by name, category and GS1 attributes (claims, allergens). When the top categories are close, the gateway asks the buyer instead of guessing.
- Offers from the Valio Aimo price and stock APIs, with retry, backoff and a cache. Each offer has a fixed price, an expiry time, the stock at a stated time and the order deadline.
- Trading rules: sales units, lot sizes, sales blocks, passed deadlines and stock that nobody has confirmed.
- Ranking by stock first, then the buyer's preferred brands, then the buyer's own weights for price, delivery reliability and CO2. Missing data shows as "no data", never as 0.
- Substitutes for rejected products, offered only when the allergen data matches in full. A cart with a substitute always waits for a person.
- A proposed split when one product is short on stock.
Decisions
- A policy engine of small, pure checks. Each cart gets AUTO, HUMAN or DENY with reason codes.
- The mandate: automatic orders on or off, a limit per order, a daily limit per delivery date, required attributes and forbidden allergens. Every change makes a new version.
- A confirmed envelope: the agent orders alone only products that a person approved before, in a usual quantity. A new product or an unusual quantity goes to a person.
- A line that repeats a recent order waits for a person, and a cart the manager rejected before is denied.
Human approval
- An approval page made for phones: the request, each line with its stock, price and offer facts, and why the cart waits.
- Cart revisions on the same link. An approval of an old revision gets 409 and places no order.
- An "Agent permissions" page: the automatic order switch, the limits, the agent list with last use, and revoke. A revoked key gets 401 at once.
Trust and audit
- Offers and order confirmations are signed with Ed25519 (JWS). The keys are public at
/.well-known/jwks.json, andPOST /api/v1/verifychecks a signed document. The UI shows the result as a trust mark. - The agent cannot send a price, a stock value or a date. The gateway reads them from its own signed offer, so the buyer pays what the agent was quoted.
- An audit record in plain language for every step and every refusal: who, when, why and under which mandate version. The buyer and the seller read the same record.
- Idempotency keys on cart creation and checkout, so a retry never makes a second order.
Engineering
- Clean architecture:
domain<-services<-adaptersandapi, with the direction pinned by tests. - PostgreSQL with Alembic migrations, plus in-memory adapters for fast tests.
- Money as exact decimals, never floats.
- Every merge to
mainruns lint, tests and type checks, builds images and deploys to one VM. An unhealthy deploy rolls back to the last good image.
buyer --> buyer agent --(MCP or REST)--> Valtuus gateway --> Valio Aimo APIs
|
search, offers, cart
|
policy engine (no LLM)
|
+-------------------------+-------------------------+
| | |
AUTO HUMAN DENY
agent checks out main user approves or ended, with the
| rejects on the approval reason codes
| page (human session)
+-------------------------+
|
signed order confirmation + audit record
- Lookup. The agent searches the catalog and gets offers: a fixed price for the price period and the stock at a stated time.
- Cart. The agent creates a cart from offer IDs. It cannot send a price, a stock value or a date. The gateway reads them from its own stored offer.
- Decision. The policy engine checks the cart against the buyer's mandate (spend limits, required attributes, forbidden allergens, deadlines) and returns AUTO, HUMAN or DENY. The decision is plain code with unit tests.
- Order. Inside its authority the agent checks out. Outside it, only a person can approve, on the approval page. Words in the agent's chat are never an approval.
- Record. Every step writes an audit record that both sides can read.
The cart states, and who is bound to what, are in docs/INTERACTION.md.
| What | Where |
|---|---|
| MCP URL | https://junction.anvik.fi/api/mcp/ |
| REST base URL | https://junction.anvik.fi/api/v1 |
| API docs | https://junction.anvik.fi/api/docs and /api/openapi.json, no login |
The main user gives each agent its own key. Send it on every call, on MCP and REST:
Authorization: Bearer <agent key>
An agent key cannot approve or reject a cart, and cannot change the mandate. Only a person can.
For Claude Code, put this in .mcp.json and set AGENT_KEY in your shell, so the key is never
in the file:
{
"mcpServers": {
"valtuus": {
"type": "http",
"url": "https://junction.anvik.fi/api/mcp/",
"headers": {
"Authorization": "Bearer ${AGENT_KEY}"
}
}
}
}Make the 4 calls in this order. REST paths are relative to the base URL.
| Step | MCP tool | REST call | Result |
|---|---|---|---|
| 1 | search_products |
GET /catalog/search?query=... |
Product IDs. No price, no stock. |
| 2 | get_offers |
POST /offers |
Offer IDs, price and stock. |
| 3 | create_cart |
POST /carts |
The decision: AUTO, HUMAN or DENY. |
| 4 | checkout |
POST /carts/{cart_id}/checkout |
Order confirmation. AUTO only. |
- Before step 1: read the buyer's rules with
get_mandate(GET /mandate). - HUMAN: give the main user the cart's
approve_url. Callwait_for_decision(GET /carts/{cart_id}/wait) with the revision of your last read. It returns when the cart changes, or after a hold with the cart still pending: then call it again. - DENY: stop.
reason_sentencestell the buyer why. - Changes:
revise_cart(POST /carts/{cart_id}/revisions) replaces the lines of an AUTO or PENDING_APPROVAL cart and runs the policy again.withdraw_cart(POST /carts/{cart_id}/withdraw) ends a cart that the buyer no longer wants. - Retries:
create_cartandcheckoutneed an idempotency key (theIdempotency-Keyheader on REST, theidempotency_keyargument on MCP). Send the same key again on a retry. - Errors: every error has the body
{error, message, next_step}. Follownext_step. A cart line with noqtyalso getsreason_code: NEEDS_CLARIFICATIONandmissing: ask the buyer, do not guess.
Python 3.12, FastAPI, MCP, PostgreSQL 17, React 19, TypeScript, Caddy, Docker Compose and GitHub
Actions. The buyer agent is Claude Code with our valio-purchasing skill.
This is a prototype. There is no real Valio Aimo order API, the stock is a snapshot, prices are EUR ex VAT and there is one approver per buyer. The full list, and the known trust limits, are in docs/ASSUMPTIONS.md. What comes next, and the path to AP2, is in docs/NEXT_STEPS.md.
- MCP for agents, REST described in OpenAPI 3.1 for other systems.
- JSON-RPC 2.0, ISO 8601 times and EUR amounts as exact decimals.
- JWS and JWKS for signatures.
- Our mandate, approval and order model is close to AP2 and UCP, but we don't claim compliance.
Needs uv, Node 22 and Docker.
git clone https://github.com/anvikx/valtuus.git
cd valtuus
cp .env.example .env
make setup
make upOpen http://localhost. To run the parts on their own with reload, use make dev-be and
make dev-fe.
| Command | What it does |
|---|---|
make setup |
Install backend and frontend deps |
make check |
Lint, format, tests, types, build, infra (as CI) |
make fmt |
Format and autofix all code |
make dev-be |
Backend on http://localhost:8000 with reload |
make dev-fe |
Frontend on http://localhost:5173, proxies /api |
make up |
Full stack in Docker on http://localhost |
make down |
Stop the Docker stack |
The Valio Aimo product data is challenge data and is not part of this repository. The backend
downloads fresh files into backend/data/ (gitignored) and loads them before accepting requests.
VALIO_API_KEY must be set in .env. A product download or parsing error prevents startup;
unavailable enrichment files are omitted from that import. With make dev-be, a code reload
also downloads the files again.
Inspect existing files without downloading or starting the app:
cd backend
uv run python -m app.commands.check_catalog
uv run python -m app.commands.check_catalog 460994Pass --data-dir PATH to inspect files in a different directory.
FastAPI backend and React frontend behind Caddy. Every merge to main deploys to one VM.
browser --> Caddy (web) --+-- /api/* --> backend:8000 (FastAPI)
|
+-- else ----> /srv (React build)
backend/
app/api/ REST routes under /api
app/domain/ domain rules, no I/O
tests/
frontend/
src/api.ts the only place that calls the backend
docs/ interaction, assumptions, next steps
scripts/ deploy script
- Interaction: the cart states, and who is bound to what.
- Assumptions: what is not real in the prototype, and the known trust limits.
- Next steps: what comes after the prototype, and the path to AP2.
Read CONTRIBUTING.md for the code rules. In short:
- Work on a branch and open a PR. No direct push to
main. - Run
make checkbefore every push. - Every merge to
maindeploys. Merge only what works. - Backend routes live only under
/api. - The frontend calls the API only from
src/api.ts. - Secrets live only in the server
.env. Never commit them. - Before the demo, set the repo variable
DEPLOY_FROZEN=trueto stop deploys.
PR ---------> backend (ruff, pytest)
frontend (tsc, oxlint, prettier, build)
infra (actionlint, shellcheck)
push main --> backend + frontend + infra --> images --> deploy
| |
| +- scp compose file + deploy.sh
| +- ssh: deploy.sh <sha>
| healthy: keep, save tag
| unhealthy: roll back to last good tag
+- push ghcr.io/<owner>/<repo>/{backend,web}:<sha>
deploy is skipped when the repo variable DEPLOY_FROZEN is true.
- Install Docker with the compose plugin.
- Open ports 80 and 443.
- Make a deploy user that can run
docker, and add the public half of an SSH key to its~/.ssh/authorized_keys. - Make the deploy folder, for example
/opt/junction, and put.envin it (see.env.example). SetSITE_ADDRESSto the domain to get HTTPS, and point the DNS A record to the VM.
- Settings > Environments: create
production. - Settings > Secrets and variables > Actions, add secrets:
DEPLOY_HOST: VM IP or host nameDEPLOY_USER: deploy userDEPLOY_SSH_KEY: private half of the SSH keyDEPLOY_PATH: deploy folder, for example/opt/junction
- Variables:
DEPLOY_FROZENset tofalse(settrueto freeze). - Branch protection on
main: require PR and thebackend,frontendandinfrachecks. Private repos need a paid plan for this.
Copyright (c) 2026 Anvik. All rights reserved. See LICENSE.
Valio Aimo for the challenge, the mock APIs and the product data. Junction for the hackathon.






