File size: 7,445 Bytes
be34ff5
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
---
license: mit
tags:
  - mcp
  - mcp-server
  - warppay
  - x402
  - python
  - ai-agents
---

# warppay402-mcp

[![M8ven Score](https://m8ven.ai/badge/mcp/warppay402-warppay402-python-1g5nyh)](https://m8ven.ai/mcp/warppay402-warppay402-python-1g5nyh?s=readme)

LangChain-compatible `BaseTool` wrappers for WarpPay402 x402 micropayment APIs.

## Overview

This package provides a toolkit of agent-ready tools for on-chain analytics, web extraction, automation, and DeFi actions. The tools are implemented in `warppay402_mcp.tools` and use the WarpPay402 API endpoints under `https://api.warppay402.com/api/v1/tools`.

## Accepted payment options

The WarpPay402 server accepts the following payment methods for tool usage:

- Base USDC
- Arbitrum One USDC
- Solana USDC
- Arc USDC

## Installation

Install the base package:

```bash
pip install warppay402-mcp
```

This includes the required runtime dependencies (`requests`, `langchain-core`, and `mcp`).

If you want to run the LangChain/OpenAI or LlamaIndex examples below, install the optional integration packages:

```bash
pip install langchain-openai
pip install "warppay402-mcp[llamaindex]" llama-index-llms-openai
```

## Available tools

The package currently includes these tools:

| Tool | Price | Server capability | Typical call signature |
| --- | --- | --- | --- |
| `ArcDexOracleTool` | $0.001 USDC | Arc DEX spot price & liquidity oracle | `run(pair="ETH/USDC")` |
| `WebScraperTool` | $0.001 USDC | Public webpage to Markdown extraction | `run(url)` |
| `BrowserScraperTool` | $0.005 USDC | JS-rendered page scraping via browser | `run(url)` |
| `BaseAnalyticsTool` | $0.002 USDC | Wallet balance / nonce / account stats on Base | `run(address)` |
| `ArcAnalyticsTool` | $0.001 USDC | Arc network block / gas / latency telemetry | `run()` |
| `ArcNetworkQueryTool` | $0.10 USDC | Pre-flight Arc node + gas + merchant checks | `run(includeGasTrends=True, checkMerchantAccount=True)` |
| `PdfExtractorTool` | $0.005 USDC | Public PDF text extraction | `run(pdfUrl)` |
| `RenderScreenshotTool` | $0.01 USDC | Full-page screenshot capture | `run(url)` |
| `ExtractJsonTool` | $0.01 USDC | Schema-driven JSON extraction from HTML | `run(url, schema=None)` |
| `SmartContractVerifierTool` | $0.02 USDC | Contract source / ABI / proxy verification | `run(address)` |
| `AerodromeYieldsTool` | $0.003 USDC | Top yield pools and APY data | `run()` |
| `AerodromeSwapTool` | $0.01 USDC | Aerodrome router token swap execution | `run(tokenIn, tokenOut, amountIn, decimalsIn, isStable)` |
| `AerodromeClammTool` | $0.01 USDC | Constrained liquidity range actions | `run(action, token0=None, token1=None, tickLower=None, tickUpper=None, amount0Desired=None, amount1Desired=None, tokenId=None)` |
| `AerodromeVeaeroTool` | $0.01 USDC | Lock / vote / claim AERO governance actions | `run(action, amount=None, lockDurationWeeks=None, tokenId=None, poolVoteAddresses=None)` |
| `DeployBaseContractTool` | $5.00 USDC | Deploy contracts on Base | `run(contractType="escrow")` |
| `DeploySolanaContractTool` | $5.00 USDC | Deploy Solana contracts / vaults | `run(contractType, params)` |
| `DeployArcContractTool` | $5.00 USDC | Deploy contracts on Arc | `run(contractType="escrow")` |
| `ArcCctpBridgeTool` | $0.25 USDC | Cross-chain USDC bridge via CCTP | `run(amountUsdc, destinationChain, recipientAddress)` |
| `PublicDataFeedTool` | $0.0001 USDC | Signed public data feed retrieval | `run(filename)` |
| `DataFeedsTool` | $0.001 USDC | Market / yield feed retrieval | `run(feedId)` |
| `RealEstateCalculatorTool` | $0.0005 USDC | Real estate Cap Rate, NOI, and DSCR calculator | `run(purchasePrice, monthlyRent)` |
| `AddressNormalizerTool` | $0.001 USDC | Address geocoding & lat/lon resolution | `run(address)` |
| `WeatherOracleTool` | $0.001 USDC | Atmospheric weather & drone flight safety oracle | `run(latitude, longitude)` |
| `ForexOracleTool` | $0.0005 USDC | Global foreign exchange fiat spot rates | `run(baseCurrency="USD")` |
| `ShippingRateEstimatorTool` | $0.001 USDC | Domestic USPS parcel shipping rate estimator | `run(weightLbs, originZip, destinationZip)` |
| `GithubHealthAnalyzerTool` | $0.002 USDC | GitHub repository stars, issues & license inspector | `run(repository)` |
| `PropertyCompsEstimatorTool` | $0.005 USDC | Property valuations & tax assessor comps | `run(squareFeet, bedrooms, zipCode)` |
| `OutageOracleTool` | $0.002 USDC | Real-time power, ISP, and cellular outage oracle | `run(zipCode, state=None, serviceType="all")` |
| `UcpDealsOracleTool` | $0.001 USDC | UCP merchant product catalog & deals oracle | `run(query, maxPriceUSD=None, inStockOnly=True)` |

This table is meant to make it easy for developers to point agents at the right server capability and understand the expected inputs and pricing before invoking a tool.

## Quickstart

### Direct tool usage

```python
from warppay402_mcp.tools import ArcDexOracleTool, AerodromeYieldsTool, WebScraperTool

oracle = ArcDexOracleTool()
print(oracle.run("ETH/USDC"))

yields_tool = AerodromeYieldsTool()
print(yields_tool.run())

scraper = WebScraperTool()
print(scraper.run("https://example.com"))
```

### LangChain agent usage

```python
from langchain.agents import AgentType, initialize_agent
from langchain_openai import ChatOpenAI

from warppay402_mcp.tools import ArcDexOracleTool

llm = ChatOpenAI(model="gpt-4o-mini")
tools = [ArcDexOracleTool()]

agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION,
)

result = agent.invoke("What is the current ETH/USDC spot price?")
print(result)
```

## Example tool details

### `ArcDexOracleTool`

- Name: `arc_dex_oracle`
- Description: Real-time ETH/USDC spot price resolver and DEX liquidity oracle for Arc Mainnet ($0.001 USDC).
- Default pair: `ETH/USDC`

```python
from warppay402_mcp.tools import ArcDexOracleTool

tool = ArcDexOracleTool()
print(tool.run("ETH/USDC"))
```

### `AerodromeYieldsTool`

- Name: `get_aerodrome_yields`
- Description: Fetches top live Aerodrome DEX yield pools, APYs, and TVL on Base Mainnet ($0.003 USDC).

```python
from warppay402_mcp.tools import AerodromeYieldsTool

tool = AerodromeYieldsTool()
print(tool.run())
```

### LlamaIndex agent usage

First, install LlamaIndex support:

```bash
pip install "warppay402-mcp[llamaindex]" llama-index-llms-openai
```

Then pass the converted tools directly into any LlamaIndex agent:

```python
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
from warppay402_mcp import WarpPayLlamaIndexTools

# Retrieve all 29 tools wrapped as LlamaIndex FunctionTools
tools = WarpPayLlamaIndexTools.get_tools()

# Attach tools to a LlamaIndex Agent
agent = ReActAgent.from_tools(tools, llm=OpenAI(model="gpt-4o-mini"), verbose=True)

response = agent.chat("What is the current ETH/USDC spot price on Arc Mainnet?")
print(response)
```

## Notes

- The package exports `ArcDexOracleTool` at the package root, but the full tool set is defined in `warppay402_mcp.tools`.
- Many tools accept simple Python arguments and return raw API response text as a string.
- This project depends on `requests`, `langchain-core`, and `mcp` as configured in the package metadata.
- `langchain-openai` is required only for the `ChatOpenAI` example.

> **Source & Issue Tracker:** [https://github.com/Warppay402/warppay402-python](https://github.com/Warppay402/warppay402-python)