From a39095ed7e32d96b51f56d176d463f7b4a58a254 Mon Sep 17 00:00:00 2001 From: Modaniels Date: Sun, 5 Apr 2026 02:01:06 +0300 Subject: [PATCH 1/4] docs: add Modexia AgentPay tool integration --- src/code-samples/package-lock.json | 12 +- src/oss/python/integrations/tools/index.mdx | 2 + src/oss/python/integrations/tools/modexia.mdx | 285 ++++++++++++++++++ 3 files changed, 288 insertions(+), 11 deletions(-) create mode 100644 src/oss/python/integrations/tools/modexia.mdx diff --git a/src/code-samples/package-lock.json b/src/code-samples/package-lock.json index 68d6df1413..96e23dae1c 100644 --- a/src/code-samples/package-lock.json +++ b/src/code-samples/package-lock.json @@ -54,8 +54,7 @@ "version": "4.1.1", "resolved": "https://registry.npmjs.org/@cfworker/json-schema/-/json-schema-4.1.1.tgz", "integrity": "sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@esbuild/aix-ppc64": { "version": "0.27.3", @@ -520,7 +519,6 @@ "resolved": "https://registry.npmjs.org/@langchain/core/-/core-1.1.36.tgz", "integrity": "sha512-9NWsdzU3uZD13lJwunXK0t6SIwew+UwcbHggW5yUdaiMmzKeNkDpp1lRD6p49N8+D0Vv4qmQBEKB4Ukh2jfnvw==", "license": "MIT", - "peer": true, "dependencies": { "@cfworker/json-schema": "^4.0.2", "@standard-schema/spec": "^1.1.0", @@ -568,7 +566,6 @@ "resolved": "https://registry.npmjs.org/@langchain/langgraph-checkpoint/-/langgraph-checkpoint-1.0.0.tgz", "integrity": "sha512-xrclBGvNCXDmi0Nz28t3vjpxSH6UYx6w5XAXSiiB1WEdc2xD2iY/a913I3x3a31XpInUW/GGfXXfePfaghV54A==", "license": "MIT", - "peer": true, "dependencies": { "uuid": "^10.0.0" }, @@ -781,7 +778,6 @@ "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz", "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==", "license": "MIT", - "peer": true, "engines": { "node": ">=10" }, @@ -826,7 +822,6 @@ "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-6.3.0.tgz", "integrity": "sha512-Gmy6FhYlCY7uOElZUSbxo2UCDH8owEk996gkbrpsgGtrJLM3J7jGxl9Ic7Qwwj4ivOE5AWZWRMecDdF7hqGjFA==", "license": "MIT", - "peer": true, "engines": { "node": ">=10" }, @@ -860,7 +855,6 @@ "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz", "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==", "license": "MIT", - "peer": true, "engines": { "node": ">=0.10.0" } @@ -1105,7 +1099,6 @@ "resolved": "https://registry.npmjs.org/langsmith/-/langsmith-0.5.7.tgz", "integrity": "sha512-FjYf2oBGMoSXnaT4SRaFguIiGJaonZ5VKWKJDPl9awLZjz2RkN29AcQWceecSINVzXzTvtRWPOjAWT+XggqNNg==", "license": "MIT", - "peer": true, "dependencies": { "@types/uuid": "^10.0.0", "chalk": "^5.6.2", @@ -1175,7 +1168,6 @@ "resolved": "https://registry.npmjs.org/mustache/-/mustache-4.2.0.tgz", "integrity": "sha512-71ippSywq5Yb7/tVYyGbkBggbU8H3u5Rz56fH60jGFgr8uHwxs+aSKeqmluIVzM0m0kB7xQjKS6qPfd0b2ZoqQ==", "license": "MIT", - "peer": true, "bin": { "mustache": "bin/mustache" } @@ -1258,7 +1250,6 @@ "resolved": "https://registry.npmjs.org/pg/-/pg-8.20.0.tgz", "integrity": "sha512-ldhMxz2r8fl/6QkXnBD3CR9/xg694oT6DZQ2s6c/RI28OjtSOpxnPrUCGOBJ46RCUxcWdx3p6kw/xnDHjKvaRA==", "license": "MIT", - "peer": true, "dependencies": { "pg-connection-string": "^2.12.0", "pg-pool": "^3.13.0", @@ -1571,7 +1562,6 @@ "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", "license": "MIT", - "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/src/oss/python/integrations/tools/index.mdx b/src/oss/python/integrations/tools/index.mdx index 6c4b63d07a..e3814b6470 100644 --- a/src/oss/python/integrations/tools/index.mdx +++ b/src/oss/python/integrations/tools/index.mdx @@ -96,6 +96,7 @@ The following table shows tools that can be used to execute financial transactio |-------------|---------|--------------| | [Ampersend](/oss/integrations/tools/ampersend) | Paid | Pay for and use remote AI agent services with automatic x402 payment handling. | | [GOAT](/oss/integrations/tools/goat) | Free | Create and receive payments, purchase physical goods, make investments, and more. | +| [Modexia AgentPay](/oss/integrations/tools/modexia) | Pay-per-use | Autonomous crypto payments, cross-chain transfers, and L402 paywall negotiation. | | [Privy](/oss/integrations/tools/privy) | Free | Create wallets with configurable permissions and execute transactions with speed. | ## Integration platforms @@ -197,6 +198,7 @@ The following platforms provide access to multiple tools and services through a + diff --git a/src/oss/python/integrations/tools/modexia.mdx b/src/oss/python/integrations/tools/modexia.mdx new file mode 100644 index 0000000000..e0cdb01c4c --- /dev/null +++ b/src/oss/python/integrations/tools/modexia.mdx @@ -0,0 +1,285 @@ +--- +title: "Modexia AgentPay" +description: "Integrate Modexia AgentPay to empower your agents with autonomous crypto infrastructure." +--- + +[Modexia](https://modexia.software) allows AI Agents to autonomously hold USDC, execute cross-chain payments, route through high-frequency zero-gas micro-transaction vaults, and automatically negotiate HTTP `402 Payment Required` paywalls without handling private keys directly. + +## Overview + +Modexia provides a core Toolkit that bundles 8 individual cryptocurrency tools. Agents can use the Toolkit directly or instantiate individual tools: + +- **`RetrieveBalanceTool`** checks the agent's current usable USDC balance. +- **`TransferTool`** executes standard, on-chain EVM-based USDC transfers. +- **`GetHistoryTool`** returns a ledger dataframe of recent transaction activity. +- **`CrossChainTransferTool`** uses Squid Router abstraction to burn/attest/transfer USDC across any supported blockchain instantly. +- **`SmartFetchTool`** is a secure HTTP client that detects `L402` paywall invoices and automatically settles them to retrieve gated JSON content. +- **`OpenChannelTool`** establishes a high-frequency, zero-gas micro-transaction vault. +- **`ConsumeChannelTool`** instantly executes cryptographically signed micro-payments off-chain. +- **`SettleChannelTool`** closes the cryptographically signed vault and commits final balances to the block. + +### Integration details + +| Class | Package | Serializable | [JS support](https://modelcontextprotocol.io/) | Version | +| :--- | :--- | :---: | :---: | :---: | +| `ModexiaToolkit` | langchain-modexia | ❌ | ✅ (Via MCP) | 0.1.1 | + +### Tool features + +| Tool | State Read | On-Chain Move | Off-Chain Micro-Tx | L402 Web Fetch | +| :--- | :---: | :---: | :---: | :---: | +| `RetrieveBalanceTool` / `GetHistoryTool` | ✅ | ❌ | ❌ | ❌ | +| `TransferTool` / `CrossChainTransferTool` | ❌ | ✅ | ❌ | ❌ | +| `Open/Consume/SettleChannelTool` | ❌ | ❌ | ✅ | ❌ | +| `SmartFetchTool` | ❌ | ❌ | ❌ | ✅ | + +## Setup + +```python +pip install --quiet -U langchain-modexia +``` + +To run asynchronous models efficiently, ensure you have your Event Loop and LangGraph configured. (Jupyter notebooks have their own event loop, so `nest_asyncio` may be required). + +### Credentials + +To use the Modexia tools, you will need to retrieve your private API key from your [Modexia Developer Dashboard](https://modexia.software) and set the `MODEXIA_API_KEY` environment variable. + +```python +import os + +os.environ["MODEXIA_API_KEY"] = "mx_live_YOUR_API_KEY" +``` + +## Instantiation + +### `ModexiaToolkit` + +The easiest way to use Modexia is by initializing the **ModexiaToolkit** which automatically registers and validates all 8 tools simultaneously. + +You can instantiate `ModexiaToolkit` with the following parameters: + +- `api_key`: Your Modexia API key (Must be either `mx_test_` or `mx_live_`). **Required.** +- `async_mode`: Whether the internal HTTPx client should use asynchronous event loops for non-blocking LangGraph execution. **Defaults to `False`.** +- `timeout`: The global timeout in seconds for Modexia REST API requests. **Defaults to `10.0`.** + +```python +from langchain_modexia import ModexiaToolkit + +toolkit = ModexiaToolkit.from_api_key( + api_key=os.environ["MODEXIA_API_KEY"], + async_mode=True, + timeout=15.0 +) +tools = toolkit.get_tools() +``` + +### Individual Tools +If you only want your Agent to have "Read-Only" capabilities (no fund transferring), you can manually inject specific tools by passing them your authenticated `ModexiaClient` or `AsyncModexiaClient`. + +```python +from modexia import ModexiaClient +from langchain_modexia.tools import RetrieveBalanceTool, GetHistoryTool + +client = ModexiaClient(api_key=os.environ["MODEXIA_API_KEY"]) + +balance_tool = RetrieveBalanceTool(client=client) +history_tool = GetHistoryTool(client=client) + +read_only_tools = [balance_tool, history_tool] +``` + +## Invocation + +### Extracting Balance +You can directly invoke any Modexia tool. Since `RetrieveBalanceTool` takes no Pydantic arguments, we pass an empty dict. + +```python +balance = balance_tool.invoke({}) +print(balance) +``` + +```text +{'balance': 1500.25, 'currency': 'USDC'} +``` + +### Executing SmartFetch (L402 Paywalls) + +`SmartFetchTool` detects HTTP `402 Payment Required` headers and automatically negotiates the LSAT/L402 invoice, deducting from your Modexia balance quietly and routing the un-gated payload back to the Agent. + +- `url`: The paywalled API endpoint. +- `method`: HTTP Method (GET/POST). +- `payload`: Optional JSON payload for POST. + +```python +from langchain_modexia.tools import SmartFetchTool + +smart_fetch = SmartFetchTool(client=client) +response = smart_fetch.invoke({ + "url": "https://api.premium-weather.com/v1/forecast", + "method": "GET" +}) +``` + +```text +{ + "modexia_cost": 0.05, + "invoice_settled": true, + "payload": { + "temperature": 72, + "conditions": "Sunny" + } +} +``` + +## Chaining + +You can use Modexia tools in a chain by binding the toolkit to a tool-calling LLM. + +### Instantiate LLM + +```python +import os + +os.environ["ANTHROPIC_API_KEY"] = "your-api-key" +``` + +```python +from langchain_anthropic import ChatAnthropic + +llm = ChatAnthropic(model="claude-3-5-sonnet-20240620") +llm_with_tools = llm.bind_tools(read_only_tools) +``` + +### Execute tool chain + +```python +from langchain_core.messages import HumanMessage + +ai_msg = llm_with_tools.invoke([ + HumanMessage(content="Can you tell me how much Crypto I have left in my wallet?") +]) + +print(ai_msg.tool_calls) +``` + +```text +[{'name': 'modexia_get_balance', 'args': {}, 'id': 'call_J3u2Dk_bHw'}] +``` + +## Use within an agent + +The true power of Modexia shines when you give the full Toolkit to a ReAct Agent. +Agents can autonomously decide to parse data, cross-chain transfer funds, or open micropayment channels without any human intervention. + +### Use with a LangGraph ReAct Agent + +```python +pip install --quiet -U langgraph +``` + +```python +from langgraph.prebuilt import create_react_agent + +# Pass tools generated by `toolkit.get_tools()` +agent_executor = create_react_agent(llm, toolkit.get_tools()) +``` + +```python +prompt = """ +1. Check my current balance. +2. If I have more than 5 USDC, send exactly 2.5 USDC to 0x123abc456def7890123abc456def7890123abc45 on the Base network. +3. Check my history to verify the last transaction went through. +4. Give me a pleasant summary of the result. +""" + +events = agent_executor.astream( + {"messages": [("user", prompt)]}, + stream_mode="values", +) +for event in events: + event["messages"][-1].pretty_print() +``` + +```text +================================ Human Message ================================= + +1. Check my current balance. +2. If I have more than 5 USDC, send exactly 2.5 USDC to 0x123abc456def7890123abc456def7890123abc45 on the Base network. +3. Check my history to verify the last transaction went through. +4. Give me a pleasant summary of the result. + +================================== Ai Message ================================== +Tool Calls: + modexia_get_balance (call_a3vX9pL2oQrt_M) + Call ID: call_a3vX9pL2oQrt_M + Args: {} + +================================= Tool Message ================================= +Name: modexia_get_balance + +{"balance": 18.50, "currency": "USDC"} + +================================== Ai Message ================================== +Tool Calls: + modexia_cross_chain_transfer (call_j7kP4nT1sVxz_W) + Call ID: call_j7kP4nT1sVxz_W + Args: + amount: 2.5 + destination_address: 0x123abc456def7890123abc456def7890123abc45 + destination_chain: Base + +================================= Tool Message ================================= +Name: modexia_cross_chain_transfer + +{"tx_hash": "0x4b7f8e...9a2e", "status": "CONFIRMED", "estimated_gas_abstracted": 0.001} + +================================== Ai Message ================================== +Tool Calls: + modexia_get_history (call_l9mN2qR3tYux_B) + Call ID: call_l9mN2qR3tYux_B + Args: + limit: 1 + +================================= Tool Message ================================= +Name: modexia_get_history + +[{"id": "cctp_base_001", "type": "CROSS_CHAIN_TRANSFER", "amount": -2.5, "timestamp": "2026-04-05T00:35:00Z"}] + +================================== Ai Message ================================== + +Here is the pleasant summary of your transaction: + +I successfully verified that your wallet had an initial balance of **18.50 USDC**, which was more than enough to proceed! + +I immediately executed a cross-chain transfer of **2.5 USDC** directly to `0x123...abc45` on the Base network for you. Your transaction hash is `0x4b7f8e...9a2e` and gas was fully abstracted. + +Finally, I checked your latest ledger history and can confirm the transaction has successfully landed on-chain. You are all set! 🚀 +``` + +--- + +## JavaScript / TypeScript Support via MCP + +If you are orchestrating agents outside of Python (such as JS LangGraph, ElizaOS, or DayS), you can achieve exact feature parity via our Model Context Protocol (MCP) Server using LangChain's generic MCP adapters. + +### JS Integration Example + +```typescript +import { loadMcpTools } from "@langchain/mcp-adapters"; +import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; + +// Instantiates the Python MCP server securely in the background +const transport = new StdioClientTransport({ + command: "uvx", + args: ["modexia-mcp"], + env: { MODEXIA_API_KEY: process.env.MODEXIA_API_KEY } +}); + +// The JS Agent now has the exact same 8 Tools from above! +const tools = await loadMcpTools(transport); +``` + +## API reference + +For more information on how to architect LangChain solutions with Modexia, please refer to the [Modexia Developer Portal](https://modexia.software) or view the raw implementation on our [GitHub Repository](https://github.com/Modaniels/SDKs). From 6691156208ffecda019c37dc29091f1e7212ed80 Mon Sep 17 00:00:00 2001 From: Modaniels Date: Sun, 5 Apr 2026 02:10:18 +0300 Subject: [PATCH 2/4] fix: change langchain_core import to langchain --- src/oss/python/integrations/tools/modexia.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oss/python/integrations/tools/modexia.mdx b/src/oss/python/integrations/tools/modexia.mdx index e0cdb01c4c..6bab33280a 100644 --- a/src/oss/python/integrations/tools/modexia.mdx +++ b/src/oss/python/integrations/tools/modexia.mdx @@ -154,7 +154,7 @@ llm_with_tools = llm.bind_tools(read_only_tools) ### Execute tool chain ```python -from langchain_core.messages import HumanMessage +from langchain.messages import HumanMessage ai_msg = llm_with_tools.invoke([ HumanMessage(content="Can you tell me how much Crypto I have left in my wallet?") From 3d55fb9b930cc53b266534e7d9b99f3afd8200a9 Mon Sep 17 00:00:00 2001 From: Daniel Okinda Date: Mon, 6 Apr 2026 21:19:20 +0300 Subject: [PATCH 3/4] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/oss/python/integrations/tools/modexia.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oss/python/integrations/tools/modexia.mdx b/src/oss/python/integrations/tools/modexia.mdx index 6bab33280a..4a31e7929d 100644 --- a/src/oss/python/integrations/tools/modexia.mdx +++ b/src/oss/python/integrations/tools/modexia.mdx @@ -30,7 +30,7 @@ Modexia provides a core Toolkit that bundles 8 individual cryptocurrency tools. | :--- | :---: | :---: | :---: | :---: | | `RetrieveBalanceTool` / `GetHistoryTool` | ✅ | ❌ | ❌ | ❌ | | `TransferTool` / `CrossChainTransferTool` | ❌ | ✅ | ❌ | ❌ | -| `Open/Consume/SettleChannelTool` | ❌ | ❌ | ✅ | ❌ | +| `OpenChannelTool` / `ConsumeChannelTool` / `SettleChannelTool` | ❌ | ❌ | ✅ | ❌ | | `SmartFetchTool` | ❌ | ❌ | ❌ | ✅ | ## Setup From fbf1b7708e954de3e548de7ae6b1ea6bedbdb61f Mon Sep 17 00:00:00 2001 From: Daniel Okinda Date: Mon, 6 Apr 2026 21:19:39 +0300 Subject: [PATCH 4/4] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/oss/python/integrations/tools/modexia.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oss/python/integrations/tools/modexia.mdx b/src/oss/python/integrations/tools/modexia.mdx index 4a31e7929d..deacf8822e 100644 --- a/src/oss/python/integrations/tools/modexia.mdx +++ b/src/oss/python/integrations/tools/modexia.mdx @@ -22,7 +22,7 @@ Modexia provides a core Toolkit that bundles 8 individual cryptocurrency tools. | Class | Package | Serializable | [JS support](https://modelcontextprotocol.io/) | Version | | :--- | :--- | :---: | :---: | :---: | -| `ModexiaToolkit` | langchain-modexia | ❌ | ✅ (Via MCP) | 0.1.1 | +| `ModexiaToolkit` | langchain-modexia | ❌ | ✅ (Via MCP) | 0.1.1 | ### Tool features