pylonapi

Python SDK for the Pylon Agent Gateway — one endpoint for every tool an agent needs.

20+ capabilities (screenshot, web scrape, OCR, PDF parse, email validate, DNS lookup, translate, and more) accessible through a single API. Payments handled automatically via the x402 protocol using USDC on Base.

Install

pip install pylonapi

Quick Start

import pylonapi

pylon = pylonapi.Pylon(private_key="0x...")

# Natural language — the gateway picks the right tool
result = pylon.do("take a screenshot of stripe.com")

# Explicit capability
result = pylon.screenshot("https://stripe.com", full_page=True)

# Check the result
print(result["result"])  # screenshot data, extracted text, etc.

How It Works

1. You call pylon.do(...) or a convenience method
2. The gateway returns 402 Payment Required with USDC cost
3. The SDK signs an x402 payment authorization (EIP-712)
4. The request is retried with the payment proof
5. You get your result

All payment happens automatically. You just need a funded wallet on Base.

Authentication

The SDK uses an Ethereum private key to sign x402 micropayments. Your wallet needs USDC on Base (mainnet).

# From a private key
pylon = pylonapi.Pylon(private_key="0xabc123...")

# Or use environment variable
import os
pylon = pylonapi.Pylon(private_key=os.environ["PYLON_PRIVATE_KEY"])

# Without payment (will raise PaymentRequired on 402)
pylon = pylonapi.Pylon()

Capabilities

Method	Capability	Cost
pylon.screenshot(url)	Screenshot	$0.01
pylon.web_scrape(url)	Web Scrape	$0.01
pylon.web_extract(url)	Web Extract	$0.005
pylon.pdf_parse(url)	PDF Parse	$0.02
pylon.ocr(url)	OCR	$0.03
pylon.email_validate(email)	Email Validate	$0.005
pylon.domain_intel(domain)	Domain Intel	$0.01
pylon.qr_code(data)	QR Code	$0.005
pylon.image_resize(url)	Image Resize	$0.01
pylon.md_to_pdf(markdown)	Markdown to PDF	$0.02
pylon.html_to_pdf(html=...)	HTML to PDF	$0.02
pylon.search(query)	Web Search	$0.003
pylon.translate(text, target)	Translate	$0.005
pylon.dns_lookup(domain)	DNS Lookup	$0.002
pylon.ip_geo(ip)	IP Geolocation	$0.002
pylon.url_shorten(url)	URL Shortener	$0.002
pylon.data_format(input, from_fmt, to_fmt)	Data Formatter	$0.002
pylon.doc_gen(data, template=...)	Document Gen	$0.02
pylon.email_send(to, subject, body)	Email Send	$0.01
pylon.file_upload(file_url)	File Storage	$0.005

Low-Level API

# Natural language
result = pylon.do("validate test@example.com")

# Explicit capability + params
result = pylon.do(
    capability="screenshot",
    params={"url": "https://example.com", "fullPage": True}
)

# With budget cap
result = pylon.do("screenshot stripe.com", budget="$0.02")

Multi-Step Chains

result = pylon.chain([
    {"capability": "web-extract", "params": {"url": "https://example.com"}},
    {"capability": "translate", "params": {"text": "{{step_0.content}}", "target": "es"}},
])

Async Support

import asyncio
import pylonapi

async def main():
    async with pylonapi.AsyncPylon(private_key="0x...") as pylon:
        # Run tasks concurrently
        results = await asyncio.gather(
            pylon.screenshot("https://stripe.com"),
            pylon.domain_intel("stripe.com"),
            pylon.dns_lookup("stripe.com"),
        )

asyncio.run(main())

Error Handling

import pylonapi

try:
    result = pylon.do("screenshot https://example.com")
except pylonapi.PaymentRequired as e:
    print("Need to configure payment:", e.body)
except pylonapi.TaskNotFound as e:
    print("No matching capability:", e)
except pylonapi.APIError as e:
    print(f"API error {e.status_code}: {e}")

Configuration

pylon = pylonapi.Pylon(
    private_key="0x...",            # Wallet key for x402 payments
    base_url="https://api.pylonapi.com",  # Gateway URL
    auto_pay=True,                  # Auto-handle 402 flow (default: True)
    timeout=60,                     # Request timeout in seconds
)

x402 Protocol

Pylon uses the x402 payment protocol. When you make a request:

• The gateway returns 402 with payment requirements (amount, asset, payee)
• The SDK signs a USDC TransferWithAuthorization (EIP-712) on Base
• The signed proof is sent as the X-PAYMENT header
• The x402 facilitator verifies and settles the payment

No API keys. No subscriptions. Just pay-per-request with USDC.

License

MIT