InsumerAPI

Overview Schema Source Related Servers Discussions Admin

Create a discount code

insumer_verify

Create a signed discount code (INSR-XXXXX, 30-minute expiry) for a wallet at a merchant. Returns tier and discount percentage, never raw balance amounts.

Instructions

Create a signed discount code (INSR-XXXXX, 30-minute expiry) for a wallet at a merchant. Returns tier and discount percentage, never raw balance amounts. 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). If the merchant has Stripe Connect, a coupon is auto-created. Takes an EVM, Solana or XRPL wallet. An rpc_failure error (503) means a read did not complete and no code was issued: 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
`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"
+}

Changed10 schema fields changedv1.16.0Oct 4, 2026

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?

Annotations only mark this as non-read-only, non-idempotent, open-world. The description goes far beyond: credit consumption rules and exemptions, an hourly rate limit with 429 behavior, the rpc_failure 503 'retry, never treat as no' semantics, 401 on failed proof with no credit used, and auto-creation of a Stripe coupon. That is exactly the operational context annotations cannot express.

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, cost, and expiry are front-loaded in sentence one, and most subsequent sentences carry distinct operational facts (billing, rate limits, error codes, proof effects). It is dense and slightly overpacked — the Stripe Connect and licensing sentences could be tightened — but there is little pure filler.

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 mutation tool with an output schema, nested walletProof object, and open-world behavior, the description covers cost, error semantics, proof-vs-unproven tradeoffs, and wallet type support. Nothing an agent needs to invoke it correctly appears to be missing, and return values are appropriately left to the output schema.

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 baseline is 3, but the description adds real meaning: which wallet families are accepted, and that walletProof changes the response (walletProven true), removes the store's unproven-wallet daily limit, and yields discountIfProven otherwise. It does not add syntax detail beyond the schema's EIP-4361 block, which is fine since the schema already covers it.

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 opening sentence gives a precise verb+resource+output format: 'Create a signed discount code (INSR-XXXXX, 30-minute expiry) for a wallet at a merchant.' An agent can tell this is a code-issuing tool, not a read/check tool. It does not, however, explicitly distinguish itself from close siblings such as insumer_validate_code, insumer_check_discount, or the acp/ucp discount variants.

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 strong conditional context: when a credit is charged, when other keys are exempt, what the hourly 429 means, and when to send walletProof versus relying on unproven-wallet terms. What is missing is explicit routing against alternatives (e.g., why create a code here rather than call check_discount or validate_code), so it falls short of the 5 bar.

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