AI agents are starting to shop autonomously. They browse product catalogs, compare prices, and complete purchases. But how does a merchant verify that the agent's user actually holds the tokens that qualify for a discount? This tutorial walks through the full flow: discover a merchant, verify on-chain eligibility, get a UCP discount, and validate the code at checkout.
The Problem
An AI shopping agent finds a merchant that offers 15% off to UNI holders. The agent knows the user's wallet address. But how does it prove the user holds UNI without exposing the wallet's full portfolio? And how does the merchant trust the discount code the agent presents?
This is where on-chain verification fits into agent commerce. An attestation authority like InsumerAPI sits between the agent and the blockchain. It verifies holdings on-chain, returns a signed boolean result (eligible or not), and issues a time-limited discount code. The merchant validates the code at checkout without needing blockchain access.
Step 1: Discover Available Merchants
The agent starts by browsing the merchant directory. This is a free, public endpoint:
import requests
BASE = "https://api.insumermodel.com"
KEY = "insr_live_YOUR_KEY_HERE"
# List merchants that recognize UNI token
merchants = requests.get(
f"{BASE}/v1/merchants",
params={"token": "UNI", "verified": "true"},
headers={"X-API-Key": KEY},
).json()
for m in merchants["data"]:
print(f"{m['companyName']} ({m['id']})")
for token in m.get("tokens", []):
print(f" {token['symbol']}: up to {token['maxDiscount']}% off")
The agent now has a list of merchants, their IDs, and the token tiers they offer. It can choose the best deal for the user.
Step 2: Check Discount Eligibility
Before requesting a formal discount code, the agent can do a free eligibility check:
# Free check, no credits consumed
eligibility = requests.get(
f"{BASE}/v1/discount/check",
params={
"merchant": "demo-coffee-shop",
"wallet": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
},
).json()
if eligibility["data"]["eligible"]:
print(f"Eligible for {eligibility['data']['totalDiscount']}% off")
else:
print("Not eligible for this merchant")
This costs nothing. The agent can check multiple merchants before committing to a verification.
Step 3: Request a UCP Discount
The user qualifies. Now the agent requests a formal discount in Google UCP format. This consumes 1 merchant credit and triggers the on-chain verification:
ucp = requests.post(
f"{BASE}/v1/ucp/discount",
headers={"X-API-Key": KEY, "Content-Type": "application/json"},
json={
"merchantId": "demo-coffee-shop",
"wallet": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
"items": [
{"path": "cart/espresso", "amount": 450},
{"path": "cart/pastry", "amount": 350},
],
},
).json()
print(ucp)
The UCP response:
{
"ok": true,
"data": {
"protocol": "ucp",
"version": "2026-01-11",
"extension": "dev.ucp.shopping.discount",
"discounts": {
"codes": ["INSR-B9M2K"],
"applied": [
{
"code": "INSR-B9M2K",
"title": "Token Holder Discount — 15% Off",
"amount": 120,
"automatic": false,
"method": "across",
"priority": 10,
"allocations": [
{"path": "cart/espresso", "amount": 68},
{"path": "cart/pastry", "amount": 52}
]
}
]
},
"verification": {
"code": "INSR-B9M2K",
"expiresAt": "2026-02-27T12:30:00.000Z",
"sig": "MEYCIQDx...base64...",
"kid": "insumer-attest-v1"
}
},
"meta": {
"version": "1.0",
"timestamp": "2026-02-27T12:00:01.000Z",
"creditsCharged": 1,
"creditsRemaining": 94
}
}
Key UCP-specific fields:
- **`extension`**: `dev.ucp.shopping.discount` identifies this as a UCP shopping discount for Google's commerce routing.
- **`title`**: A human-readable discount description (UCP uses this instead of ACP's coupon object).
- **`allocations`**: Per-item discount amounts, calculated from the `items` array you sent.
- **`verification.sig`**: ECDSA P-256 signature. The merchant can verify this against the public key at `/.well-known/jwks.json`.
Step 4: Agent Applies the Discount
The agent now has everything it needs to apply the discount in the checkout flow:
if ucp["ok"] and ucp["data"]["discounts"]["applied"]:
discount = ucp["data"]["discounts"]["applied"][0]
code = discount["code"]
title = discount["title"]
amount = discount.get("amount", 0)
expiry = ucp["data"]["verification"]["expiresAt"]
print(f"Applying: {title}")
print(f"Discount code: {code}")
print(f"Savings: ${amount / 100:.2f}")
print(f"Valid until: {expiry}")
# Agent presents code to merchant checkout
checkout_payload = {
"discount_code": code,
"cart_items": [
{"path": "cart/espresso", "amount": 450},
{"path": "cart/pastry", "amount": 350},
],
}
else:
print("No discount available")
Step 5: Merchant Validates the Code
On the merchant side, the backend validates the code before applying the discount. This endpoint is public. No API key required:
# Merchant backend (server-side)
validation = requests.get(f"{BASE}/v1/codes/INSR-B9M2K").json()
if validation["data"]["valid"]:
pct = validation["data"]["discountPercent"]
mid = validation["data"]["merchantId"]
exp = validation["data"]["expiresAt"]
print(f"Code valid: {pct}% off for merchant {mid}")
print(f"Expires: {exp}")
# Apply discount to order
else:
reason = validation["data"]["reason"]
print(f"Code rejected: {reason}")
# reason is "expired", "already_used", or "not_found"
The merchant should verify three things:
- **`valid` is `true`**
- **`merchantId` matches their own ID** (prevents code reuse across merchants)
- **`expiresAt` is in the future** (codes are valid for 30 minutes)
UCP Discovery for Automated Agents
Google UCP agents can discover InsumerAPI automatically via the UCP discovery file:
GET https://insumermodel.com/.well-known/ucp.json
This returns the endpoint URL, authentication method, and capabilities:
{
"name": "InsumerAPI",
"capabilities": ["dev.ucp.shopping.discount"],
"endpoints": {
"discount": {
"method": "POST",
"path": "/v1/ucp/discount",
"authentication": {
"type": "custom",
"header": "X-API-Key"
}
},
"validate_code": {
"method": "GET",
"path": "/v1/codes/{code}",
"authentication": { "type": "none" }
}
},
"signing": {
"algorithm": "ES256",
"kid": "insumer-attest-v1",
"jwks_uri": "https://insumermodel.com/.well-known/jwks.json"
}
}
An agent using UCP discovery can find the endpoint, call it, and validate codes without any hardcoded URLs.
For the complete commerce integration surface, including ACP and UCP endpoints, code validation, and merchant configuration, see the AI Agent Verification API overview, the commerce developer guide, and the full OpenAPI 3.1 spec.
Why This Matters for Agent Commerce
Privacy by default. The agent sends a wallet address. InsumerAPI verifies holdings on-chain and returns a boolean result with a discount percentage. No token quantities, no portfolio composition, no PII. The merchant learns "this wallet qualifies for 15% off" and nothing else.
Cryptographic trust. Every discount code is ECDSA-signed. The merchant does not need to trust the agent. They verify the signature against a public key. The on-chain state is the ground truth. The signature proves the attestation authority checked it.
Protocol-native output. Agents built on Google's commerce stack consume UCP responses directly. Agents built on OpenAI's stack use the ACP endpoint instead. Same verification, different response shape.
30-minute codes. Discount codes expire after 30 minutes. They cannot be stockpiled, shared, or replayed. Each code is single-use and tied to a specific merchant.
A forkable reference repository with all examples is available at acp-ucp-onchain-eligibility-example on GitHub.
, before CTA) -->
Share this article
[
Share on X
](#)
[
LinkedIn
](#)
[
Reddit
](#)
Discord
Copy Link
InsumerAPI is free to start. Get an API key and try it. View API Docs
Top comments (0)