# Python: x402 with requests or httpx

Pay per call from Python with the x402 package: a requests Session (or httpx client) that answers 402s with a signed USDC payment.

For: Python 3.10+. Endpoint shape: `GET https://shop.lordevo.com/api/quick/<tool>?<input>` (HTTP 402 with x402 terms until paid). All guides: https://shop.lordevo.com/guides

## Prerequisites
- A wallet on Base mainnet holding a little USDC. One `dns-lookup` call costs $0.003; quick tools cost $0.003 to $0.02 per call, so $0.10 of USDC covers 33 `dns-lookup` calls. Payments are x402 `exact` USDC transfers that your wallet signs; the facilitator submits them, so the wallet needs no ETH for gas.
- The wallet's private key in the environment variable `AGENT_WALLET_KEY`, never in code. Use a separate agent wallet with a small balance: an x402 client pays the amount the 402 asks for (the shop's prices are fixed per tool, listed in https://shop.lordevo.com/catalog.json).
- No account, sign-up or API key. Instant tools that fail or are refused are not charged. Long jobs (202) are charged when accepted and are not refunded automatically if they fail later. If a paid job failed, email hello@lordevo.com with the transaction hash and we'll review it, usually within 2 business days.
- To try without a wallet: 3 free calls per IP per UTC day on the 52 tools priced up to $0.005 (opt-in, see below).

## Pay per call: requests (sync)
Save as `lordevo.py`. The helper also does the free trial, and is reused by the LangChain, CrewAI and OpenAI Agents guides.
```python
# pip install "x402[requests,evm]" eth_account requests
import json, os, time
import requests
from eth_account import Account
from x402 import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

BASE = "https://shop.lordevo.com"
pay = None  # a requests.Session that pays x402 402s in USDC on Base; without AGENT_WALLET_KEY only free trial calls work
if os.environ.get("AGENT_WALLET_KEY"):
    _x402 = x402ClientSync()
    register_exact_evm_client(_x402, EthAccountSigner(Account.from_key(os.environ["AGENT_WALLET_KEY"])))
    pay = x402_requests(_x402)
_no_trial_until = 0.0  # after "used_up_today", skip the free attempt until 00:00 UTC


class LordevoError(Exception):
    def __init__(self, status, body=None, retry_after=None, message=None):
        self.status, self.body, self.retry_after = status, body, retry_after
        super().__init__(message or (body or {}).get("message") or f"HTTP {status}")


def _answer(r):
    try:
        body = r.json()
    except ValueError:
        body = None
    if r.status_code < 400:
        return body
    raise LordevoError(r.status_code, body if isinstance(body, dict) else None, int(r.headers.get("retry-after") or 0) or None)


def lordevo(tool, params=None, trial=False):
    """One Lordevo call. trial=True asks for a free call first and pays only when no free call is left.
    Raises LordevoError(status, body, retry_after); refused or failed calls are not charged."""
    global _no_trial_until
    url = f"{BASE}/api/quick/{tool}"
    q = {k: str(v) for k, v in (params or {}).items() if v not in (None, "")}
    if trial and time.time() >= _no_trial_until:
        r = requests.get(url, params=q, headers={"accept": "application/json", "x-lordevo-trial": "1"}, timeout=60)
        if r.status_code != 402:
            return _answer(r)
        why = ((r.json() or {}).get("free_trial") or {}).get("status")
        if why in ("used_up_today", "daily_cap_reached"):
            _no_trial_until = (int(time.time()) // 86400 + 1) * 86400
        if pay is None:
            raise LordevoError(402, message=f"No free call left ({why or 'not_eligible'}); set AGENT_WALLET_KEY to pay per call.")
    if pay is None:
        raise LordevoError(402, message="Set AGENT_WALLET_KEY to pay per call, or use trial=True.")
    return _answer(pay.get(url, params=q, headers={"accept": "application/json"}, timeout=60))


def lordevo_tool(tool, params):
    """For agent tools: errors come back as JSON the model can read, instead of an exception."""
    try:
        return json.dumps(lordevo(tool, params, trial=True))
    except LordevoError as e:
        return json.dumps({"error": (e.body or {}).get("error") or f"http_{e.status}", "message": str(e), "retry_after_seconds": e.retry_after, "charged": False})


if __name__ == "__main__":
    print(lordevo("dns-lookup", {"host": "example.com"}, trial=True))
```

