InsumerAPI

Overview Schema Source Related Servers Discussions Admin

Discount in UCP format

insumer_ucp_discount

Check token-holder discount eligibility in Google Universal Commerce Protocol (UCP) format. Returns title, extension field, and applied array compatible with UCP checkout flows.

Instructions

Check token-holder discount eligibility in Google Universal Commerce Protocol (UCP) format. Returns title, extension field, and applied array compatible with UCP checkout flows. The on-chain check is the same one behind INSR discount codes, wrapped in UCP format. A code that carries a discount costs one credit from the API key that owns the store; a 0% result is free. A caller using another key is not charged, and stores on a licensed platform are covered by its license. Paid discount codes requested with a key other than the store's owner are subject to an hourly limit (429; the message says when to try again). Takes an EVM, Solana or XRPL wallet. An rpc_failure error (503) means a read did not complete and nothing was signed: retry, and never treat it as a no. Optional walletProof proves you control the EVM wallet: the response then says walletProven true, and the full discount its holdings earn applies, without the store's daily limit for unproven wallets. Without it the store's terms for unproven wallets apply, and discountIfProven shows what a proof would get.

Input Schema

TableJSON Schema

Name	Required	Description
`items`	No	Optional line items for per-item cent-amount allocations
`wallet`	No	EVM wallet address (0x...)
`merchantId`	Yes	Merchant ID
`xrplWallet`	No	XRPL wallet address (r-address)
`walletProof`	No	Optional proof that you control 'wallet' (EVM only; send it without solanaWallet or xrplWallet). Sign this EIP-4361 message with the wallet, within 5 minutes, with a nonce you never reused: api.insumermodel.com wants you to sign in with your Ethereum account: <wallet> Prove wallet for a discount. URI: https://api.insumermodel.com/v1/merchants/<merchantId> Version: 1 Chain ID: 1 Nonce: <8+ random letters or digits> Issued At: <ISO 8601 time now> A proven wallet gets the full discount its holdings earn (under the store's tiers and cap), without the daily limit for unproven wallets. Without it, the store's terms for unproven wallets apply (see walletTerms on the merchant). A proof that fails returns 401 and uses no credit. Smart-contract wallets are not accepted yet.
`solanaWallet`	No	Solana wallet address (base58)

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	No	true when the API call succeeded
`data`	No	The endpoint's payload: a signed attestation, trust profile, discount, merchant or token records
`keys`	No	JWKS entries (insumer_jwks)
`meta`	No	Response metadata such as version and timestamp
`error`	No	Error details when ok is false
`items`	No	The result when the endpoint returns a JSON array
`message`	No	A plain-text result (insumer_setup), or a message from the API

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.17.1Oct 6, 2026

removedInput schema / properties / stellarWallet

Removed value: -{
-  "description": "Stellar wallet address (G-prefixed)",
-  "pattern": "^G[A-Z2-7]{55}$",
-  "type": "string"
-}

removedInput schema / properties / suiWallet

Removed value: -{
-  "description": "Sui wallet address (0x + 64 hex)",
-  "pattern": "^0x[0-9a-fA-F]{64}$",
-  "type": "string"
-}

removedInput schema / properties / tronWallet

Removed value: -{
-  "description": "Tron wallet address (T-prefixed)",
-  "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$",
-  "type": "string"
-}

addedInput schema / properties / walletProof

