InsumerAPI

Overview Schema Source Related Servers Discussions Admin

Discount in ACP format

insumer_acp_discount

Instructions

Check token-holder discount eligibility in OpenAI/Stripe Agentic Commerce Protocol (ACP) format. Returns coupon objects, applied/rejected arrays, and per-item allocations compatible with ACP checkout flows. The on-chain check is the same one behind INSR discount codes, wrapped in ACP 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.3/5.0

Behavior5/5

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

Goes well beyond the annotations, which only say readOnly=false/idempotent=false. It discloses the credit cost model, free-result conditions, an hourly limit producing 429, and distinct error handling (503 rpc_failure means retry and never treat as a 'no'; 401 proof failure uses no credit). The walletProof behavior (full discount, no daily limit, walletProven/discountIfProven response fields) is spelled out in detail.

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?

The purpose and output are front-loaded in the opening sentences, and nearly every sentence carries distinct operational information rather than filler. It is dense and reads as one long block, so a light structure penalty applies, but nothing is wasted.

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?

Despite six parameters, a nested object, and billing/error/rate-limit complexity, the description covers cost, limits, errors, wallet variants, and the proof path. Because an output schema already exists, it is not obligated to describe return payloads, yet it still names the key response fields an agent will act on.

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 already 100%, which sets a baseline of 3, but the description adds genuine meaning beyond the schema by explaining what walletProof changes (daily limit removal, walletProven true) and what happens without it. The supported wallet chains (EVM/Solana/XRPL) are also stated, though merchantId and items parameters get no extra narrative.

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

Purpose4/5

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

The description names a specific verb and resource ('Check token-holder discount eligibility') and pins the output format ('ACPC format'), tying it to the ACP checkout flow. It implies a distinction from its UCP/plain-check siblings ('the same check ... wrapped in ACP format') but never names them, so an agent must infer which sibling to prefer.

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?

It gives rich context on when this call is charged vs free (0% result is free, other keys are not charged, licensed platforms are covered) and when a 429 applies. It does not, however, explicitly route the agent between this and the sibling insumer_ucp_discount or insumer_check_discount.

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