agentsvc.io

Documentation

Pay per call. Nothing else to set up.

Every service is a JSON endpoint behind HTTP 402. If you already use an x402 client, you are done: point it at any endpoint below. Agents can read this whole page as Markdown at /llms-full.txt.

Free trial, no wallet

Every service has a trial endpoint with the identical output. Limits: 3 calls per service per day, heavy services (screenshot, PDF, OCR, scrape, resize) 1, 20 per IP in total. Send an empty body to use the example input.

curl -X POST https://agentsvc.io/api/v1/try/web-scrape \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

# GET works too and uses the example input:
curl https://agentsvc.io/api/v1/try/weather

The response carries trial.remaining_today and paid_endpoint. Hitting the limit returns 429 with resets_at.

Quickstart with a wallet

You need an EVM private key whose address holds USDC on Base mainnet (chain 8453). No ETH is needed; the facilitator pays gas. Then:

npm i @x402/fetch @x402/evm viem
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);
const res = await payFetch("https://agentsvc.io/api/v1/proxy/web-scrape", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ url: "https://example.com" }) });
console.log(await res.json());

Swap the URL for any endpoint from the reference. The client handles 402, signing and retry. The 200 response contains data and payment.transaction.

Payment protocol (x402 v1 and v2)

One request without payment returns 402. We answer both protocol versions at once, so any x402 client works:

  • x402 v2: header PAYMENT-REQUIRED = base64 JSON with accepts[0] = {scheme: exact, network: eip155:8453, amount, asset, payTo, maxTimeoutSeconds, extra}. Pay by sending PAYMENT-SIGNATURE.
  • x402 v1: JSON body with accepts[0] = {scheme: exact, network: base, maxAmountRequired, resource, asset, payTo, extra}. Pay by sending X-PAYMENT.
POST https://agentsvc.io/api/v1/proxy/ip-lookup   {"ip":"8.8.8.8"}

HTTP/2 402
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2Ui…   (x402 v2)
{
  "x402Version": 1,                                   (x402 v1)
  "error": "payment_required",
  "accepts": [{ "scheme": "exact", "network": "base", "maxAmountRequired": "2000",
                "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "payTo": "0x622efA6Ceb83a5b6EdBC931332f4db68B7f74F27",
                "maxTimeoutSeconds": 300, "extra": { "name": "USD Coin", "version": "2" } }],
  "hint": "This call costs $0.002 USDC …",
  "try_free": "https://agentsvc.io/api/v1/try/ip-lookup"
}

Manual signing: create an EIP-3009 TransferWithAuthorization (EIP-712 domain name USD Coin, version 2, chainId 8453, verifyingContract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) with value = amount, to = payTo, a random 32-byte nonce and validBefore at least 60 seconds ahead. Base64-encode the PaymentPayload and retry with the header. The official clients do exactly this.

