ARIES / API HUB

API Documentation

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.

Getting started — free tier

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.

1 — Register (no charge)
curl -X POST https://aries-api-hub.piratecove.workers.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
2 — Response (key shown once)
{
  "userId": "158eb48c-...",
  "apiKey": "ak_8092f70611b1996d...",
  "tier": "free",
  "created": true
}
3 — Call a free endpoint
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.

Paying for calls (no account)

Each endpoint responds 402 Payment Required with machine-readable requirements. Pay once per call — any x402-compatible client or wallet can do this flow:

1 — Request (no payment yet)
curl https://aries-api-hub.piratecove.workers.dev/v1/ip/8.8.8.8
2 — 402 response with requirements
{
  "error": "payment_required",
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "3000",
    "payTo": "0x...",
    "asset": "0x...",
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}
3 — Resend with payment + idempotency key
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.

Endpoints

IP Intelligence
GET /v1/ip/:ip · /v1/ip/me
IP → reverse DNS, city, ASN, ISP + proxy & hosting flags. Self-lookup via /v1/ip/me.
free with key · $0.003 pay-per-call
Domain Intelligence
GET /v1/domain/:domain
RDAP registration + live DNS set (A/AAAA/CNAME/MX/TXT/NS/SOA/CAA) + SPF & DMARC.
$0.015 / call · included with Pro+
Email Validate
POST /v1/email/validate
Single or batch (20): syntax, MX, disposable, SPF & DMARC checks.
free with key · $0.008 pay-per-call
Weather / Real-Time
GET /v1/weather?lat=&lon=
Current + up to 7-day forecast, metric/imperial, optional air quality.
free with key · $0.003 pay-per-call
PDF Toolkit
POST /v1/pdf/merge | /info | /rotate | /split
Merge, inspect, rotate and split PDFs server-side. Base64 JSON in/out.
$0.02 / call · included with Pro+
PDF Watermark
POST /v1/pdf/watermark
Stamp diagonal text watermark across every page.
$0.02 / call · included with Pro+
YouTube Transcribe
GET /v1/youtube/transcribe?v=
Fetch captions with language select & optional timestamped segments.
$0.001 / call · included with Pro+

Call Reference

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.

POST/v1/auth/registerfree

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.

Response 200
{
  "userId": "158eb48c-...",
  "apiKey": "ak_8092f70611b1996d...",
  "tier": "free",
  "created": true
}
POST/v1/auth/keysfree

Create an additional key for your account. Authenticate with Authorization: Bearer ak_...; optional body {"name":"..."}. The new key inherits your account plan.

GET/v1/auth/keysfree

List your keys (id + prefix, hashed full values never exposed). Authenticate with Authorization: Bearer ak_....

DELETE/v1/auth/keys/:idfree

Revoke a key by its id. Authenticate with Authorization: Bearer ak_.... Revoked keys immediately stop authorizing requests.

GET/billingfree

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.

POST/v1/stripe/checkout—

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.

POST/v1/stripe/webhook—

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.

GET/v1/ip/{ip} | /v1/ip/mefree w/ key · $0.003

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.

Response 200
{
  "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
}
GET/v1/domain/{domain}$0.015 · free with Pro+

Registration (RDAP) data plus the live DNS record set (A, AAAA, CNAME, MX, TXT, NS, SOA, CAA) and an SPF/DMARC security summary.

Response 200
{
  "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
}
POST/v1/email/validatefree w/ key · $0.008

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.

Response 200 (single)
{
  "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" }
}
Response 200 (batch)
{ "results": [ { "email": "...", "valid": true, "...": "..." } ] }
GET/v1/weatherfree w/ key · $0.003

Required: lat and lon as numbers. Optional: days (1–7, default 3), units (metric|imperial), aqi=true to include live air quality.

Response 200
{
  "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
}
POST/v1/pdf/merge$0.02 · free with Pro+

JSON body only (not multipart): { "files_base64": [ ... ] }. Accepts 2–20 base64-encoded PDFs (20MB max each). Returns the merged document as base64.