## Try it free (no wallet)
Leave `AGENT_WALLET_KEY` unset and call `lordevo(..., trial=True)`: it sends `X-Lordevo-Trial: 1` and no payment (3 free calls per IP per UTC day on tools up to $0.005). With the key set, `trial=True` uses the free calls first and then pays.

## Pay per call: httpx (async)
```python
# pip install "x402[httpx,evm]" eth_account
import asyncio, os
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

client = x402Client()
register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ["AGENT_WALLET_KEY"])))


async def main():
    async with x402HttpxClient(client) as http:
        r = await http.get("https://shop.lordevo.com/api/quick/dns-lookup", params={"host": "example.com"}, headers={"accept": "application/json"})
        await r.aread()
        print(r.status_code, r.json() if r.status_code < 500 else r.text)

asyncio.run(main())
```

Or use the shop's own client: `pip install "lordevo-x402>=0.1.5"` (`LordevoSync.from_private_key(...)`, `try_free(...)`; LangChain and CrewAI tools built in).

## Errors (nothing is charged on any of these)
- **400 / 422**: bad or unusable input (body `{"error", "message", "charged": false}`). Fix the input; do not retry as is.
- **403**: robots.txt does not allow the shop to fetch that URL. Pick another URL.
- **402**: payment needed. On a trial request, `free_trial.status` says why: `used_up_today` (3 free calls used; resets 00:00 UTC), `daily_cap_reached` (the shop's daily trial cap) or `not_eligible` (tool above $0.005). Pay per call instead. With a paying client, a final 402 means the payment was not accepted: check the USDC balance on Base (eip155:8453).
- **429 / 503**: busy or rate-limited. Wait `Retry-After` seconds, then retry once.
- **409** `payment_in_use`: the same signed payment was sent twice at once. Make a new call.

`lordevo()` raises `LordevoError` with `.status`, `.body` and `.retry_after`; `lordevo_tool()` returns the same as JSON for agent tools.

## Next tools to try
- `can-fetch` ($0.003, free trial ok): Can I fetch this URL? robots.txt + AI-crawler permission gate. `GET https://shop.lordevo.com/api/quick/can-fetch?url=https://example.com/blog/post`
- `page-markdown` ($0.003, free trial ok): URL to Markdown: LLM-ready web page reader (main content). `GET https://shop.lordevo.com/api/quick/page-markdown?url=https://example.com`
- `site-check` ($0.02): Site check: URL risk signals + AI readiness + security headers (recommended start). `GET https://shop.lordevo.com/api/quick/site-check?url=https://example.com`
- `email-validate` ($0.003, free trial ok): Email validation / email verification API (syntax + domain + MX, no SMTP probing). `GET https://shop.lordevo.com/api/quick/email-validate?email=jane@example.com`
- `pdf-text` ($0.003, free trial ok): PDF to text, page by page. `GET https://shop.lordevo.com/api/quick/pdf-text?url=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf`
- All 58 tools with prices and inputs: https://shop.lordevo.com/catalog.json, https://shop.lordevo.com/llms.txt, https://shop.lordevo.com/quick

## Checked
Written 2026-10-30 against the current public docs:
- https://docs.x402.org/getting-started/quickstart-for-buyers (x402 Python, requests and httpx clients)
- https://pypi.org/project/x402/ (x402 2.26.0)
The snippets follow those docs; they were not executed end to end by the shop. Tell us if something has moved: hello@lordevo.com
