@pylonapi/sdk

Official TypeScript SDK for the Pylon Agent Gateway — one endpoint, every tool an agent needs.

20+ capabilities · No API keys · Pay-per-request via x402 micropayments

Install

npm install @pylonapi/sdk

Quick Start

import { Pylon } from "@pylonapi/sdk";

const pylon = new Pylon({
  privateKey: process.env.PYLON_PRIVATE_KEY as `0x${string}`, // wallet with USDC on Base
});

// Natural language — the gateway figures out what to do
const result = await pylon.do("take a screenshot of stripe.com");

// Typed convenience methods
const screenshot = await pylon.screenshot("https://stripe.com", { fullPage: true });
const email = await pylon.validateEmail("user@example.com");
const search = await pylon.search("latest AI news");
const translation = await pylon.translate("hello world", "ja");

How It Works

Pylon is a pay-per-request API gateway. No API keys, no subscriptions — you pay per call in USDC on Base using the x402 protocol.

1. Your request hits POST /do
2. Server returns 402 with payment requirements
3. SDK signs a USDC payment (EIP-3009 transferWithAuthorization)
4. SDK retries the request with the payment proof
5. You get your result ✨

The SDK handles all of this automatically.

Configuration

const pylon = new Pylon({
  // Required for paid endpoints
  privateKey: "0x...",       // Wallet private key (USDC on Base)

  // Optional
  baseUrl: "https://api.pylonapi.com",  // Gateway URL (default)
  autoPayment: true,                     // Auto-handle x402 (default: true)
  maxCostUsd: 1.00,                      // Max cost per request (default: $1.00)
  timeoutMs: 30000,                      // Request timeout (default: 30s)
});

API Reference

Low-Level

pylon.do(task: string)

Execute a task using natural language. The gateway matches your description to the best capability.

const result = await pylon.do("scrape https://news.ycombinator.com as markdown");

pylon.do({ capability, params })

Execute a specific capability with explicit parameters.

const result = await pylon.do({
  capability: "screenshot",
  params: { url: "https://stripe.com", fullPage: true },
});

pylon.chain(steps)

Execute a multi-step workflow.

const result = await pylon.chain([
  { capability: "web-scrape", params: { url: "https://example.com" } },
  { capability: "translate", params: { to: "es" } },
]);

pylon.capabilities()

List all available capabilities with pricing and status.

const caps = await pylon.capabilities();
// [{ id: "screenshot", name: "Screenshot", cost: "$0.01", ... }, ...]

High-Level Methods

Every capability has a typed convenience method:

Method	Cost	Description
pylon.screenshot(url, opts?)	$0.01	Full-page screenshot
pylon.scrape(url, opts?)	$0.01	Web scrape to markdown/text/html
pylon.extract(url, opts?)	$0.005	Clean content extraction
pylon.parsePdf(url)	$0.02	Extract text from PDF
pylon.ocr(url, opts?)	$0.03	Image to text (OCR)
pylon.validateEmail(email)	$0.005	Email validation
pylon.domainIntel(domain)	$0.01	WHOIS, DNS, SSL, tech stack
pylon.qrCode(data, opts?)	$0.005	Generate QR code
pylon.resizeImage(url, opts?)	$0.01	Resize/convert images
pylon.mdToPdf(markdown)	$0.02	Markdown → PDF
pylon.htmlToPdf(html, opts?)	$0.02	HTML → PDF
pylon.search(query, opts?)	$0.003	Web search
pylon.translate(text, to, from?)	$0.005	Text translation
pylon.dnsLookup(domain, type?)	$0.002	DNS records
pylon.ipGeo(ip)	$0.002	IP geolocation
pylon.shortenUrl(url, slug?)	$0.002	URL shortener
pylon.formatData(params)	$0.002	JSON ↔ CSV ↔ XML ↔ YAML
pylon.storeFile(params)	$0.005	File upload (30-day hosting)
pylon.generateDoc(params)	$0.02	Document generation
pylon.sendEmail(params)	$0.01	Send email

Response Format

All methods return a PylonResponse:

interface PylonResponse<T = unknown> {
  success: boolean;
  capability?: string;   // Which capability was used
  data?: T;              // The result (JSON, Buffer for binary, or string)
  url?: string;          // URL if the result is hosted
  contentType?: string;  // MIME type
  raw?: Response;        // Original fetch Response
}

Error Handling

import { Pylon, PylonApiError } from "@pylonapi/sdk";

try {
  const result = await pylon.screenshot("https://example.com");
} catch (err) {
  if (err instanceof PylonApiError) {
    console.error(`API error ${err.status}: ${err.body}`);
  }
}

Payment Setup

You need a wallet with USDC on Base network.

1. Get a wallet private key (use a dedicated hot wallet, not your main wallet!)
2. Fund it with USDC on Base
3. Pass the private key to the SDK

const pylon = new Pylon({
  privateKey: process.env.PYLON_PRIVATE_KEY as `0x${string}`,
  maxCostUsd: 0.50, // Safety: max $0.50 per request
});

The maxCostUsd setting prevents accidental overspend. The SDK will throw an error if a request would exceed this amount.

Without Payment

You can use the SDK without a wallet for free endpoints like /capabilities:

const pylon = new Pylon(); // No wallet
const caps = await pylon.capabilities();

Paid endpoints will throw a PylonApiError with status 402.

ESM & CommonJS

The SDK ships dual builds:

// ESM
import { Pylon } from "@pylonapi/sdk";

// CommonJS
const { Pylon } = require("@pylonapi/sdk");

Links

• Pylon Gateway
• x402 Protocol
• GitHub
• API Docs

License

MIT