Metadata-Version: 2.4
Name: haystack-spraay
Version: 0.1.0
Summary: Spraay x402 Gateway integration for Haystack - multi-chain batch payments, balances, RPC, and oracles for AI agents
Project-URL: Homepage, https://github.com/plagtech/haystack-spraay
Project-URL: Documentation, https://docs.spraay.app
Project-URL: Repository, https://github.com/plagtech/haystack-spraay
Project-URL: Issues, https://github.com/plagtech/haystack-spraay/issues
Author-email: plagtech <hello@spraay.app>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: USDC,ai-agents,batch-payments,blockchain,crypto,defi,haystack,multi-chain,payments,spraay,web3,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: haystack-ai>=2.6.0
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# 💧 haystack-spraay

[![PyPI](https://img.shields.io/pypi/v/haystack-spraay)](https://pypi.org/project/haystack-spraay/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

[Spraay x402 Gateway](https://gateway.spraay.app) integration for [Haystack](https://haystack.deepset.ai/) — multi-chain batch payments, balance checks, RPC calls, and oracle prices for AI agents and pipelines.

## What is Spraay?

Spraay is a multi-chain batch payment protocol and x402 gateway that lets AI agents make USDC micropayments across 16+ blockchains. The gateway exposes 76+ paid endpoints covering payments, RPC, oracles, AI inference, storage, and more — all payable via the [x402 HTTP payment protocol](https://github.com/coinbase/x402).

## What is Haystack?

Haystack is an open-source AI orchestration framework by [deepset](https://www.deepset.ai/) for building production-ready LLM applications with modular pipelines and agent workflows.

## Installation

```bash
pip install haystack-spraay
```

## Quick Start — Agent with Payment Tools

```python
import os
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack_spraay.tools import spraay_batch_payment, spraay_check_balance, spraay_oracle_price

os.environ["OPENAI_API_KEY"] = "<YOUR_KEY>"

# Create an agent with Spraay payment tools
agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
    tools=[spraay_batch_payment, spraay_check_balance, spraay_oracle_price],
    system_prompt="You are a helpful blockchain payment assistant. You can send payments, check balances, and look up token prices across 16+ blockchains.",
)

# Run it
result = agent.run(
    messages=[ChatMessage.from_user("What's the current price of ETH in USD?")]
)
print(result["last_message"].text)
```

## Quick Start — Pipeline Component

```python
from haystack import Pipeline
from haystack_spraay.components import SpraayBalanceCheck, SpraayBatchPayment

# Use components directly
balance_checker = SpraayBalanceCheck(chain="base")
result = balance_checker.run(address="0xAd62f03C7514bb8c51f1eA70C2b75C37404695c8")
print(result)

# Or in a pipeline
pipeline = Pipeline()
pipeline.add_component("balance", SpraayBalanceCheck(chain="base"))
result = pipeline.run({"balance": {"address": "0x1234...", "token": "USDC"}})
```

## Available Components

| Component | Description |
|-----------|-------------|
| `SpraayBatchPayment` | Send batch USDC payments to multiple recipients |
| `SpraayBalanceCheck` | Check token balances on any chain |
| `SpraayGasPrice` | Get real-time gas prices |
| `SpraayRPCCall` | Make raw JSON-RPC calls to any chain |
| `SpraayOraclePrice` | Get real-time token prices |

## Available Tools (for Agents)

| Tool | Description |
|------|-------------|
| `spraay_batch_payment` | Send multi-recipient payments |
| `spraay_check_balance` | Query wallet balances |
| `spraay_gas_price` | Estimate transaction costs |
| `spraay_rpc_call` | Raw blockchain queries |
| `spraay_oracle_price` | Token price lookups |

## Supported Chains

Base, Ethereum, Arbitrum, Polygon, BNB Chain, Avalanche, Solana, Stellar, XRP Ledger, Bitcoin, BOB, Unichain, Plasma, Bittensor, Stacks.

## Advanced: Multi-Step Payment Pipeline

```python
from haystack import Pipeline
from haystack_spraay.components import (
    SpraayBalanceCheck,
    SpraayGasPrice,
    SpraayBatchPayment,
)

# Build a payment pipeline: check balance → estimate gas → send payment
pipeline = Pipeline()
pipeline.add_component("balance", SpraayBalanceCheck(chain="base"))
pipeline.add_component("gas", SpraayGasPrice())
pipeline.add_component("payment", SpraayBatchPayment(chain="base"))

# Run steps individually or connect them with custom routing logic
balance_result = pipeline.run(
    {"balance": {"address": "0xSenderAddr", "token": "USDC"}}
)
```

## Advanced: Use with Haystack Agent + Other Tools

```python
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.tools import ComponentTool
from haystack.components.websearch import SerperDevWebSearch
from haystack_spraay.tools import spraay_batch_payment, spraay_oracle_price

# Combine Spraay tools with web search
search_tool = ComponentTool(
    component=SerperDevWebSearch(api_key=Secret.from_env_var("SERPERDEV_API_KEY")),
    name="web_search",
    description="Search the web for information",
)

agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o"),
    tools=[spraay_batch_payment, spraay_oracle_price, search_tool],
    system_prompt=(
        "You are a crypto research assistant that can search the web, "
        "check token prices, and send payments when instructed."
    ),
)
```

## Architecture

```
┌──────────────┐     ┌───────────────┐     ┌─────────────────┐
│  Haystack    │────▶│  Agent /       │────▶│  Spraay Tools   │
│  Pipeline    │     │  ToolInvoker   │     │  & Components   │
└──────────────┘     └───────────────┘     └────────┬────────┘
                                                     │
                                           ┌─────────▼─────────┐
                                           │  Spraay x402       │
                                           │  Gateway            │
                                           │  gateway.spraay.app │
                                           └─────────┬─────────┘
                                                     │
                                     ┌───────────────┼───────────────┐
                                     │               │               │
                               ┌─────▼───┐    ┌─────▼───┐    ┌─────▼───┐
                               │  Base    │    │  Solana  │    │  15+    │
                               │          │    │          │    │  more   │
                               └─────────┘    └─────────┘    └─────────┘
```

## Contributing

1. Clone: `git clone https://github.com/plagtech/haystack-spraay.git`
2. Install dev deps: `pip install -e ".[dev]"`
3. Run tests: `pytest tests/ -v`

## Links

- **Spraay Gateway:** [gateway.spraay.app](https://gateway.spraay.app)
- **Spraay Docs:** [docs.spraay.app](https://docs.spraay.app)
- **Spraay MCP Server:** [@plagtech/spraay-x402-mcp](https://smithery.ai/server/@plagtech/spraay-x402-mcp)
- **Haystack:** [haystack.deepset.ai](https://haystack.deepset.ai)
- **Haystack Integrations:** [github.com/deepset-ai/haystack-integrations](https://github.com/deepset-ai/haystack-integrations)
- **x402 Protocol:** [github.com/coinbase/x402](https://github.com/coinbase/x402)

## Payment Address

All x402 payments route to: `0xAd62f03C7514bb8c51f1eA70C2b75C37404695c8`

## License

Apache-2.0

## Author

Built by [@plagtech](https://github.com/plagtech) | [@plag](https://warpcast.com/plag) on Farcaster | [@Spraay_app](https://twitter.com/Spraay_app)
