Metadata-Version: 2.4
Name: langchain-spraay
Version: 0.2.0
Summary: LangChain tools for Spraay — multi-chain batch payments and x402 gateway for AI agents
Author-email: Plag <spraay@spraay.app>
License: MIT
Project-URL: Homepage, https://spraay.app
Project-URL: Repository, https://github.com/plagtech/langchain-spraay
Project-URL: Documentation, https://docs.spraay.app
Project-URL: Gateway, https://gateway.spraay.app
Project-URL: Issue Tracker, https://github.com/plagtech/langchain-spraay/issues
Keywords: langchain,spraay,x402,batch-payments,crypto,base,ai-agents,web3,erc20,defi
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-core>=0.2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.28.0
Provides-Extra: onchain
Requires-Dist: web3>=6.0; extra == "onchain"
Provides-Extra: all
Requires-Dist: web3>=6.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# langchain-spraay

LangChain tools for [Spraay](https://spraay.app) — multi-chain batch payments and x402 payment gateway for AI agents.

[![PyPI](https://img.shields.io/pypi/v/langchain-spraay)](https://pypi.org/project/langchain-spraay/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

`langchain-spraay` provides LangChain-compatible tools that let AI agents:

- **Send batch payments** to up to 200 recipients in a single transaction across 13+ chains
- **Access 200+ AI models** via pay-per-request (no API keys needed)
- **Query price oracles**, execute DeFi swaps, manage payroll, and more
- **Pay with USDC on Base** via the x402 payment protocol — no accounts, no API keys

## Installation

```bash
# Gateway tools (HTTP-based, no web3 needed)
pip install langchain-spraay

# Include on-chain smart contract tools
pip install langchain-spraay[onchain]
```

## Quick Start

### Gateway Tools (Recommended)

```python
import os
from langchain_spraay import SpraayGatewayTool, SpraayToolkit

os.environ["SPRAAY_PRIVATE_KEY"] = "your-private-key-with-usdc-on-base"

# Use individual tools
tool = SpraayGatewayTool()
result = tool.invoke({
    "endpoint": "/price/eth",
    "method": "GET"
})

# Or load all tools via toolkit
toolkit = SpraayToolkit()
tools = toolkit.get_tools()  # 4 gateway tools ready to use
```

### Batch Payments

```python
from langchain_spraay import SpraayBatchPaymentTool

tool = SpraayBatchPaymentTool()
result = tool.invoke({
    "chain": "base",
    "token": "USDC",
    "recipients": ["0xAbc...", "0xDef...", "0x123..."],
    "amounts": ["100", "250", "50"]
})
```

### AI Inference

```python
from langchain_spraay import SpraayAIInferenceTool

tool = SpraayAIInferenceTool()
result = tool.invoke({
    "prompt": "Explain quantum computing in one paragraph",
    "model": "gpt-4o-mini",
    "provider": "openrouter"
})
```

### On-Chain Tools

```python
from langchain_spraay import SpraayBatchSendETH

tool = SpraayBatchSendETH()
result = tool.invoke({
    "recipients": ["0xAbc...", "0xDef..."],
    "amount_per_recipient_eth": "0.01"
})
```

### With LangChain Agents

```python
from langchain_spraay import SpraayToolkit
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

llm = ChatOpenAI(model="gpt-4o-mini")
toolkit = SpraayToolkit(include_onchain=True)
tools = toolkit.get_tools()

agent = create_react_agent(llm, tools)
result = agent.invoke({
    "messages": [{"role": "user", "content": "Send 0.01 ETH to 0xAbc... and 0xDef..."}]
})
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SPRAAY_PRIVATE_KEY` | Yes | Private key of wallet with USDC on Base |
| `SPRAAY_GATEWAY_URL` | No | Gateway URL (default: `https://gateway.spraay.app`) |
| `SPRAAY_RPC_URL` | No | RPC URL for on-chain tools (default: `https://mainnet.base.org`) |
| `SPRAAY_CONTRACT_ADDRESS` | No | Spraay V2 contract address (default: mainnet) |

## Available Tools

### Gateway Tools
| Tool | Description |
|------|-------------|
| `SpraayGatewayTool` | Generic access to all 76+ gateway endpoints |
| `SpraayBatchPaymentTool` | Multi-chain batch payments (13+ chains) |
| `SpraayAIInferenceTool` | AI inference (200+ models, 3 providers) |
| `SpraayPriceOracleTool` | Real-time crypto price lookups |

### On-Chain Tools (require `web3`)
| Tool | Description |
|------|-------------|
| `SpraayBatchSendETH` | Batch send equal ETH amounts |
| `SpraayBatchSendToken` | Batch send equal ERC-20 amounts |
| `SpraayBatchSendETHVariable` | Batch send variable ETH amounts |
| `SpraayBatchSendTokenVariable` | Batch send variable ERC-20 amounts |

## Supported Chains

Base, Ethereum, Arbitrum, Polygon, BNB Chain, Avalanche, Optimism, Solana, Bitcoin (PSBT), XRP Ledger, Bittensor, Stacks, BOB

## Links

- [Spraay Gateway](https://gateway.spraay.app)
- [Documentation](https://docs.spraay.app)
- [MCP Server](https://smithery.ai/server/@plagtech/spraay-x402-mcp)
- [GitHub](https://github.com/plagtech/langchain-spraay)

## License

MIT
