Metadata-Version: 2.5
Name: x402serps
Version: 1.0.0
Summary: Client for x402serps, a third-party search provider: web search, news, extraction, research, SEO and lead APIs for AI agents (x402 USDC or a prepaid credit key).
Project-URL: Homepage, https://x402serps.com/integrations?utm_campaign=100sales
Project-URL: Documentation, https://x402serps.com/docs
Project-URL: Help, https://x402serps.com/help
Author-email: x402serps <hello@x402serps.com>
License: MIT
License-File: LICENSE
Keywords: ai-agents,mcp,search,serp,x402
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Provides-Extra: x402
Requires-Dist: x402[httpx]>=2.27; extra == 'x402'
Description-Content-Type: text/markdown

# x402serps

Python client for [x402serps](https://x402serps.com/integrations?utm_campaign=100sales), a third-party search provider for AI agents.

Pay per call with x402 (USDC on Base or Solana), a prepaid credit key, or the 25-call trial. Search is $0.004 per 10 results. Extract is $0.003 per URL. MCP includes 20 free `web_search` / `extract` calls per day.

## Two-minute quickstart (trial)

```bash
pip install x402serps
```

```python
from x402serps import X402Serps

xs = X402Serps(trial=True)
print(xs.search("x402 payments protocol", num=5)["results"])
```

The trial covers `/api/v1/search`, `news`, `extract`, `images`, `places`, `shopping`, `scholar` and `videos` (25 calls per client network). After that, use a credit key or x402.

## Prepaid credit key

Buy a key at [pricing](https://x402serps.com/pricing?utm_campaign=100sales#credits) and pass it (or set `X402SERPS_API_KEY`):

```python
from x402serps import X402Serps

xs = X402Serps(api_key="xs_...")
print(xs.search("x402 payments protocol")["results"])
```

## Pay per call with x402 (Base or Solana)

The official [`x402`](https://pypi.org/project/x402/) package wraps `httpx.AsyncClient` so a 402 is retried with a payment header. Use `AsyncX402Serps` and pass that client:

```bash
pip install "x402serps[x402]" "x402[httpx,evm]"
# For Solana: pip install "x402[httpx,svm]"
```

```python
import asyncio
from x402 import x402Client
from x402.http.clients import wrapHttpxWithPayment
from x402.mechanisms.evm.exact import ExactEvmScheme
from x402serps import AsyncX402Serps

# `signer` is your EVM account signer (see x402 EVM docs).
x402 = x402Client()
x402.register("eip155:*", ExactEvmScheme(signer=signer))

async def main():
    http = wrapHttpxWithPayment(x402)
    async with AsyncX402Serps(client=http) as xs:
        data = await xs.search("x402 payments protocol")
        print(data["results"])

asyncio.run(main())
```

Register a Solana scheme the same way (`ExactSvmScheme` on `solana:*`) if you want to pay on Solana.

If a call is unpaid, the client raises `PaymentRequiredError` (`status == 402`) with `accepts` and any trial status header.

```python
from x402serps import PaymentRequiredError, X402Serps

try:
    X402Serps().search("x402")
except PaymentRequiredError as err:
    print(err, err.accepts)
```

## Async trial or credit-key client

```python
import asyncio
from x402serps import AsyncX402Serps

async def main():
    async with AsyncX402Serps(trial=True) as xs:
        data = await xs.search("x402 payments protocol", num=5)
        print(data["results"], "remaining", xs.trial_remaining)

asyncio.run(main())
```

## API

Every `/api/v1` route has a method. Keyword arguments are merged into the JSON body.

| Method | Path | Notes |
| --- | --- | --- |
| `search(q, **kw)` | `/api/v1/search` | $0.004 / 10 results |
| `news`, `images`, `places`, `shopping`, `scholar`, `videos` | matching path | same search price |
| `extract(url or urls, **kw)` | `/api/v1/extract` | $0.003 / URL |
| `search_extract`, `answer`, `crawl`, `map` | matching path | |
| `batch(queries, **kw)` | `/api/v1/batch` | |
| `research`, `visibility`, `competitor_report`, `leads`, `seo_audit`, `news_digest` | matching path | paid endpoints, not in the trial |
| `balance()` | `/api/v1/balance` | credit key |
| `create_monitor`, `list_monitors`, `get_monitor`, `delete_monitor` | `/api/v1/monitors` | |

Use `request(path, body, method)` for a custom path (for example with schemas from [tools.json](https://x402serps.com/tools.json)). After a trial call, `xs.trial_remaining` holds the remaining quota when the server sends it.

## LangChain

Install [`langchain-x402serps`](https://pypi.org/project/langchain-x402serps/) for ready-made tools, or wrap this client yourself:

```python
from langchain_core.tools import tool
from x402serps import X402Serps

xs = X402Serps(trial=True)

@tool
def web_search(query: str) -> str:
    """Search the web for current information."""
    return str(xs.search(query, num=8)["results"])
```

## More

- Integrations: https://x402serps.com/integrations?utm_campaign=100sales
- Pricing: https://x402serps.com/pricing?utm_campaign=100sales
- MCP: https://x402serps.com/mcp?utm_campaign=100sales (20 free calls/day)
- Help: https://x402serps.com/help
- JavaScript: `npm install x402serps`