Added value: +{
+  "additionalProperties": false,
+  "description": "Optional proof that you control 'wallet' (EVM only; send it without solanaWallet or xrplWallet). Sign this EIP-4361 message with the wallet, within 5 minutes, with a nonce you never reused:\napi.insumermodel.com wants you to sign in with your Ethereum account:\n<wallet>\n\nProve wallet for a discount.\n\nURI: https://api.insumermodel.com/v1/merchants/<merchantId>\nVersion: 1\nChain ID: 1\nNonce: <8+ random letters or digits>\nIssued At: <ISO 8601 time now>\nA proven wallet gets the full discount its holdings earn (under the store's tiers and cap), without the daily limit for unproven wallets. Without it, the store's terms for unproven wallets apply (see walletTerms on the merchant). A proof that fails returns 401 and uses no credit. Smart-contract wallets are not accepted yet.",
+  "properties": {
+    "message": {
+      "description": "The EIP-4361 message, exactly as signed",
+      "maxLength": 4096,
+      "type": "string"
+    },
+    "signature": {
+      "description": "The wallet's personal_sign (EIP-191) signature over the message",
+      "maxLength": 2000,
+      "pattern": "^0x[0-9a-fA-F]+$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "message",
+    "signature"
+  ],
+  "type": "object"
+}

Changed12 schema fields changedv1.16.0Oct 4, 2026

addedInput schema / properties / items / items / properties / path / maxLength
```
Added value: +200
```
addedInput schema / properties / items / maxItems
```
Added value: +100
```
addedInput schema / properties / merchantId / maxLength
```
Added value: +100
```
addedInput schema / properties / merchantId / minLength
```
Added value: +1
```
addedInput schema / properties / merchantId / pattern
```
Added value: +"^[a-zA-Z0-9_-]+$"
```
addedInput schema / properties / solanaWallet / pattern
```
Added value: +"^[1-9A-HJ-NP-Za-km-z]{32,44}$"
```

addedInput schema / properties / stellarWallet

Added value: +{
+  "description": "Stellar wallet address (G-prefixed)",
+  "pattern": "^G[A-Z2-7]{55}$",
+  "type": "string"
+}

addedInput schema / properties / suiWallet

Added value: +{
+  "description": "Sui wallet address (0x + 64 hex)",
+  "pattern": "^0x[0-9a-fA-F]{64}$",
+  "type": "string"
+}

addedInput schema / properties / tronWallet

Added value: +{
+  "description": "Tron wallet address (T-prefixed)",
+  "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$",
+  "type": "string"
+}

addedInput schema / properties / wallet / pattern
```
Added value: +"^0x[0-9a-fA-F]{40}$"
```
addedInput schema / properties / xrplWallet / pattern
```
Added value: +"^r[1-9A-HJ-NP-Za-km-z]{24,34}$"
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "data": {
+      "description": "The endpoint's payload: a signed attestation, trust profile, discount, merchant or token records"
+    },
+    "error": {
+      "description": "Error details when ok is false"
+    },
+    "items": {
+      "description": "The result when the endpoint returns a JSON array",
+      "items": {},
+      "type": "array"
+    },
+    "keys": {
+      "description": "JWKS entries (insumer_jwks)",
+      "items": {},
+      "type": "array"
+    },
+    "message": {
+      "description": "A plain-text result (insumer_setup), or a message from the API"
+    },
+    "meta": {
+      "description": "Response metadata such as version and timestamp"
+    },
+    "ok": {
+      "description": "true when the API call succeeded",
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}

Addedv0.1.0Apr 28, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond the annotations: credit costs (one credit when a discount applies, free at 0%), key-ownership and licensed-platform billing rules, an hourly rate limit with 429 semantics, 503 rpc_failure meaning 'nothing signed, retry, never treat as no,' and the effect of walletProof versus its absence. This is well past the readOnlyHint=false/openWorldHint baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then layers billing, error, and proof behavior; nearly every sentence carries information an agent needs. It is a dense single paragraph, however, and could be more scannable with bullets, slightly hurting structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter, nested-object tool with an output schema, the description covers what the schema cannot: billing/key rules, rate limits, error semantics, and walletProof consequences. Return values are described in brief and the output schema covers the rest, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the structured fields already carry most parameter meaning. The description nonetheless explains material semantics the schema alone implies only partly: accepted chains (EVM, Solana, XRPL) and precisely how walletProof changes the returned discount and daily-limit treatment.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Check token-holder discount eligibility') and pins the output format to Google UCP, immediately signaling its distinction from the ACP sibling and the generic insumer_check_discount. It also names the concrete return payload (title, extension field, applied array). An agent can differentiate it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Context is clear: use it when the checkout flow speaks UCP, since it is the same on-chain check as INSR discount codes 'wrapped in UCP format.' It does not explicitly name the alternative (insumer_acp_discount or insumer_check_discount) or state when-not to use this one, so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.