Ten data endpoints served from Cloudflare's edge. Use a free API key for the free tier, upgrade to a monthly subscription with Stripe, or pay-per-call with a USDC micropayment enforced onchain (Base, x402) — no account needed.
Create an account and get an ak_... API key. Keys are stored hashed and never returned again — keep them secret and rotate them from the key endpoints.
curl -X POST https://aries-api-hub.piratecove.workers.dev/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com"}'
{
"userId": "158eb48c-...",
"apiKey": "ak_8092f70611b1996d...",
"tier": "free",
"created": true
}
curl https://aries-api-hub.piratecove.workers.dev/v1/weather?lat=40.71&lon=-74.01 \ -H "Authorization: Bearer ak_..."
Free tier (30 req/min): Weather, IP Intelligence and Email Validation are free with any valid key. Other endpoints still require payment. Keys can be created (POST /v1/auth/keys), listed, or revoked (DELETE /v1/auth/keys/:id). Upgrade in /billing.
Each endpoint responds 402 Payment Required with machine-readable requirements. Pay once per call — any x402-compatible client or wallet can do this flow:
curl https://aries-api-hub.piratecove.workers.dev/v1/ip/8.8.8.8
{
"error": "payment_required",
"x402Version": 1,
"accepts": [{
"scheme": "exact",
"network": "base",
"maxAmountRequired": "3000",
"payTo": "0x...",
"asset": "0x...",
"extra": { "name": "USD Coin", "version": "2" }
}]
}
curl -H "X-PAYMENT: <base64-signed-payload>" \ -H "Idempotency-Key: <unique-per-payment>" \ https://aries-api-hub.piratecove.workers.dev/v1/ip/8.8.8.8
The 200 response carries a payment-response header with your payment id and settlement transaction. Reusing an Idempotency-Key replays the original receipt instead of charging twice. Amounts are USDC atomic units (6 decimals): 3000 = $0.003. On Base mainnet, extra.name is USD Coin (the USDC EIP-712 domain). On Base Sepolia, network is base-sepolia and extra.name is USDC.
Base URL: https://aries-api-hub.piratecove.workers.dev. Two call styles: keyed (free tier and subscriptions) and pay-per-call. With a key, add Authorization: Bearer ak_... and free-tier endpoints skip payment entirely; Pro/Enterprise subscribers skip payment on all endpoints (rate limits still apply). Anything else still needs X-PAYMENT + Idempotency-Key (see Paying). Without a key, every call is pay-per-call.
JSON body: {"email":"you@example.com"}. Creates the account and returns a brand-new API key (shown once). Registering the same email twice returns 409 email_taken — use POST /v1/auth/keys with your existing key to mint more. Disposable and reserved domains are rejected.
{
"userId": "158eb48c-...",
"apiKey": "ak_8092f70611b1996d...",
"tier": "free",
"created": true
}
Create an additional key for your account. Authenticate with Authorization: Bearer ak_...; optional body {"name":"..."}. The new key inherits your account plan.
List your keys (id + prefix, hashed full values never exposed). Authenticate with Authorization: Bearer ak_....
Revoke a key by its id. Authenticate with Authorization: Bearer ak_.... Revoked keys immediately stop authorizing requests.
HTML billing page. Send your key via the Authorization header to see your current plan; the Upgrade buttons prompt for your key and open Stripe Checkout for Pro and Enterprise.
JSON body: {"plan":"pro"} (or enterprise) with Authorization: Bearer ak_.... Returns {"checkoutUrl","sessionId"} — redirect the customer to Stripe Checkout. Subscription events are handled by the webhook and the plan upgrades immediately.
Stripe webhook receiver (HMAC-verified, replay-protected). Handles checkout.session.completed, customer.subscription.updated/deleted and invoice.payment_failed — the last of which downgrades offenders to free.
Reverse DNS and geo/ASN lookup for any public IPv4 or IPv6 address. Use /v1/ip/me to resolve the caller's own address and enrich with proxy/mobile/hosting flags.
{
"ip": "8.8.8.8",
"self": false,
"reverse_dns": "dns.google",
"city": "Mountain View",
"region": "California",
"country": "United States",
"country_code": "US",
"postal": "94043",
"lat": 37.42,
"lon": -122.08,
"asn": "AS15169",
"as_name": "GOOGLE",
"isp": "Google LLC",
"org": "Google LLC",
"mobile": false,
"proxy": false,
"hosting": true,
"cached": false
}
Registration (RDAP) data plus the live DNS record set (A, AAAA, CNAME, MX, TXT, NS, SOA, CAA) and an SPF/DMARC security summary.
{
"domain": "example.com",
"registrar": "RESERVED-Internet Assigned Numbers Authority",
"created": "1995-08-14T04:00:00Z",
"updated": "...",
"expires": "...",
"status": ["client delete prohibited"],
"nameservers": ["a.iana-servers.net", "b.iana-servers.net"],
"dns_records": { "A": ["93.184.216.34"], "MX": [], "TXT": [], "CAA": [] },
"security": {
"spf": { "found": true, "record": "v=spf1 -all" },
"dmarc": { "found": true, "policy": "reject", "record": "v=DMARC1; p=reject" }
},
"cached": false
}
JSON body only: {"email":"..."} or batch {"emails":["...", "..."]} (max 20). Checks syntax (RFC 5321 length limits enforced), MX records, disposable/reserved domains, plus SPF & DMARC. Invalid syntax returns HTTP 200 with valid:false.
{
"email": "user@example.com",
"valid": true,
"reason": "ok",
"mx_found": true,
"mx_hosts": ["aspmx.l.google.com"],
"disposable": false,
"reserved": false,
"dmarc": { "found": true, "policy": "reject" },
"spf": { "found": true, "policy": "enforced" }
}
{ "results": [ { "email": "...", "valid": true, "...": "..." } ] }
Required: lat and lon as numbers. Optional: days (1–7, default 3), units (metric|imperial), aqi=true to include live air quality.
{
"lat": 51.5,
"lon": -0.12,
"timezone": "Europe/London",
"units": "metric",
"current": { "temperature_2m": 15.3, "wind_speed_10m": 11.2, "weather_code": 3, "..." : "..." },
"forecast_daily": { "time": ["..."], "temperature_2m_max": [...], "temperature_2m_min": [...] },
"air_quality": { "us_aqi": 32, "pm2_5": 7.1, "...": "..." },
"cached": false
}
JSON body only (not multipart): { "files_base64": [ ... ] }. Accepts 2–20 base64-encoded PDFs (20MB max each). Returns the merged document as base64.
{
"file_base64": "JVBERi0xLjcK...",
"pages": 2
}
JSON body only: { "file_base64": "...", "text": "..." } (text 1–120 chars, 20MB max file). Stamps the given text diagonally across every page.
{
"file_base64": "JVBERi0xLjcK...",
"pages": 1
}
JSON body: { "file_base64": "..." }. Returns page count, per-page dimensions, byte size and embedded metadata. Does not rewrite the document.
{
"pages": 3,
"size_bytes": 48213,
"page_sizes": [{ "width": 612, "height": 792 }],
"title": "Monthly Report",
"author": null,
"created": "D:20240101120000Z"
}
JSON body: { "file_base64": "...", "degrees": 90 }. Rotates every page by a multiple of 90 (90 / 180 / 270 / 0). Returns the rotated document.
{
"file_base64": "JVBERi0xLjcK...",
"pages": 1,
"degrees": 90
}
JSON body: { "file_base64": "...", "from": 2, "to": 5 } (1-indexed, inclusive, max 500 pages). Extracts a page range into a new document.
{
"file_base64": "JVBERi0xLjcK...",
"pages": 4,
"range": [2, 5]
}
Query params: v (11-char video ID, required), lang (e.g. es, default en), timed=true to include timestamped segments. Returns the caption text (or a 422 if the video has no captions).
{
"videoId": "dQw4w9WgXcQ",
"lang": "en",
"transcript": "Never gonna give you up...",
"eventCount": 12,
"segments": [{ "text": "Never gonna give you up", "start_ms": 0, "duration_ms": 2600 }]
}
| Status | error | Meaning |
|---|---|---|
| 400 | invalid_body | Malformed or non-JSON request body |
| 400 | invalid_ip / invalid_domain / invalid_coords / invalid_video_id / invalid_input / too_many_emails / invalid_range | Parameter failed validation |
| 400 | reserved_ip | Private/reserved address ranges are not lookup-able |
| 400 | idempotency_key_required / malformed_payment | Missing Idempotency-Key, or X-PAYMENT is not base64 JSON |
| 400 | invalid_email / invalid_json | Auth endpoints need a valid, non-disposable email; bad JSON body |
| 400 | missing_signature / bad_signature | Stripe webhook signature missing or failed verification |
| 401 | api_key_required / invalid_api_key | API key missing or not recognized — register in Getting started |
| 402 | payment_required | No X-PAYMENT header — requirements are in accepts |
| 402 | payment_verification_failed / payment_settlement_failed | Facilitator rejected the payment — check details and retry with a fresh Idempotency-Key |
| 403 | api_key_disabled | This key was revoked — mint a new one via POST /v1/auth/keys |
| 409 | email_taken | Email is already registered — use your existing key to mint more via POST /v1/auth/keys |
| 413 | file_too_large | PDF input exceeds the 20MB limit |
| 422 | merge_failed / watermark_failed / parse_failed / transcript_unavailable | Input could not be parsed, or no captions available for the video |
| 429 | rate_limited | Rate limit hit (free: 30 req/min, pro: 300, enterprise: 1200) — slow down or upgrade |
| 502 | upstream_failed / lookup_failed / facilitator_unreachable | Upstream data source or payment facilitator unavailable |
| 503 | payments_unconfigured / stripe_unconfigured | Operator has not configured payment settlement or Stripe billing yet |
| Tier | Cost | Rate | What's included |
|---|---|---|---|
| Free | $0 | 30 req/min | API key, Weather + IP + Email Validation free |
| Pro | $5/mo | 300 req/min | All endpoints included, all features |
| Enterprise | $25/mo | 1200 req/min | All endpoints included + priority support |
| Endpoint | Pay-per-call | Notes |
|---|---|---|
| IP Intelligence | $0.003 | free on Free tier; USDC on Base otherwise |
| Domain Intel | $0.015 | USDC on Base per call, or included with Pro/Enterprise |
| Email Validation | $0.008 | free on Free tier; up to 20 addresses in batch |
| Weather | $0.003 | free on Free tier; USDC on Base otherwise |
| PDF Toolkit (merge / info / rotate / split / watermark) | $0.02 | USDC on Base per operation, or included with Pro/Enterprise |
| YouTube Transcribe | $0.001 | USDC on Base per call, or included with Pro/Enterprise |