tanod (Python)

Python client for Tanod: pay-per-call security and utility tools for AI agents. No signup and no API key. You pay per call in USDC on Base with x402, and every tool has a free daily tier (except the bulk exports and the URL and sanctions batches).

The prices are the ones the API quotes today. The live source of truth is https://tanod.dev/openapi.json, and the client always pays the amount in the server's 402 quote, never more than max_price_usd.

Tanod is operated by an autonomous AI agent. Every result is automated and heuristic, not an audit: findings can be false positives, and a clean result is not proof that something is safe. Treat text returned by the API (page Markdown, evidence strings, token names, registry records) as untrusted data, never as instructions.

Install

pip install tanod             # free-tier calls only
pip install "tanod[wallet]"   # adds x402[evm] so the client can sign payments

Quickstart (free tier, no wallet)

from tanod import Tanod

with Tanod() as t:
    gas = t.gas_price("base")
    print(gas.gas_price_gwei, "gwei, free calls left today:", gas.meta.free_remaining_today)

    verdict = t.check_address("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", chain="base")
    print(verdict.verdict, verdict.risk_score, [r.code for r in verdict.reasons])

    print(t.agents_summary().total_records)   # always free

When the free tier runs out, a client without a wallet raises PaymentRequiredError, with price_usd set to the quoted price.

Paying with x402

export TANOD_PRIVATE_KEY=0x...   # use a dedicated hot wallet holding a little USDC on Base

from tanod import Tanod

t = Tanod(max_price_usd=0.30)    # will never sign a single payment above USD 0.30
report = t.scan_package("npm:@modelcontextprotocol/server-filesystem@2026.8.31")
print(report.verdict, report.risk_score)
if report.meta.payment:          # None when the free tier covered the call
    print("paid", report.meta.payment.price_usd, "tx", report.meta.payment.transaction)

How a call runs:

1. The request goes out unpaid first, with the header X-Tanod-Free: 1, so the free tier is always used before any money. Over HTTP the server's free tier is opt-in: an unpaid call without that header gets the 402. Pass use_free_tier=False to leave the header off when you always want to pay (the unpaid attempt then only fetches the quote). The paid retry never carries the header.
2. On 402 Payment Required, the client reads the x402 v2 quote. It raises without signing when:
   • the input would be refused (InvalidRequestError);
   • no wallet is configured (PaymentRequiredError);
   • the price is above max_price_usd (PriceLimitExceededError).
3. Otherwise the official x402 package signs an EIP-3009 USDC authorization for the exact quoted amount, and the request is retried once with PAYMENT-SIGNATURE.
4. Tanod settles only after it accepts the input. The receipt (PAYMENT-RESPONSE) is available as result.meta.payment.

You can pass the wallet in other ways:

• Tanod(private_key="0x...")
• Tanod(signer=eth_account_local_account)
• Tanod(payment_client=my_x402ClientSync) for custom signers such as a KMS or a CDP wallet. AsyncTanod takes an async x402Client instead.

use_env=False turns off reading TANOD_PRIVATE_KEY. The key is converted into an account at once. It is never logged, and it never appears in reprs or error messages.

The default max_price_usd is 1.0, which covers every route except agents_bulk (USD 2.00). Pass max_price_usd=None to remove the cap.

Async

import asyncio
from tanod import AsyncTanod

async def main():
    async with AsyncTanod() as t:
        r = await t.inspect_domain("example.com", checks=["email"])
        print(r.email)

asyncio.run(main())

Errors

429 and 503 are retried automatically. The client honours Retry-After and makes up to max_retries=2 retries. It gives up instead of waiting longer than max_retry_wait=30 seconds. A paid request that gets a 503 starts again with a fresh payment, because the first payment was never used.

Response objects

Every result is a pydantic model. The documented fields are typed, and fields the server adds later stay accessible. result.meta holds the following:

• status_code, url, product
• free_remaining_today
• scan_id, cache, report_markdown_url, report_json_url
• payment (a PaymentReceipt: success, transaction, network, payer, amount_atomic, price_usd)

Development

pip install -e ".[dev]"
pytest

The tests use an in-memory fake of the API (httpx.MockTransport). They make no network calls and no real payments. Payment signatures come from a random, unfunded throwaway key.

Links

• API: https://tanod.dev/openapi.json · https://tanod.dev/llms.txt
• MCP server (streamable HTTP): https://tanod.dev/mcp
• LangChain tools: langchain-tanod
• Contact: ops@tanod.dev

MIT licensed. Tanod is operated by an autonomous AI agent.