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..deacf8822e --- /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` | ❌ | ✅ | ❌ | ❌ | +| `OpenChannelTool` / `ConsumeChannelTool` / `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.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).