ddg-langchain

LangChain + CrewAI tools for DDG Agent Services — 376 pay-per-call x402 API routes on Base. Priced per call in USDC, no API key, no account, no KYC.

This package wraps three flagship routes as agent tools:

Install

pip install ddg-langchain                      # LangChain tools (no payment signing)
pip install "ddg-langchain[x402]"              # + automatic x402 settlement (EVM key)
pip install "ddg-langchain[crewai]"            # + CrewAI toolkit
pip install "ddg-langchain[dev]"               # everything + pytest

Quickstart — LangChain

from ddg_langchain import build_tools

tools = build_tools()          # 3 StructuredTools, ready for any agent
price = tools[1].invoke({"asset": "BTC"})
print(price["price"], price["_ddg"])

Quickstart — CrewAI

from ddg_langchain.crewai import DdgCrewAIToolkit
from crewai import Agent, Crew, Task, Process

toolkit = DdgCrewAIToolkit()
researcher = Agent(role="Researcher", goal="...", tools=toolkit.tools)
crew = Crew(agents=[researcher], tasks=[Task(..., agent=researcher)], process=Process.sequential)

Payment (x402) — how it settles

There is no API key. A route outside the free tier answers 402 with an x402 challenge; this package offers three behaviours:

1. Automatic settlement (recommended)

Set an EVM key. The client builds a requests.Session through the official x402 Python SDK (x402.x402ClientSync + x402_requests + EthAccountSigner), registers the exact EVM scheme pinned to Base (eip155:8453), and the SDK answers the 402, signs the EIP-3009 authorization, retries, and exposes the settle response.

export DDG_AGENT_ID=acme-research-agent      # stable identity -> X-Agent-Id (free tier key)
export DDG_EVM_PRIVATE_KEY=0x...             # wallet that pays the USDC
export DDG_MAX_PRICE_USD=0.05                # per-call cap (default 0.05)
python examples/langchain_agent.py

The wallet address is the payer; it needs USDC on Base (0x833589fC...02913). <amount> values in challenges are atomic USDC (6 decimals): 5000 = $0.005.

2. Out-of-band signature

Settle with any other x402 client (TypeScript x402-fetch, a facilitator, a hardware wallet flow) and hand the proof over:

export DDG_PAYMENT_SIGNATURE=<base64 PAYMENT-SIGNATURE>

3. Challenge-only (no key)

Tools still run, free tier works, and any paid call returns a JSON payload instead of raising:

{
  "status": "payment_required",
  "route": "/v1/price-feed",
  "accepts": [{ "network": "eip155:8453", "asset": "0x833589...02913",
                "amount": "5000", "payTo": "0x8AfBD522...30Bc6",
                "extra": { "name": "USD Coin", "version": "2" } }],
  "how_to_settle": "Set DDG_EVM_PRIVATE_KEY ... or send the base64 PAYMENT-SIGNATURE."
}

That is deliberate: an agent should be able to report a paywall rather than crash a crew. Programmatic callers who want the exception can use the client directly — DdgClient().price_feed("BTC") raises DdgPaymentRequired.

Spend cap

When a key is configured, every call is pre-flighted with a keyless request so the real challenge price is known before anything is signed. A quote above DDG_MAX_PRICE_USD raises DdgSpendLimitExceeded and nothing is paid.

API

from ddg_langchain import DdgClient, DdgConfig, build_tools, describe_routes

client = DdgClient(DdgConfig(
    base_url="https://agents.daedalusdevelopmentgroup.com",
    agent_id="acme-research-agent",
    private_key=None,        # or "0x..."
    max_price_usd=0.05,
    timeout=180,
))

client.web_search("x402 protocol", limit=5)
client.price_feed("BTC")
client.site_audit("https://example.com", business_type="saas", market="us-b2b")
client.last_settlement        # settle response from the last paid call, if any

Every successful return carries a _ddg metadata block:

"_ddg": {
  "route": "/v1/web-search",
  "status_code": 200,
  "price_usd": "$0.005",
  "payment_receipt": "ft-9ee46d0a911229b8-4684b8d3",
  "free_tier": true,
  "settled": false,
  "settlement": null
}

Environment variables: DDG_BASE_URL, DDG_AGENT_ID, DDG_EVM_PRIVATE_KEY, DDG_PAYMENT_SIGNATURE, DDG_MAX_PRICE_USD, DDG_TIMEOUT.

Tests

pytest                 # offline: fake transport, no keys, no network
pytest -m live         # real edge, free tier only (costs nothing)

The live tests assert that a fresh agent id gets a real 200 on the free tier and that the second call on the same identity returns a genuine 402 challenge with accepts[0].network == "eip155:8453".

Honest status / what is missing to go live

• Code is verified, the paid path is not. The offline suite passes, and the live tests drive the real edge end-to-end — but only on the free tier and the challenge path. No paid settlement has been executed by this package against the live edge, because that needs a funded Base wallet key.
• To go live you need: a wallet with USDC on Base, funded with at least DDG_MAX_PRICE_USD per call, exported as DDG_EVM_PRIVATE_KEY; the x402[evm] extra installed (pip install "ddg-langchain[x402]").
• Untested against real x402 settlement: the pre-flight-then-pay flow, the EIP-3009 signature the SDK produces for DDG's payTo, and last_settlement decoding. All three are exercised only with the fake transport today.
• Facilitator behaviour is DDG-side. If a settle ever fails (gas, rate limit, stale challenge), the failure surfaces as an HTTP error from the edge — see DDG's x402 debugger notes for the failure taxonomy.
• CrewAI is exercised only if the extra is installed; otherwise the whole tests/test_crewai.py module is skipped, and the toolkit's lazy import keeps LangChain-only installs lean.
• Not published to PyPI.

License

MIT