golfgolfgolf200 commited on
Commit
be34ff5
·
verified ·
1 Parent(s): 85a114c

Add Hugging Face model card metadata

Browse files
Files changed (1) hide show
  1. README.md +183 -0
README.md ADDED
@@ -0,0 +1,183 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ license: mit
3
+ tags:
4
+ - mcp
5
+ - mcp-server
6
+ - warppay
7
+ - x402
8
+ - python
9
+ - ai-agents
10
+ ---
11
+
12
+ # warppay402-mcp
13
+
14
+ [![M8ven Score](https://m8ven.ai/badge/mcp/warppay402-warppay402-python-1g5nyh)](https://m8ven.ai/mcp/warppay402-warppay402-python-1g5nyh?s=readme)
15
+
16
+ LangChain-compatible `BaseTool` wrappers for WarpPay402 x402 micropayment APIs.
17
+
18
+ ## Overview
19
+
20
+ 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`.
21
+
22
+ ## Accepted payment options
23
+
24
+ The WarpPay402 server accepts the following payment methods for tool usage:
25
+
26
+ - Base USDC
27
+ - Arbitrum One USDC
28
+ - Solana USDC
29
+ - Arc USDC
30
+
31
+ ## Installation
32
+
33
+ Install the base package:
34
+
35
+ ```bash
36
+ pip install warppay402-mcp
37
+ ```
38
+
39
+ This includes the required runtime dependencies (`requests`, `langchain-core`, and `mcp`).
40
+
41
+ If you want to run the LangChain/OpenAI or LlamaIndex examples below, install the optional integration packages:
42
+
43
+ ```bash
44
+ pip install langchain-openai
45
+ pip install "warppay402-mcp[llamaindex]" llama-index-llms-openai
46
+ ```
47
+
48
+ ## Available tools
49
+
50
+ The package currently includes these tools:
51
+
52
+ | Tool | Price | Server capability | Typical call signature |
53
+ | --- | --- | --- | --- |
54
+ | `ArcDexOracleTool` | $0.001 USDC | Arc DEX spot price & liquidity oracle | `run(pair="ETH/USDC")` |
55
+ | `WebScraperTool` | $0.001 USDC | Public webpage to Markdown extraction | `run(url)` |
56
+ | `BrowserScraperTool` | $0.005 USDC | JS-rendered page scraping via browser | `run(url)` |
57
+ | `BaseAnalyticsTool` | $0.002 USDC | Wallet balance / nonce / account stats on Base | `run(address)` |
58
+ | `ArcAnalyticsTool` | $0.001 USDC | Arc network block / gas / latency telemetry | `run()` |
59
+ | `ArcNetworkQueryTool` | $0.10 USDC | Pre-flight Arc node + gas + merchant checks | `run(includeGasTrends=True, checkMerchantAccount=True)` |
60
+ | `PdfExtractorTool` | $0.005 USDC | Public PDF text extraction | `run(pdfUrl)` |
61
+ | `RenderScreenshotTool` | $0.01 USDC | Full-page screenshot capture | `run(url)` |
62
+ | `ExtractJsonTool` | $0.01 USDC | Schema-driven JSON extraction from HTML | `run(url, schema=None)` |
63
+ | `SmartContractVerifierTool` | $0.02 USDC | Contract source / ABI / proxy verification | `run(address)` |
64
+ | `AerodromeYieldsTool` | $0.003 USDC | Top yield pools and APY data | `run()` |
65
+ | `AerodromeSwapTool` | $0.01 USDC | Aerodrome router token swap execution | `run(tokenIn, tokenOut, amountIn, decimalsIn, isStable)` |
66
+ | `AerodromeClammTool` | $0.01 USDC | Constrained liquidity range actions | `run(action, token0=None, token1=None, tickLower=None, tickUpper=None, amount0Desired=None, amount1Desired=None, tokenId=None)` |
67
+ | `AerodromeVeaeroTool` | $0.01 USDC | Lock / vote / claim AERO governance actions | `run(action, amount=None, lockDurationWeeks=None, tokenId=None, poolVoteAddresses=None)` |
68
+ | `DeployBaseContractTool` | $5.00 USDC | Deploy contracts on Base | `run(contractType="escrow")` |
69
+ | `DeploySolanaContractTool` | $5.00 USDC | Deploy Solana contracts / vaults | `run(contractType, params)` |
70
+ | `DeployArcContractTool` | $5.00 USDC | Deploy contracts on Arc | `run(contractType="escrow")` |
71
+ | `ArcCctpBridgeTool` | $0.25 USDC | Cross-chain USDC bridge via CCTP | `run(amountUsdc, destinationChain, recipientAddress)` |
72
+ | `PublicDataFeedTool` | $0.0001 USDC | Signed public data feed retrieval | `run(filename)` |
73
+ | `DataFeedsTool` | $0.001 USDC | Market / yield feed retrieval | `run(feedId)` |
74
+ | `RealEstateCalculatorTool` | $0.0005 USDC | Real estate Cap Rate, NOI, and DSCR calculator | `run(purchasePrice, monthlyRent)` |
75
+ | `AddressNormalizerTool` | $0.001 USDC | Address geocoding & lat/lon resolution | `run(address)` |
76
+ | `WeatherOracleTool` | $0.001 USDC | Atmospheric weather & drone flight safety oracle | `run(latitude, longitude)` |
77
+ | `ForexOracleTool` | $0.0005 USDC | Global foreign exchange fiat spot rates | `run(baseCurrency="USD")` |
78
+ | `ShippingRateEstimatorTool` | $0.001 USDC | Domestic USPS parcel shipping rate estimator | `run(weightLbs, originZip, destinationZip)` |
79
+ | `GithubHealthAnalyzerTool` | $0.002 USDC | GitHub repository stars, issues & license inspector | `run(repository)` |
80
+ | `PropertyCompsEstimatorTool` | $0.005 USDC | Property valuations & tax assessor comps | `run(squareFeet, bedrooms, zipCode)` |
81
+ | `OutageOracleTool` | $0.002 USDC | Real-time power, ISP, and cellular outage oracle | `run(zipCode, state=None, serviceType="all")` |
82
+ | `UcpDealsOracleTool` | $0.001 USDC | UCP merchant product catalog & deals oracle | `run(query, maxPriceUSD=None, inStockOnly=True)` |
83
+
84
+ 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.
85
+
86
+ ## Quickstart
87
+
88
+ ### Direct tool usage
89
+
90
+ ```python
91
+ from warppay402_mcp.tools import ArcDexOracleTool, AerodromeYieldsTool, WebScraperTool
92
+
93
+ oracle = ArcDexOracleTool()
94
+ print(oracle.run("ETH/USDC"))
95
+
96
+ yields_tool = AerodromeYieldsTool()
97
+ print(yields_tool.run())
98
+
99
+ scraper = WebScraperTool()
100
+ print(scraper.run("https://example.com"))
101
+ ```
102
+
103
+ ### LangChain agent usage
104
+
105
+ ```python
106
+ from langchain.agents import AgentType, initialize_agent
107
+ from langchain_openai import ChatOpenAI
108
+
109
+ from warppay402_mcp.tools import ArcDexOracleTool
110
+
111
+ llm = ChatOpenAI(model="gpt-4o-mini")
112
+ tools = [ArcDexOracleTool()]
113
+
114
+ agent = initialize_agent(
115
+ tools=tools,
116
+ llm=llm,
117
+ agent=AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION,
118
+ )
119
+
120
+ result = agent.invoke("What is the current ETH/USDC spot price?")
121
+ print(result)
122
+ ```
123
+
124
+ ## Example tool details
125
+
126
+ ### `ArcDexOracleTool`
127
+
128
+ - Name: `arc_dex_oracle`
129
+ - Description: Real-time ETH/USDC spot price resolver and DEX liquidity oracle for Arc Mainnet ($0.001 USDC).
130
+ - Default pair: `ETH/USDC`
131
+
132
+ ```python
133
+ from warppay402_mcp.tools import ArcDexOracleTool
134
+
135
+ tool = ArcDexOracleTool()
136
+ print(tool.run("ETH/USDC"))
137
+ ```
138
+
139
+ ### `AerodromeYieldsTool`
140
+
141
+ - Name: `get_aerodrome_yields`
142
+ - Description: Fetches top live Aerodrome DEX yield pools, APYs, and TVL on Base Mainnet ($0.003 USDC).
143
+
144
+ ```python
145
+ from warppay402_mcp.tools import AerodromeYieldsTool
146
+
147
+ tool = AerodromeYieldsTool()
148
+ print(tool.run())
149
+ ```
150
+
151
+ ### LlamaIndex agent usage
152
+
153
+ First, install LlamaIndex support:
154
+
155
+ ```bash
156
+ pip install "warppay402-mcp[llamaindex]" llama-index-llms-openai
157
+ ```
158
+
159
+ Then pass the converted tools directly into any LlamaIndex agent:
160
+
161
+ ```python
162
+ from llama_index.core.agent import ReActAgent
163
+ from llama_index.llms.openai import OpenAI
164
+ from warppay402_mcp import WarpPayLlamaIndexTools
165
+
166
+ # Retrieve all 29 tools wrapped as LlamaIndex FunctionTools
167
+ tools = WarpPayLlamaIndexTools.get_tools()
168
+
169
+ # Attach tools to a LlamaIndex Agent
170
+ agent = ReActAgent.from_tools(tools, llm=OpenAI(model="gpt-4o-mini"), verbose=True)
171
+
172
+ response = agent.chat("What is the current ETH/USDC spot price on Arc Mainnet?")
173
+ print(response)
174
+ ```
175
+
176
+ ## Notes
177
+
178
+ - The package exports `ArcDexOracleTool` at the package root, but the full tool set is defined in `warppay402_mcp.tools`.
179
+ - Many tools accept simple Python arguments and return raw API response text as a string.
180
+ - This project depends on `requests`, `langchain-core`, and `mcp` as configured in the package metadata.
181
+ - `langchain-openai` is required only for the `ChatOpenAI` example.
182
+
183
+ > **Source & Issue Tracker:** [https://github.com/Warppay402/warppay402-python](https://github.com/Warppay402/warppay402-python)