Response 200
{
  "file_base64": "JVBERi0xLjcK...",
  "pages": 2
}
POST/v1/pdf/watermark$0.02 · free with Pro+

JSON body only: { "file_base64": "...", "text": "..." } (text 1–120 chars, 20MB max file). Stamps the given text diagonally across every page.

Response 200
{
  "file_base64": "JVBERi0xLjcK...",
  "pages": 1
}
POST/v1/pdf/info$0.02 · free with Pro+

JSON body: { "file_base64": "..." }. Returns page count, per-page dimensions, byte size and embedded metadata. Does not rewrite the document.

Response 200
{
  "pages": 3,
  "size_bytes": 48213,
  "page_sizes": [{ "width": 612, "height": 792 }],
  "title": "Monthly Report",
  "author": null,
  "created": "D:20240101120000Z"
}
POST/v1/pdf/rotate$0.02 · free with Pro+

JSON body: { "file_base64": "...", "degrees": 90 }. Rotates every page by a multiple of 90 (90 / 180 / 270 / 0). Returns the rotated document.

Response 200
{
  "file_base64": "JVBERi0xLjcK...",
  "pages": 1,
  "degrees": 90
}
POST/v1/pdf/split$0.02 · free with Pro+

JSON body: { "file_base64": "...", "from": 2, "to": 5 } (1-indexed, inclusive, max 500 pages). Extracts a page range into a new document.

Response 200
{
  "file_base64": "JVBERi0xLjcK...",
  "pages": 4,
  "range": [2, 5]
}
GET/v1/youtube/transcribe?v={id}$0.001 · free with Pro+

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).

Response 200 (timed)
{
  "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 }]
}

Error Codes

StatuserrorMeaning
400invalid_bodyMalformed or non-JSON request body
400invalid_ip / invalid_domain / invalid_coords / invalid_video_id / invalid_input / too_many_emails / invalid_rangeParameter failed validation
400reserved_ipPrivate/reserved address ranges are not lookup-able
400idempotency_key_required / malformed_paymentMissing Idempotency-Key, or X-PAYMENT is not base64 JSON
400invalid_email / invalid_jsonAuth endpoints need a valid, non-disposable email; bad JSON body
400missing_signature / bad_signatureStripe webhook signature missing or failed verification
401api_key_required / invalid_api_keyAPI key missing or not recognized — register in Getting started
402payment_requiredNo X-PAYMENT header — requirements are in accepts
402payment_verification_failed / payment_settlement_failedFacilitator rejected the payment — check details and retry with a fresh Idempotency-Key
403api_key_disabledThis key was revoked — mint a new one via POST /v1/auth/keys
409email_takenEmail is already registered — use your existing key to mint more via POST /v1/auth/keys
413file_too_largePDF input exceeds the 20MB limit
422merge_failed / watermark_failed / parse_failed / transcript_unavailableInput could not be parsed, or no captions available for the video
429rate_limitedRate limit hit (free: 30 req/min, pro: 300, enterprise: 1200) — slow down or upgrade
502upstream_failed / lookup_failed / facilitator_unreachableUpstream data source or payment facilitator unavailable
503payments_unconfigured / stripe_unconfiguredOperator has not configured payment settlement or Stripe billing yet

Pricing

TierCostRateWhat's included
Free$030 req/minAPI key, Weather + IP + Email Validation free
Pro$5/mo300 req/minAll endpoints included, all features
Enterprise$25/mo1200 req/minAll endpoints included + priority support
EndpointPay-per-callNotes
IP Intelligence$0.003free on Free tier; USDC on Base otherwise
Domain Intel$0.015USDC on Base per call, or included with Pro/Enterprise
Email Validation$0.008free on Free tier; up to 20 addresses in batch
Weather$0.003free on Free tier; USDC on Base otherwise
PDF Toolkit (merge / info / rotate / split / watermark)$0.02USDC on Base per operation, or included with Pro/Enterprise
YouTube Transcribe$0.001USDC on Base per call, or included with Pro/Enterprise