# LangChain (Python): a paid @tool for create_agent

Give a LangChain Python agent one of the shop's tools: a @tool function, paid per call with x402, free trial first.

For: LangChain 1.x. 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

Easier: use the SDK: https://shop.lordevo.com/guides/sdk/langchain-python

## 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).

## Code
Put the helper from https://shop.lordevo.com/guides/python in `lordevo.py` next to this file.
```python
# pip install langchain   (plus the helper's packages)
import os
from langchain.agents import create_agent
from langchain.tools import tool
from lordevo import lordevo_tool  # tries a free trial call first (X-Lordevo-Trial: 1), then pays


@tool
def dns_lookup(host: str, type: str | None = None) -> str:
    """DNS records lookup (A, AAAA, CNAME, MX, TXT, NS, SOA, CAA). Costs $0.003 per call (x402, USDC on Base); 3 free trial calls per IP per UTC day (shared by all tools up to $0.005). 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.

    Args:
        host: Host name to look up, e.g. example.com or mail.example.com (a URL also works; the host part is used)
        type: Record type (default ALL = A, AAAA, CNAME, MX, TXT, NS, SOA, CAA) One of ALL, A, AAAA, CNAME, MX, TXT, NS, SOA, CAA.
    """
    return lordevo_tool("dns-lookup", {"host": host, "type": type})


# Any chat model LangChain supports, e.g. "openai:<model>" or "anthropic:<model>" (provider key in its usual env variable).
agent = create_agent(os.environ["LANGCHAIN_MODEL"], tools=[dns_lookup])
out = agent.invoke({"messages": [{"role": "user", "content": "Use the dns_lookup tool on example.com and summarise the answer."}]})
print(out["messages"][-1].content)
```

Or all 58 tools at once from the shop's package: `pip install "lordevo-x402>=0.1.5"`, then `from lordevo_x402.langchain import langchain_tools` and `langchain_tools(sync_client=LordevoSync.from_private_key(os.environ["AGENT_WALLET_KEY"]))`.

## Try it free (no wallet)
`lordevo_tool()` always tries a free call first (3 per IP per UTC day on tools up to $0.005). Without `AGENT_WALLET_KEY` the agent gets `{"error": "http_402", ...}` once they are used up.

## 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.

The tool never raises: errors reach the model as JSON (`error`, `message`, `retry_after_seconds`, `charged: false`).

## 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.langchain.com/oss/python/langchain/tools (@tool from langchain.tools, create_agent)
- https://pypi.org/project/langchain-core/ (langchain-core 1.7.3)
The snippets follow those docs; they were not executed end to end by the shop. Tell us if something has moved: hello@lordevo.com