Order of operations on our side: verify with the facilitator (https://facilitator.payai.network) → run the service → settle on-chain → respond. A failed service never settles, so you are never charged for errors. The response headers PAYMENT-RESPONSE and X-PAYMENT-RESPONSE contain the settlement receipt.

Receiving wallet: 0x622efA6Ceb83a5b6EdBC931332f4db68B7f74F27. Prices in atomic units: $0.002 = 2000, $0.005 = 5000, $0.008 = 8000.

Responses and errors

200  {"success":true,"data":{…},"payment":{"settled":true,"amount_usdc":0.002,"transaction":"0x…","network":"eip155:8453","payer":"0x…"}}
400  {"success":false,"error":"invalid_input","message":"…","charged":false,"example_input":{…},"input_schema":{…}}
402  {"x402Version":1,"error":"<code>","accepts":[…],"hint":"what to fix","payer":"0x…"}
404  {"success":false,"error":"service_not_found","did_you_mean":["web-scrape"]}
429  {"success":false,"error":"trial_limit_reached","resets_at":"…","paid_endpoint":"…"}   (trial only)
500  {"success":false,"error":"internal_error","charged":false}
503  {"success":false,"error":"facilitator_unavailable","charged":false}   retry after a few seconds

402 error codes you may see after paying: invalid_exact_evm_insufficient_balance (fund the wallet), wrong_network (only Base mainnet), wrong_recipient, amount_too_low, authorization_expired, payment_already_used (fresh nonce per call), settlement_failed. Every 402 includes a hint written for the agent that reads it.

Discovery for agents

The catalog JSON includes for every service: input_schema, output_schema with example, example_input, price_usdc, try_url, curl_example and live status. Every 402 also carries a Bazaar discovery extension, so facilitator catalogs index the endpoints automatically.

Service reference (27)

timezone$0.002dataResolve a city name or coordinates to its IANA timezone and return the current local time, UTC offset, DST flag and weekday.

Resolve a city name or coordinates to its IANA timezone and return the current local time, UTC offset, DST flag and weekday. Use for scheduling across regions, 'what time is it in X', or normalizing timestamps. Params: location (required, e.g. 'Tokyo' or '35.68,139.69').

POST https://agentsvc.io/api/v1/proxy/timezone
{
  "location": "Tokyo"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

weather$0.002dataReal-time weather + 3-day forecast.

Real-time weather + 3-day forecast. Returns current (temp_c, feels_like_c, humidity_pct, wind_kph, weather_code) and forecast_3d array. Pass location as city name ('Berlin') or GPS string ('52.52,13.41'). WMO codes: 0=clear, 1-3=cloudy, 45-48=fog, 51-67=rain, 71-77=snow, 95-99=thunderstorm.

POST https://agentsvc.io/api/v1/proxy/weather
{
  "location": "Berlin"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

crypto-prices$0.002financeReal-time crypto prices, market caps, and 24h % changes via CoinGecko.

Real-time crypto prices, market caps, and 24h % changes via CoinGecko. Pass coins as CoinGecko IDs (['bitcoin','ethereum','solana']) or tickers. Max 25 coins per call. Returns usd, usd_24h_change, usd_market_cap per coin. Add currencies param for multi-currency output (['usd','eur','gbp']).

POST https://agentsvc.io/api/v1/proxy/crypto-prices
{
  "coins": [
    "bitcoin",
    "ethereum"
  ],
  "currencies": [
    "usd"
  ]
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

evm-balance$0.002financeRead the ETH and USDC balance of any address on Base mainnet (chain 8453) straight from the chain, plus transaction count and how many x402 calls the USDC covers.

Read the ETH and USDC balance of any address on Base mainnet (chain 8453) straight from the chain, plus transaction count and how many x402 calls the USDC covers. Use it to check your own agent wallet before a paid workflow, to verify a counterparty was paid, or to monitor treasury addresses. Params: address (required, 0x...).

POST https://agentsvc.io/api/v1/proxy/evm-balance
{
  "address": "0x622efA6Ceb83a5b6EdBC931332f4db68B7f74F27"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

exchange-rates$0.002financeLive forex rates from European Central Bank (ECB), updated hourly.

Live forex rates from European Central Bank (ECB), updated hourly. Returns rates object mapping currency codes to rates relative to base. Pass symbols array to filter (e.g. ['USD','CHF','GBP']). Empty symbols = all 30+ currencies. Use for currency conversion in invoices, pricing, or financial calculations.

POST https://agentsvc.io/api/v1/proxy/exchange-rates
{
  "base": "EUR",
  "symbols": [
    "USD",
    "CHF",
    "GBP"
  ]
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

stock-prices$0.002financeReal-time stock data via Yahoo Finance.

Real-time stock data via Yahoo Finance. Returns price, change, change_pct, previous_close, market_cap, pe_ratio, week_52_high, week_52_low, volume, and market_state. Max 10 symbols per call. Non-US exchange suffixes: 'SAP.DE' (Xetra), 'VOD.L' (London LSE), 'AIR.PA' (Paris Euronext), 'ASML.AS' (Amsterdam).

POST https://agentsvc.io/api/v1/proxy/stock-prices
{
  "symbols": [
    "AAPL",
    "MSFT"
  ]
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

ocr$0.008textExtract text from images using Tesseract OCR.

Extract text from images using Tesseract OCR. Send image as image_base64 (PNG/JPEG/WebP/TIFF/BMP, max 10 MB decoded). Returns text and confidence (0-100, where 80+ is reliable). Set language to Tesseract code: 'eng' (default), 'deu' (German), 'fra' (French), 'chi_sim' (Chinese Simplified), 'jpn' (Japanese), 'ara' (Arabic). Use for invoices, receipts, scanned documents, or screenshots with text.

POST https://agentsvc.io/api/v1/proxy/ocr
{
  "image_base64": "<base64 of a PNG/JPG>",
  "language": "eng"
}

Free trial: 1/day · run it ↗ · full schema and code · amount 8000

pdf-extract$0.004textExtract all text from a PDF.

Extract all text from a PDF. Send as pdf_base64 (base64-encoded PDF, max ~10 MB decoded). Returns text (full concatenated text), pages array (per-page text + char_count), page_count, and metadata (title, author, creator). Encode with: Buffer.from(pdfBytes).toString('base64'). Ideal for RAG pipelines, document QA, or LLM ingestion.

POST https://agentsvc.io/api/v1/proxy/pdf-extract
{
  "pdf_base64": "<base64 of a PDF>",
  "max_pages": 10
}

Free trial: 1/day · run it ↗ · full schema and code · amount 4000

translate$0.002textTranslate text between 100+ languages.

Translate text between 100+ languages. Max 500 characters per call. Returns translated_text and confidence (0-1). Set target_lang to IETF code: 'de' (German), 'fr' (French), 'es' (Spanish), 'ja' (Japanese), 'zh-CN' (Chinese Simplified), 'ar' (Arabic), 'pt' (Portuguese), 'it' (Italian), 'nl' (Dutch). source_lang defaults to auto-detect.

POST https://agentsvc.io/api/v1/proxy/translate
{
  "text": "Hello, how are you?",
  "target_lang": "de"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

barcode$0.002utilityGenerate a barcode as PNG (base64): code128 (default), ean13, ean8, upca, upce, code39, itf14, gs1_128, isbn, datamatrix, pdf417, aztec or qr.

Generate a barcode as PNG (base64): code128 (default), ean13, ean8, upca, upce, code39, itf14, gs1_128, isbn, datamatrix, pdf417, aztec or qr. Validates check digits for EAN/UPC. Use for labels, shipping, inventory, tickets or invoices. Params: text (required), type, scale (1-8, default 3), include_text boolean (human-readable text under the bars).

POST https://agentsvc.io/api/v1/proxy/barcode
{
  "text": "4006381333931",
  "type": "ean13"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

dns-lookup$0.002utilityResolve DNS records for any domain.

Resolve DNS records for any domain. Supports A, AAAA, MX, TXT, CNAME, NS. Returns records object with array per type. Default: A records only. Use to verify mail server setup (MX), check domain ownership (TXT), or debug DNS propagation.

POST https://agentsvc.io/api/v1/proxy/dns-lookup
{
  "domain": "github.com",
  "types": [
    "A",
    "MX"
  ]
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

email-validate$0.002utilityValidate an email address: RFC 5322 format check, domain MX record lookup, disposable provider detection, and role address detection (e.g.

Validate an email address: RFC 5322 format check, domain MX record lookup, disposable provider detection, and role address detection (e.g. info@, admin@). Returns is_valid boolean and granular checks object. Use before storing or sending to email addresses to prevent bounces.

POST https://agentsvc.io/api/v1/proxy/email-validate
{
  "email": "support@github.com"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

geocode$0.002utilityForward geocoding: address string → lat/lon.

Forward geocoding: address string → lat/lon. Reverse geocoding: lat/lon → human-readable address. Powered by OpenStreetMap Nominatim. Returns results array with display_name, lat, lon, type, and structured address object. Provide address (string) for forward, or lat + lon (numbers) for reverse.

POST https://agentsvc.io/api/v1/proxy/geocode
{
  "address": "Brandenburger Tor, Berlin"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

ip-lookup$0.002utilityResolve any IPv4 or IPv6 address to location and network data.

Resolve any IPv4 or IPv6 address to location and network data. Returns country, country_code, city, region, postal, lat/lon, timezone, ISP, org, and ASN. Use for fraud detection, geolocation enrichment, or access log analysis.

POST https://agentsvc.io/api/v1/proxy/ip-lookup
{
  "ip": "8.8.8.8"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

phone-validate$0.002utilityParse and validate any phone number worldwide using libphonenumber.

Parse and validate any phone number worldwide using libphonenumber. Returns is_valid, e164 (canonical international format e.g. '+4917612345678'), national_format, country_code (ISO alpha-2), and line_type (MOBILE/FIXED_LINE/VOIP/TOLL_FREE). Provide country_code hint (e.g. 'DE') for local numbers without country prefix.

POST https://agentsvc.io/api/v1/proxy/phone-validate
{
  "phone": "+41 44 668 18 00"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

qr-code$0.002utilityGenerate a QR code for any text or URL.

Generate a QR code for any text or URL. Returns image_base64 (base64 PNG — decode to get raw bytes). Params: text (required), size in px (64-1024, default 256), error_correction (L/M/Q/H, default M). H = highest redundancy, survives up to 30% damage.

POST https://agentsvc.io/api/v1/proxy/qr-code
{
  "text": "https://agentsvc.io",
  "size": 256
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

ssl-check$0.002utilityInspect SSL/TLS certificate for any domain.

Inspect SSL/TLS certificate for any domain. Returns valid boolean, days_remaining, issuer, valid_from, valid_to, subject_alt_names (SANs), fingerprint_sha256, and protocol version. Default port 443. Use for certificate expiry monitoring, security audits, or HTTPS verification.

POST https://agentsvc.io/api/v1/proxy/ssl-check
{
  "domain": "github.com"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

url-status$0.002utilityCheck whether a URL is reachable and what it returns: final status code, full redirect chain, response time, content-type, server header and content length.

Check whether a URL is reachable and what it returns: final status code, full redirect chain, response time, content-type, server header and content length. Use for link validation, uptime checks, canonical URL resolution or before spending money on a scrape/screenshot. Params: url (required), method (GET default, or HEAD).

POST https://agentsvc.io/api/v1/proxy/url-status
{
  "url": "https://example.com"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

whois$0.002utilityDomain registration lookup via RDAP (modern WHOIS).

Domain registration lookup via RDAP (modern WHOIS). Returns registrar, registrar_url, created_at, updated_at, expires_at, days_until_expiry, name_servers array, status array, and registrant_country. Clean JSON — no raw WHOIS text to parse. Covers all major TLDs.

POST https://agentsvc.io/api/v1/proxy/whois
{
  "domain": "github.com"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

html-to-pdf$0.008visualRender a URL or raw HTML string to PDF.

Render a URL or raw HTML string to PDF. Returns pdf_base64 (base64 PDF — decode to get raw bytes) and page_count. Provide url OR html — never both. Supports format (A4/Letter/Legal), landscape boolean, and margin settings (top/bottom/left/right in CSS units). Use for invoices, reports, or printable document generation.

POST https://agentsvc.io/api/v1/proxy/html-to-pdf
{
  "html": "<h1>Invoice #123</h1><p>Total: $42.00</p>"
}

Free trial: 1/day · run it ↗ · full schema and code · amount 8000

image-resize$0.003visualResize, crop-fit and convert images (PNG, JPEG, WebP, AVIF, GIF, TIFF, SVG input) to webp, png, jpeg or avif.

Resize, crop-fit and convert images (PNG, JPEG, WebP, AVIF, GIF, TIFF, SVG input) to webp, png, jpeg or avif. Auto-rotates by EXIF. Use to shrink screenshots before sending them to a vision model, create thumbnails, or convert formats. Params: image_base64 or image_url (one required), width, height (max 4096), fit (inside default | cover | contain | fill), format (webp default), quality (1-100, default 80).

POST https://agentsvc.io/api/v1/proxy/image-resize
{
  "image_url": "https://agentsvc.io/sample.png",
  "width": 130,
  "format": "webp"
}

Free trial: 1/day · run it ↗ · full schema and code · amount 3000

screenshot$0.005visualCapture any URL as a PNG screenshot.

Capture any URL as a PNG screenshot. Returns image_base64 (base64 PNG — decode to get raw bytes). Full JS rendering via Playwright, works on SPAs and dynamic content. Params: url (required), width px (default 1280), height px (default 800), full_page boolean, wait_ms.

POST https://agentsvc.io/api/v1/proxy/screenshot
{
  "url": "https://example.com",
  "width": 1280,
  "height": 800
}

Free trial: 1/day · run it ↗ · full schema and code · amount 5000

news-search$0.003webSearch recent news articles by keyword.

Search recent news articles by keyword. Returns articles with title, url, source, published_at, and snippet. Sources: HackerNews Algolia (tech) + BBC RSS (general/world). Optional category filter: general/tech/business/science/health/politics. Limit max 30. Use for current events, topic monitoring, or market sentiment.

POST https://agentsvc.io/api/v1/proxy/news-search
{
  "query": "AI agents",
  "limit": 5
}

Free trial: 3/day · run it ↗ · full schema and code · amount 3000

rss-fetch$0.002webFetch an RSS 2.0, RSS 1.0 or Atom feed and return normalized JSON items (title, link, published_at ISO 8601, summary without HTML, author, guid).

Fetch an RSS 2.0, RSS 1.0 or Atom feed and return normalized JSON items (title, link, published_at ISO 8601, summary without HTML, author, guid). Use for monitoring blogs, news sites, GitHub releases, podcasts or any feed URL without writing an XML parser. Params: url (required), limit (default 20, max 100).

POST https://agentsvc.io/api/v1/proxy/rss-fetch
{
  "url": "https://hnrss.org/frontpage",
  "limit": 10
}

Free trial: 3/day · run it ↗ · full schema and code · amount 2000

web-scrape$0.004webFetch any public URL and return the page as clean Markdown for LLM consumption (title, meta description, main content with headings/lists/links preserved).

Fetch any public URL and return the page as clean Markdown for LLM consumption (title, meta description, main content with headings/lists/links preserved). Pass render:true to execute JavaScript in a real browser for SPAs (slower, returns plain text). Use this instead of raw fetch when a site blocks bots or when you want token-efficient content. Params: url (required), max_chars (default 8000, max 60000), include_links boolean, render boolean.

POST https://agentsvc.io/api/v1/proxy/web-scrape
{
  "url": "https://example.com",
  "max_chars": 8000
}

Free trial: 1/day · run it ↗ · full schema and code · amount 4000

web-search$0.003webSearch for factual information via DuckDuckGo + Wikipedia.

Search for factual information via DuckDuckGo + Wikipedia. Returns heading, abstract (plain-language summary), abstract_url, and results (list of relevant links). Best for: people, places, concepts, history, science. NOT for breaking news — use news-search instead.

POST https://agentsvc.io/api/v1/proxy/web-search
{
  "query": "x402 payment protocol"
}

Free trial: 3/day · run it ↗ · full schema and code · amount 3000

webpage-reader$0.006webFetch and extract clean readable text from any URL.

Fetch and extract clean readable text from any URL. Full JS rendering via Playwright — works on SPAs and dynamic sites. Returns title, text (cleaned content, default max 8000 chars), description, word_count, and optional links array. Ideal for web research, content summarization, or feeding page content to an LLM.

POST https://agentsvc.io/api/v1/proxy/webpage-reader
{
  "url": "https://example.com",
  "max_chars": 4000
}

Free trial: 3/day · run it ↗ · full schema and code · amount 6000