langchain-insumer 0.1.0__tar.gz

langchain_insumer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Insumer Model
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_insumer-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: langchain-insumer
+Version: 0.1.0
+Summary: LangChain integration for The Insumer Model — privacy-preserving on-chain attestation across 31 blockchains
+Author-email: The Insumer Model <contact@insumermodel.com>
+License: MIT
+Project-URL: Homepage, https://insumermodel.com/for-agents/
+Project-URL: Documentation, https://insumermodel.com/llms-full.txt
+Project-URL: Repository, https://github.com/douglasborthwick-crypto/langchain-insumer
+Project-URL: API Reference, https://insumermodel.com/openapi.yaml
+Project-URL: Bug Tracker, https://github.com/douglasborthwick-crypto/langchain-insumer/issues
+Keywords: langchain,blockchain,attestation,token-gated,nft,web3,privacy,on-chain,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain-core>=0.2.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# langchain-insumer
+
+LangChain integration for [The Insumer Model](https://insumermodel.com) Attestation API.
+
+Verify on-chain token balances and NFT ownership across 31 blockchains with privacy-preserving attestations. Returns only true/false — never exposes actual wallet balances.
+
+## Installation
+
+```bash
+pip install langchain-insumer
+```
+
+## Quick Start
+
+```python
+from langchain_insumer import InsumerAPIWrapper, InsumerAttestTool
+
+# Initialize the API wrapper
+api = InsumerAPIWrapper(api_key="insr_live_YOUR_KEY_HERE")
+
+# Create tools for your agent
+attest_tool = InsumerAttestTool(api_wrapper=api)
+
+# Use with a LangChain agent
+from langchain.agents import initialize_agent, AgentType
+from langchain_openai import ChatOpenAI
+
+llm = ChatOpenAI(model="gpt-4")
+tools = [attest_tool]
+agent = initialize_agent(tools, llm, agent=AgentType.OPENAI_FUNCTIONS)
+
+agent.run("Does wallet 0x1234... hold at least 100 USDC on Ethereum?")
+```
+
+## Available Tools
+
+| Tool | Description | Credits |
+|------|-------------|---------|
+| `InsumerAttestTool` | Verify on-chain conditions with signed attestation | 1/call |
+| `InsumerCheckDiscountTool` | Calculate discount for wallet at merchant | Free |
+| `InsumerListMerchantsTool` | Browse merchant directory | Free |
+| `InsumerListTokensTool` | List registered tokens and NFTs | Free |
+| `InsumerVerifyTool` | Create signed discount code (INSR-XXXXX) | 1/call |
+| `InsumerCreditsTool` | Check API key credit balance | Free |
+
+## Using All Tools
+
+```python
+from langchain_insumer import (
+    InsumerAPIWrapper,
+    InsumerAttestTool,
+    InsumerCheckDiscountTool,
+    InsumerCreditsTool,
+    InsumerListMerchantsTool,
+    InsumerListTokensTool,
+    InsumerVerifyTool,
+)
+
+api = InsumerAPIWrapper(api_key="insr_live_YOUR_KEY_HERE")
+
+tools = [
+    InsumerAttestTool(api_wrapper=api),
+    InsumerCheckDiscountTool(api_wrapper=api),
+    InsumerCreditsTool(api_wrapper=api),
+    InsumerListMerchantsTool(api_wrapper=api),
+    InsumerListTokensTool(api_wrapper=api),
+    InsumerVerifyTool(api_wrapper=api),
+]
+```
+
+## Attestation Example
+
+```python
+import json
+
+api = InsumerAPIWrapper(api_key="insr_live_YOUR_KEY_HERE")
+
+result = api.attest(
+    wallet="0x1234567890abcdef1234567890abcdef12345678",
+    conditions=[
+        {
+            "type": "token_balance",
+            "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+            "chainId": 1,
+            "threshold": 1000,
+            "decimals": 6,
+            "label": "USDC >= 1000 on Ethereum",
+        },
+        {
+            "type": "nft_ownership",
+            "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
+            "chainId": 1,
+            "label": "Bored Ape Yacht Club holder",
+        },
+    ],
+)
+
+attestation = result["data"]["attestation"]
+print(f"Pass: {attestation['pass']}")
+for r in attestation["results"]:
+    print(f"  {r['label']}: {'met' if r['met'] else 'not met'}")
+print(f"Signature: {result['data']['sig']}")
+```
+
+## Supported Chains (31)
+
+Ethereum, BNB Chain, Base, Avalanche, Polygon, Arbitrum, Optimism, Solana, Chiliz, Soneium, Plume, Sonic, Gnosis, Mantle, Scroll, Linea, zkSync Era, Blast, Taiko, Ronin, Celo, Moonbeam, Moonriver, Viction, opBNB, World Chain, Unichain, Ink, Sei, Berachain, ApeChain.
+
+## Get an API Key
+
+- **Free** (10 credits): [insumermodel.com/developers](https://insumermodel.com/developers/)
+- **Pro** (10,000/day): 29 USDC/month
+- **Enterprise** (100,000/day): 99 USDC/month
+
+## Links
+
+- [API Documentation](https://insumermodel.com/for-agents/)
+- [OpenAPI Spec](https://insumermodel.com/openapi.yaml)
+- [Full API Reference](https://insumermodel.com/llms-full.txt)
+
+## License
+
+MIT

langchain_insumer-0.1.0/README.md

@@ -0,0 +1,123 @@
+# langchain-insumer
+
+LangChain integration for [The Insumer Model](https://insumermodel.com) Attestation API.
+
+Verify on-chain token balances and NFT ownership across 31 blockchains with privacy-preserving attestations. Returns only true/false — never exposes actual wallet balances.
+
+## Installation
+
+```bash
+pip install langchain-insumer
+```
+
+## Quick Start
+
+```python
+from langchain_insumer import InsumerAPIWrapper, InsumerAttestTool
+
+# Initialize the API wrapper
+api = InsumerAPIWrapper(api_key="insr_live_YOUR_KEY_HERE")
+
+# Create tools for your agent
+attest_tool = InsumerAttestTool(api_wrapper=api)
+
+# Use with a LangChain agent
+from langchain.agents import initialize_agent, AgentType
+from langchain_openai import ChatOpenAI
+
+llm = ChatOpenAI(model="gpt-4")
+tools = [attest_tool]
+agent = initialize_agent(tools, llm, agent=AgentType.OPENAI_FUNCTIONS)
+
+agent.run("Does wallet 0x1234... hold at least 100 USDC on Ethereum?")
+```
+
+## Available Tools
+
+| Tool | Description | Credits |
+|------|-------------|---------|
+| `InsumerAttestTool` | Verify on-chain conditions with signed attestation | 1/call |
+| `InsumerCheckDiscountTool` | Calculate discount for wallet at merchant | Free |
+| `InsumerListMerchantsTool` | Browse merchant directory | Free |
+| `InsumerListTokensTool` | List registered tokens and NFTs | Free |
+| `InsumerVerifyTool` | Create signed discount code (INSR-XXXXX) | 1/call |
+| `InsumerCreditsTool` | Check API key credit balance | Free |
+
+## Using All Tools
+
+```python
+from langchain_insumer import (
+    InsumerAPIWrapper,
+    InsumerAttestTool,
+    InsumerCheckDiscountTool,
+    InsumerCreditsTool,
+    InsumerListMerchantsTool,
+    InsumerListTokensTool,
+    InsumerVerifyTool,
+)
+
+api = InsumerAPIWrapper(api_key="insr_live_YOUR_KEY_HERE")
+
+tools = [
+    InsumerAttestTool(api_wrapper=api),
+    InsumerCheckDiscountTool(api_wrapper=api),
+    InsumerCreditsTool(api_wrapper=api),
+    InsumerListMerchantsTool(api_wrapper=api),
+    InsumerListTokensTool(api_wrapper=api),
+    InsumerVerifyTool(api_wrapper=api),
+]
+```
+
+## Attestation Example
+
+```python
+import json
+
+api = InsumerAPIWrapper(api_key="insr_live_YOUR_KEY_HERE")
+
+result = api.attest(
+    wallet="0x1234567890abcdef1234567890abcdef12345678",
+    conditions=[
+        {
+            "type": "token_balance",
+            "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+            "chainId": 1,
+            "threshold": 1000,
+            "decimals": 6,
+            "label": "USDC >= 1000 on Ethereum",
+        },
+        {
+            "type": "nft_ownership",
+            "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
+            "chainId": 1,
+            "label": "Bored Ape Yacht Club holder",
+        },
+    ],
+)
+
+attestation = result["data"]["attestation"]
+print(f"Pass: {attestation['pass']}")
+for r in attestation["results"]:
+    print(f"  {r['label']}: {'met' if r['met'] else 'not met'}")
+print(f"Signature: {result['data']['sig']}")
+```
+
+## Supported Chains (31)
+
+Ethereum, BNB Chain, Base, Avalanche, Polygon, Arbitrum, Optimism, Solana, Chiliz, Soneium, Plume, Sonic, Gnosis, Mantle, Scroll, Linea, zkSync Era, Blast, Taiko, Ronin, Celo, Moonbeam, Moonriver, Viction, opBNB, World Chain, Unichain, Ink, Sei, Berachain, ApeChain.
+
+## Get an API Key
+
+- **Free** (10 credits): [insumermodel.com/developers](https://insumermodel.com/developers/)
+- **Pro** (10,000/day): 29 USDC/month
+- **Enterprise** (100,000/day): 99 USDC/month
+
+## Links
+
+- [API Documentation](https://insumermodel.com/for-agents/)
+- [OpenAPI Spec](https://insumermodel.com/openapi.yaml)
+- [Full API Reference](https://insumermodel.com/llms-full.txt)
+
+## License
+
+MIT

langchain_insumer-0.1.0/langchain_insumer/__init__.py

@@ -0,0 +1,19 @@
+"""LangChain integration for The Insumer Model Attestation API."""
+
+from langchain_insumer.tools.attest import InsumerAttestTool
+from langchain_insumer.tools.check_discount import InsumerCheckDiscountTool
+from langchain_insumer.tools.credits import InsumerCreditsTool
+from langchain_insumer.tools.list_merchants import InsumerListMerchantsTool
+from langchain_insumer.tools.list_tokens import InsumerListTokensTool
+from langchain_insumer.tools.verify import InsumerVerifyTool
+from langchain_insumer.wrapper import InsumerAPIWrapper
+
+__all__ = [
+    "InsumerAPIWrapper",
+    "InsumerAttestTool",
+    "InsumerCheckDiscountTool",
+    "InsumerCreditsTool",
+    "InsumerListMerchantsTool",
+    "InsumerListTokensTool",
+    "InsumerVerifyTool",
+]

langchain_insumer-0.1.0/langchain_insumer/tools/__init__.py

@@ -0,0 +1,17 @@
+"""Insumer Model tools for LangChain agents."""
+
+from langchain_insumer.tools.attest import InsumerAttestTool
+from langchain_insumer.tools.check_discount import InsumerCheckDiscountTool
+from langchain_insumer.tools.credits import InsumerCreditsTool
+from langchain_insumer.tools.list_merchants import InsumerListMerchantsTool
+from langchain_insumer.tools.list_tokens import InsumerListTokensTool
+from langchain_insumer.tools.verify import InsumerVerifyTool
+
+__all__ = [
+    "InsumerAttestTool",
+    "InsumerCheckDiscountTool",
+    "InsumerCreditsTool",
+    "InsumerListMerchantsTool",
+    "InsumerListTokensTool",
+    "InsumerVerifyTool",
+]

langchain_insumer-0.1.0/langchain_insumer/tools/attest.py

@@ -0,0 +1,72 @@
+"""Tool for creating privacy-preserving on-chain attestations."""
+
+import json
+from typing import Any, Optional, Type
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from langchain_insumer.wrapper import InsumerAPIWrapper
+
+
+class AttestSchema(BaseModel):
+    """Input for InsumerAttestTool."""
+
+    wallet: Optional[str] = Field(
+        default=None,
+        description="EVM wallet address (0x...) to verify.",
+    )
+    solana_wallet: Optional[str] = Field(
+        default=None,
+        description="Solana wallet address (base58) to verify.",
+    )
+    conditions: str = Field(
+        description=(
+            'JSON array of conditions. Each condition: {"type": "token_balance" or '
+            '"nft_ownership", "contractAddress": "0x...", "chainId": 1, '
+            '"threshold": 1000, "decimals": 6, "label": "USDC >= 1000"}. '
+            "Supported chains: Ethereum (1), BNB (56), Base (8453), Polygon (137), "
+            "Arbitrum (42161), Optimism (10), Avalanche (43114), Solana (\"solana\"), "
+            "and 23 more. Max 10 conditions per call."
+        ),
+    )
+
+
+class InsumerAttestTool(BaseTool):
+    """Verify on-chain token balances or NFT ownership with a signed attestation.
+
+    Returns only true/false per condition -- never exposes actual balances.
+    The response includes an ECDSA P-256 signature for cryptographic proof.
+    Costs 1 attestation credit per call.
+    """
+
+    name: str = "insumer_attest"
+    description: str = (
+        "Verify on-chain conditions (token balances, NFT ownership) across 31 "
+        "blockchains. Returns a cryptographically signed true/false attestation "
+        "without exposing actual wallet balances. Use this when you need to check "
+        "if a wallet holds a specific token or NFT. Costs 1 attestation credit."
+    )
+    args_schema: Type[AttestSchema] = AttestSchema
+
+    api_wrapper: InsumerAPIWrapper = Field(..., exclude=True)
+
+    def __init__(self, api_wrapper: InsumerAPIWrapper) -> None:
+        super().__init__(api_wrapper=api_wrapper)
+
+    def _run(
+        self,
+        conditions: str,
+        wallet: Optional[str] = None,
+        solana_wallet: Optional[str] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        """Execute the attestation."""
+        parsed_conditions: list[dict[str, Any]] = json.loads(conditions)
+        result = self.api_wrapper.attest(
+            conditions=parsed_conditions,
+            wallet=wallet,
+            solana_wallet=solana_wallet,
+        )
+        return json.dumps(result, indent=2)

langchain_insumer-0.1.0/langchain_insumer/tools/check_discount.py

@@ -0,0 +1,60 @@
+"""Tool for checking wallet discount eligibility at a merchant."""
+
+import json
+from typing import Optional, Type
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from langchain_insumer.wrapper import InsumerAPIWrapper
+
+
+class CheckDiscountSchema(BaseModel):
+    """Input for InsumerCheckDiscountTool."""
+
+    merchant_id: str = Field(description="Merchant ID to check discount at.")
+    wallet: Optional[str] = Field(
+        default=None,
+        description="EVM wallet address (0x...).",
+    )
+    solana_wallet: Optional[str] = Field(
+        default=None,
+        description="Solana wallet address (base58).",
+    )
+
+
+class InsumerCheckDiscountTool(BaseTool):
+    """Calculate the discount a wallet qualifies for at a specific merchant.
+
+    Checks on-chain balances server-side and returns the total discount
+    percentage with a breakdown by token. Free to call, no credits consumed.
+    """
+
+    name: str = "insumer_check_discount"
+    description: str = (
+        "Calculate what discount a wallet qualifies for at a specific merchant. "
+        "Checks on-chain token balances and returns the discount percentage "
+        "with a breakdown by token tier. Free to call, no credits consumed."
+    )
+    args_schema: Type[CheckDiscountSchema] = CheckDiscountSchema
+
+    api_wrapper: InsumerAPIWrapper = Field(..., exclude=True)
+
+    def __init__(self, api_wrapper: InsumerAPIWrapper) -> None:
+        super().__init__(api_wrapper=api_wrapper)
+
+    def _run(
+        self,
+        merchant_id: str,
+        wallet: Optional[str] = None,
+        solana_wallet: Optional[str] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        """Check the discount."""
+        result = self.api_wrapper.check_discount(
+            merchant_id=merchant_id,
+            wallet=wallet,
+            solana_wallet=solana_wallet,
+        )
+        return json.dumps(result, indent=2)

langchain_insumer-0.1.0/langchain_insumer/tools/credits.py

@@ -0,0 +1,40 @@
+"""Tool for checking attestation credit balance."""
+
+import json
+from typing import Optional, Type
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from langchain_insumer.wrapper import InsumerAPIWrapper
+
+
+class CreditsSchema(BaseModel):
+    """Input for InsumerCreditsTool. No parameters required."""
+
+    pass
+
+
+class InsumerCreditsTool(BaseTool):
+    """Check the attestation credit balance for the current API key."""
+
+    name: str = "insumer_credits"
+    description: str = (
+        "Check the attestation credit balance, tier, and daily rate limit "
+        "for the current Insumer API key. No parameters needed."
+    )
+    args_schema: Type[CreditsSchema] = CreditsSchema
+
+    api_wrapper: InsumerAPIWrapper = Field(..., exclude=True)
+
+    def __init__(self, api_wrapper: InsumerAPIWrapper) -> None:
+        super().__init__(api_wrapper=api_wrapper)
+
+    def _run(
+        self,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        """Check credits."""
+        result = self.api_wrapper.get_credits()
+        return json.dumps(result, indent=2)

langchain_insumer-0.1.0/langchain_insumer/tools/list_merchants.py

@@ -0,0 +1,66 @@
+"""Tool for listing merchants in the public directory."""
+
+import json
+from typing import Optional, Type
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from langchain_insumer.wrapper import InsumerAPIWrapper
+
+
+class ListMerchantsSchema(BaseModel):
+    """Input for InsumerListMerchantsTool."""
+
+    token: Optional[str] = Field(
+        default=None,
+        description="Filter by accepted token symbol (e.g. UNI, SHIB).",
+    )
+    verified: Optional[bool] = Field(
+        default=None,
+        description="Filter by domain verification status.",
+    )
+    limit: int = Field(
+        default=50,
+        description="Results per page (max 200).",
+    )
+    offset: int = Field(
+        default=0,
+        description="Pagination offset.",
+    )
+
+
+class InsumerListMerchantsTool(BaseTool):
+    """Browse merchants that offer token-gated discounts."""
+
+    name: str = "insumer_list_merchants"
+    description: str = (
+        "List merchants in The Insumer Model directory that offer discounts "
+        "to token holders. Optionally filter by accepted token symbol or "
+        "verification status. Returns merchant names, locations, accepted "
+        "tokens, and discount structures."
+    )
+    args_schema: Type[ListMerchantsSchema] = ListMerchantsSchema
+
+    api_wrapper: InsumerAPIWrapper = Field(..., exclude=True)
+
+    def __init__(self, api_wrapper: InsumerAPIWrapper) -> None:
+        super().__init__(api_wrapper=api_wrapper)
+
+    def _run(
+        self,
+        token: Optional[str] = None,
+        verified: Optional[bool] = None,
+        limit: int = 50,
+        offset: int = 0,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        """List merchants."""
+        result = self.api_wrapper.list_merchants(
+            token=token,
+            verified=verified,
+            limit=limit,
+            offset=offset,
+        )
+        return json.dumps(result, indent=2)

langchain_insumer-0.1.0/langchain_insumer/tools/list_tokens.py

@@ -0,0 +1,59 @@
+"""Tool for listing registered tokens and NFT collections."""
+
+import json
+from typing import Any, Optional, Type
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from langchain_insumer.wrapper import InsumerAPIWrapper
+
+
+class ListTokensSchema(BaseModel):
+    """Input for InsumerListTokensTool."""
+
+    chain: Optional[Any] = Field(
+        default=None,
+        description='Filter by chain ID (e.g. 1 for Ethereum, "solana" for Solana).',
+    )
+    symbol: Optional[str] = Field(
+        default=None,
+        description="Filter by token symbol (e.g. UNI).",
+    )
+    asset_type: Optional[str] = Field(
+        default=None,
+        description='Filter by type: "token" or "nft".',
+    )
+
+
+class InsumerListTokensTool(BaseTool):
+    """List tokens and NFT collections registered with merchants."""
+
+    name: str = "insumer_list_tokens"
+    description: str = (
+        "List all tokens and NFT collections registered in The Insumer Model "
+        "ecosystem. Filter by blockchain, symbol, or asset type (token/nft). "
+        "Returns contract addresses, chain IDs, and metadata."
+    )
+    args_schema: Type[ListTokensSchema] = ListTokensSchema
+
+    api_wrapper: InsumerAPIWrapper = Field(..., exclude=True)
+
+    def __init__(self, api_wrapper: InsumerAPIWrapper) -> None:
+        super().__init__(api_wrapper=api_wrapper)
+
+    def _run(
+        self,
+        chain: Optional[Any] = None,
+        symbol: Optional[str] = None,
+        asset_type: Optional[str] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        """List tokens."""
+        result = self.api_wrapper.list_tokens(
+            chain=chain,
+            symbol=symbol,
+            asset_type=asset_type,
+        )
+        return json.dumps(result, indent=2)

langchain_insumer-0.1.0/langchain_insumer/tools/verify.py

@@ -0,0 +1,61 @@
+"""Tool for creating signed discount verification codes."""
+
+import json
+from typing import Optional, Type
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from langchain_insumer.wrapper import InsumerAPIWrapper
+
+
+class VerifySchema(BaseModel):
+    """Input for InsumerVerifyTool."""
+
+    merchant_id: str = Field(description="Merchant ID to generate the discount code for.")
+    wallet: Optional[str] = Field(
+        default=None,
+        description="EVM wallet address (0x...).",
+    )
+    solana_wallet: Optional[str] = Field(
+        default=None,
+        description="Solana wallet address (base58).",
+    )
+
+
+class InsumerVerifyTool(BaseTool):
+    """Create a signed discount verification code for a wallet at a merchant.
+
+    The code (INSR-XXXXX) is valid for 30 minutes and can be redeemed
+    at the merchant's point of sale. Costs 1 merchant credit.
+    """
+
+    name: str = "insumer_verify"
+    description: str = (
+        "Create a signed discount verification code (INSR-XXXXX) for a wallet "
+        "at a specific merchant. The code is valid for 30 minutes and includes "
+        "the discount percentage and an ECDSA signature. Use this after "
+        "checking the discount to generate a redeemable code. Costs 1 credit."
+    )
+    args_schema: Type[VerifySchema] = VerifySchema
+
+    api_wrapper: InsumerAPIWrapper = Field(..., exclude=True)
+
+    def __init__(self, api_wrapper: InsumerAPIWrapper) -> None:
+        super().__init__(api_wrapper=api_wrapper)
+
+    def _run(
+        self,
+        merchant_id: str,
+        wallet: Optional[str] = None,
+        solana_wallet: Optional[str] = None,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+    ) -> str:
+        """Create verification code."""
+        result = self.api_wrapper.verify(
+            merchant_id=merchant_id,
+            wallet=wallet,
+            solana_wallet=solana_wallet,
+        )
+        return json.dumps(result, indent=2)

langchain_insumer-0.1.0/langchain_insumer/wrapper.py

@@ -0,0 +1,151 @@
+"""API wrapper for The Insumer Model Attestation API."""
+
+from typing import Any, Optional
+
+import requests
+from pydantic import BaseModel, Field
+
+BASE_URL = "https://us-central1-insumer-merchant.cloudfunctions.net/insumerApi/v1"
+
+
+class InsumerAPIWrapper(BaseModel):
+    """Wrapper around The Insumer Model API.
+
+    Provides privacy-preserving on-chain attestation and token-gated commerce
+    across 31 blockchains. Verifies token balances and NFT ownership without
+    exposing actual wallet balances.
+
+    Args:
+        api_key: API key in format ``insr_live_`` followed by 40 hex characters.
+            Get a free key at https://insumermodel.com/developers/
+        timeout: Request timeout in seconds. Default 30.
+    """
+
+    api_key: str = Field(description="Insumer API key (insr_live_...)")
+    timeout: int = Field(default=30, description="Request timeout in seconds")
+
+    def _headers(self) -> dict:
+        return {
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json",
+        }
+
+    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        resp = requests.get(
+            f"{BASE_URL}{path}",
+            headers=self._headers(),
+            params=params,
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def _post(self, path: str, json_body: Optional[dict] = None) -> dict:
+        resp = requests.post(
+            f"{BASE_URL}{path}",
+            headers=self._headers(),
+            json=json_body or {},
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def attest(
+        self,
+        conditions: list[dict[str, Any]],
+        wallet: Optional[str] = None,
+        solana_wallet: Optional[str] = None,
+    ) -> dict:
+        """Create a privacy-preserving on-chain attestation.
+
+        Verifies 1-10 conditions (token balances, NFT ownership) and returns
+        a cryptographically signed true/false result. Never exposes actual
+        balances. Costs 1 attestation credit.
+
+        Args:
+            conditions: List of condition dicts, each with:
+                - type: "token_balance" or "nft_ownership"
+                - contractAddress: Token/NFT contract address
+                - chainId: EVM chain ID (int) or "solana"
+                - threshold: Min balance (for token_balance)
+                - decimals: Token decimals (default 18)
+                - label: Human-readable label
+            wallet: EVM wallet address (0x...)
+            solana_wallet: Solana wallet address (base58)
+
+        Returns:
+            API response with attestation results and ECDSA signature.
+        """
+        body: dict[str, Any] = {"conditions": conditions}
+        if wallet:
+            body["wallet"] = wallet
+        if solana_wallet:
+            body["solanaWallet"] = solana_wallet
+        return self._post("/attest", body)
+
+    def get_credits(self) -> dict:
+        """Check attestation credit balance for the API key."""
+        return self._get("/credits")
+
+    def list_merchants(
+        self,
+        token: Optional[str] = None,
+        verified: Optional[bool] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict:
+        """List merchants in the public directory."""
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if token:
+            params["token"] = token
+        if verified is not None:
+            params["verified"] = str(verified).lower()
+        return self._get("/merchants", params)
+
+    def get_merchant(self, merchant_id: str) -> dict:
+        """Get full public merchant profile with tier structures."""
+        return self._get(f"/merchants/{merchant_id}")
+
+    def list_tokens(
+        self,
+        chain: Optional[Any] = None,
+        symbol: Optional[str] = None,
+        asset_type: Optional[str] = None,
+    ) -> dict:
+        """List registered tokens and NFT collections."""
+        params: dict[str, Any] = {}
+        if chain is not None:
+            params["chain"] = chain
+        if symbol:
+            params["symbol"] = symbol
+        if asset_type:
+            params["type"] = asset_type
+        return self._get("/tokens", params)
+
+    def check_discount(
+        self,
+        merchant_id: str,
+        wallet: Optional[str] = None,
+        solana_wallet: Optional[str] = None,
+    ) -> dict:
+        """Calculate discount for a wallet at a merchant. Free, no credits consumed."""
+        params: dict[str, Any] = {"merchant": merchant_id}
+        if wallet:
+            params["wallet"] = wallet
+        if solana_wallet:
+            params["solanaWallet"] = solana_wallet
+        return self._get("/discount/check", params)
+
+    def verify(
+        self,
+        merchant_id: str,
+        wallet: Optional[str] = None,
+        solana_wallet: Optional[str] = None,
+    ) -> dict:
+        """Create a signed discount code (INSR-XXXXX), valid 30 minutes. Costs 1 credit."""
+        body: dict[str, Any] = {"merchantId": merchant_id}
+        if wallet:
+            body["wallet"] = wallet
+        if solana_wallet:
+            body["solanaWallet"] = solana_wallet
+        return self._post("/verify", body)

langchain_insumer-0.1.0/langchain_insumer.egg-info/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: langchain-insumer
+Version: 0.1.0
+Summary: LangChain integration for The Insumer Model — privacy-preserving on-chain attestation across 31 blockchains
+Author-email: The Insumer Model <contact@insumermodel.com>
+License: MIT
+Project-URL: Homepage, https://insumermodel.com/for-agents/
+Project-URL: Documentation, https://insumermodel.com/llms-full.txt
+Project-URL: Repository, https://github.com/douglasborthwick-crypto/langchain-insumer
+Project-URL: API Reference, https://insumermodel.com/openapi.yaml
+Project-URL: Bug Tracker, https://github.com/douglasborthwick-crypto/langchain-insumer/issues
+Keywords: langchain,blockchain,attestation,token-gated,nft,web3,privacy,on-chain,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain-core>=0.2.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=2.0.0
+Dynamic: license-file
+
+# langchain-insumer
+
+LangChain integration for [The Insumer Model](https://insumermodel.com) Attestation API.
+
+Verify on-chain token balances and NFT ownership across 31 blockchains with privacy-preserving attestations. Returns only true/false — never exposes actual wallet balances.
+
+## Installation
+
+```bash
+pip install langchain-insumer
+```
+
+## Quick Start
+
+```python
+from langchain_insumer import InsumerAPIWrapper, InsumerAttestTool
+
+# Initialize the API wrapper
+api = InsumerAPIWrapper(api_key="insr_live_YOUR_KEY_HERE")
+
+# Create tools for your agent
+attest_tool = InsumerAttestTool(api_wrapper=api)
+
+# Use with a LangChain agent
+from langchain.agents import initialize_agent, AgentType
+from langchain_openai import ChatOpenAI
+
+llm = ChatOpenAI(model="gpt-4")
+tools = [attest_tool]
+agent = initialize_agent(tools, llm, agent=AgentType.OPENAI_FUNCTIONS)
+
+agent.run("Does wallet 0x1234... hold at least 100 USDC on Ethereum?")
+```
+
+## Available Tools
+
+| Tool | Description | Credits |
+|------|-------------|---------|
+| `InsumerAttestTool` | Verify on-chain conditions with signed attestation | 1/call |
+| `InsumerCheckDiscountTool` | Calculate discount for wallet at merchant | Free |
+| `InsumerListMerchantsTool` | Browse merchant directory | Free |
+| `InsumerListTokensTool` | List registered tokens and NFTs | Free |
+| `InsumerVerifyTool` | Create signed discount code (INSR-XXXXX) | 1/call |
+| `InsumerCreditsTool` | Check API key credit balance | Free |
+
+## Using All Tools
+
+```python
+from langchain_insumer import (
+    InsumerAPIWrapper,
+    InsumerAttestTool,
+    InsumerCheckDiscountTool,
+    InsumerCreditsTool,
+    InsumerListMerchantsTool,
+    InsumerListTokensTool,
+    InsumerVerifyTool,
+)
+
+api = InsumerAPIWrapper(api_key="insr_live_YOUR_KEY_HERE")
+
+tools = [
+    InsumerAttestTool(api_wrapper=api),
+    InsumerCheckDiscountTool(api_wrapper=api),
+    InsumerCreditsTool(api_wrapper=api),
+    InsumerListMerchantsTool(api_wrapper=api),
+    InsumerListTokensTool(api_wrapper=api),
+    InsumerVerifyTool(api_wrapper=api),
+]
+```
+
+## Attestation Example
+
+```python
+import json
+
+api = InsumerAPIWrapper(api_key="insr_live_YOUR_KEY_HERE")
+
+result = api.attest(
+    wallet="0x1234567890abcdef1234567890abcdef12345678",
+    conditions=[
+        {
+            "type": "token_balance",
+            "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+            "chainId": 1,
+            "threshold": 1000,
+            "decimals": 6,
+            "label": "USDC >= 1000 on Ethereum",
+        },
+        {
+            "type": "nft_ownership",
+            "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
+            "chainId": 1,
+            "label": "Bored Ape Yacht Club holder",
+        },
+    ],
+)
+
+attestation = result["data"]["attestation"]
+print(f"Pass: {attestation['pass']}")
+for r in attestation["results"]:
+    print(f"  {r['label']}: {'met' if r['met'] else 'not met'}")
+print(f"Signature: {result['data']['sig']}")
+```
+
+## Supported Chains (31)
+
+Ethereum, BNB Chain, Base, Avalanche, Polygon, Arbitrum, Optimism, Solana, Chiliz, Soneium, Plume, Sonic, Gnosis, Mantle, Scroll, Linea, zkSync Era, Blast, Taiko, Ronin, Celo, Moonbeam, Moonriver, Viction, opBNB, World Chain, Unichain, Ink, Sei, Berachain, ApeChain.
+
+## Get an API Key
+
+- **Free** (10 credits): [insumermodel.com/developers](https://insumermodel.com/developers/)
+- **Pro** (10,000/day): 29 USDC/month
+- **Enterprise** (100,000/day): 99 USDC/month
+
+## Links
+
+- [API Documentation](https://insumermodel.com/for-agents/)
+- [OpenAPI Spec](https://insumermodel.com/openapi.yaml)
+- [Full API Reference](https://insumermodel.com/llms-full.txt)
+
+## License
+
+MIT

langchain_insumer-0.1.0/langchain_insumer.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+langchain_insumer/__init__.py
+langchain_insumer/wrapper.py
+langchain_insumer.egg-info/PKG-INFO
+langchain_insumer.egg-info/SOURCES.txt
+langchain_insumer.egg-info/dependency_links.txt
+langchain_insumer.egg-info/requires.txt
+langchain_insumer.egg-info/top_level.txt
+langchain_insumer/tools/__init__.py
+langchain_insumer/tools/attest.py
+langchain_insumer/tools/check_discount.py
+langchain_insumer/tools/credits.py
+langchain_insumer/tools/list_merchants.py
+langchain_insumer/tools/list_tokens.py
+langchain_insumer/tools/verify.py
+tests/test_tools.py

langchain_insumer-0.1.0/langchain_insumer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

langchain_insumer-0.1.0/langchain_insumer.egg-info/requires.txt

@@ -0,0 +1,3 @@
+langchain-core>=0.2.0
+requests>=2.28.0
+pydantic>=2.0.0

langchain_insumer-0.1.0/langchain_insumer.egg-info/top_level.txt

@@ -0,0 +1 @@
+langchain_insumer

langchain_insumer-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langchain-insumer"
+version = "0.1.0"
+description = "LangChain integration for The Insumer Model — privacy-preserving on-chain attestation across 31 blockchains"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "The Insumer Model", email = "contact@insumermodel.com"},
+]
+keywords = [
+    "langchain",
+    "blockchain",
+    "attestation",
+    "token-gated",
+    "nft",
+    "web3",
+    "privacy",
+    "on-chain",
+    "verification",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "langchain-core>=0.2.0",
+    "requests>=2.28.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://insumermodel.com/for-agents/"
+Documentation = "https://insumermodel.com/llms-full.txt"
+Repository = "https://github.com/douglasborthwick-crypto/langchain-insumer"
+"API Reference" = "https://insumermodel.com/openapi.yaml"
+"Bug Tracker" = "https://github.com/douglasborthwick-crypto/langchain-insumer/issues"
+
+[tool.setuptools.packages.find]
+include = ["langchain_insumer*"]

langchain_insumer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

langchain_insumer-0.1.0/tests/test_tools.py

@@ -0,0 +1,153 @@
+"""Tests for langchain-insumer tools."""
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from langchain_insumer import (
+    InsumerAPIWrapper,
+    InsumerAttestTool,
+    InsumerCheckDiscountTool,
+    InsumerCreditsTool,
+    InsumerListMerchantsTool,
+    InsumerListTokensTool,
+    InsumerVerifyTool,
+)
+
+
+@pytest.fixture
+def api():
+    return InsumerAPIWrapper(api_key="insr_live_0000000000000000000000000000000000000000")
+
+
+@pytest.fixture
+def mock_response():
+    mock = MagicMock()
+    mock.status_code = 200
+    mock.json.return_value = {
+        "ok": True,
+        "data": {},
+        "meta": {"version": "1.0", "timestamp": "2026-02-22T00:00:00.000Z"},
+    }
+    mock.raise_for_status = MagicMock()
+    return mock
+
+
+class TestInsumerAPIWrapper:
+    def test_headers(self, api):
+        headers = api._headers()
+        assert headers["X-API-Key"] == "insr_live_0000000000000000000000000000000000000000"
+        assert headers["Content-Type"] == "application/json"
+
+    @patch("langchain_insumer.wrapper.requests.post")
+    def test_attest(self, mock_post, api, mock_response):
+        mock_response.json.return_value = {
+            "ok": True,
+            "data": {
+                "attestation": {
+                    "id": "ATST-A7C3E",
+                    "pass": True,
+                    "results": [{"condition": 0, "met": True}],
+                    "passCount": 1,
+                    "failCount": 0,
+                },
+                "sig": "base64sig...",
+            },
+            "meta": {"creditsRemaining": 9},
+        }
+        mock_post.return_value = mock_response
+
+        result = api.attest(
+            wallet="0x1234567890abcdef1234567890abcdef12345678",
+            conditions=[
+                {
+                    "type": "token_balance",
+                    "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+                    "chainId": 1,
+                    "threshold": 100,
+                    "decimals": 6,
+                }
+            ],
+        )
+
+        assert result["ok"] is True
+        assert result["data"]["attestation"]["pass"] is True
+        mock_post.assert_called_once()
+
+    @patch("langchain_insumer.wrapper.requests.get")
+    def test_get_credits(self, mock_get, api, mock_response):
+        mock_response.json.return_value = {
+            "ok": True,
+            "data": {"apiKeyCredits": 42, "tier": "pro", "dailyLimit": 10000},
+        }
+        mock_get.return_value = mock_response
+
+        result = api.get_credits()
+        assert result["data"]["apiKeyCredits"] == 42
+
+    @patch("langchain_insumer.wrapper.requests.get")
+    def test_list_merchants(self, mock_get, api, mock_response):
+        mock_response.json.return_value = {
+            "ok": True,
+            "data": [{"id": "test", "companyName": "Test Co"}],
+            "meta": {"total": 1, "limit": 50, "offset": 0},
+        }
+        mock_get.return_value = mock_response
+
+        result = api.list_merchants(token="UNI", limit=10)
+        assert len(result["data"]) == 1
+
+    @patch("langchain_insumer.wrapper.requests.get")
+    def test_check_discount(self, mock_get, api, mock_response):
+        mock_response.json.return_value = {
+            "ok": True,
+            "data": {"eligible": True, "totalDiscount": 15},
+        }
+        mock_get.return_value = mock_response
+
+        result = api.check_discount(
+            merchant_id="test",
+            wallet="0x1234567890abcdef1234567890abcdef12345678",
+        )
+        assert result["data"]["totalDiscount"] == 15
+
+
+class TestTools:
+    @patch("langchain_insumer.wrapper.requests.post")
+    def test_attest_tool(self, mock_post, api, mock_response):
+        mock_response.json.return_value = {
+            "ok": True,
+            "data": {"attestation": {"pass": True}},
+        }
+        mock_post.return_value = mock_response
+
+        tool = InsumerAttestTool(api_wrapper=api)
+        assert tool.name == "insumer_attest"
+
+        result = tool._run(
+            conditions=json.dumps([{"type": "token_balance", "contractAddress": "0x...", "chainId": 1, "threshold": 100}]),
+            wallet="0x1234567890abcdef1234567890abcdef12345678",
+        )
+        parsed = json.loads(result)
+        assert parsed["ok"] is True
+
+    def test_credits_tool_name(self, api):
+        tool = InsumerCreditsTool(api_wrapper=api)
+        assert tool.name == "insumer_credits"
+
+    def test_list_merchants_tool_name(self, api):
+        tool = InsumerListMerchantsTool(api_wrapper=api)
+        assert tool.name == "insumer_list_merchants"
+
+    def test_list_tokens_tool_name(self, api):
+        tool = InsumerListTokensTool(api_wrapper=api)
+        assert tool.name == "insumer_list_tokens"
+
+    def test_check_discount_tool_name(self, api):
+        tool = InsumerCheckDiscountTool(api_wrapper=api)
+        assert tool.name == "insumer_check_discount"
+
+    def test_verify_tool_name(self, api):
+        tool = InsumerVerifyTool(api_wrapper=api)
+        assert tool.name == "insumer_verify"