Calling APIs

The proxy

All paid calls go through https://proxy.apihub.io. Three call shapes:

• Onboarded service: /{slug}/{endpoint_path}
• External x402: POST /external with the target URL in the body
• Content gateway: /{slug}/fetch?url={target_url}

Onboarded service calls

The simplest path. The proxy looks up the service by slug, charges the configured per-endpoint price from your credits, and forwards the request to the upstream.

curl https://proxy.apihub.io/exchange-rates/latest/USD \
  -H "Authorization: Bearer ahk_..."

POST/PUT requests forward the body verbatim. Query strings on the path are passed through.

curl -X POST https://proxy.apihub.io/my-service/v1/translate \
  -H "Authorization: Bearer ahk_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "hello", "target": "es" }'

External x402 calls

For x402-protected APIs that aren't onboarded to APIHub. The proxy signs the x402 payment for you using its hot wallet, charges you (provider price + markup), and forwards the response.

curl -X POST https://proxy.apihub.io/external \
  -H "Authorization: Bearer ahk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://bitcoinsapi.com/api/v1/fees/landscape",
    "method": "GET"
  }'

Body fields: url (required), method (default POST), body (object or string), headers (object; Authorization and X-PAYMENT are stripped).

The response wraps the upstream response in metadata showing what was charged:

{
  "ok": true,
  "status": 200,
  "body": { /* upstream JSON */ },
  "credits_spent_microdollars": 5500,
  "credits_remaining_microdollars": 994500,
  "upstream_headers": { ... }
}

Content gateway calls

For paid web content (paywalled articles, gated docs, etc.). The proxy fetches the URL via headless browser and returns clean structured text.

curl "https://proxy.apihub.io/my-blog/fetch?url=https://blog.example.com/premium/article-1" \
  -H "Authorization: Bearer ahk_..."

Returns title, body text, headings, word count, and source URL. The provider sets URL pricing rules; if no rule matches the path, the call returns 404 NO_CONTENT_RULE with no charge.

Free tier

If a service has a free tier configured, you get N free calls per month per endpoint per agent. The proxy uses free quota first; once exhausted it falls through to credits or x402.

You can spot a free call by the response header:

x-apihub-payment-protocol: free_tier
x-apihub-charged: 0
x-apihub-free-tier-remaining: 47

Response headers (every paid call)

The proxy attaches these headers to every response so your code can react to billing state without parsing JSON:

• x-apihub-payment-protocol: credit | free_tier | x402 | provider_test
• x-apihub-charged: amount in microdollars, or false for non-charged
• x-apihub-credit-balance-remaining: post-call balance (when payment_protocol is credit)
• x-apihub-free-tier-remaining: free quota left (when payment_protocol is free_tier)
• x-apihub-latency-ms: upstream call duration
• x-apihub-receipt-hash: SHA-256 of the audit row (for dispute reference)
• x-apihub-request-id: opaque request identifier

402 challenge

If you have no free quota, no credits, and didn't send PAYMENT-SIGNATURE, the proxy returns 402 with the per-call x402 requirements. Your client can sign and retry, or top up credits and retry.

Rate limits

Per-account, per minute, profile-shared (multiple keys under one account share the bucket):

• Free tier (no credit balance): 100 requests/minute
• Pro (any credit balance): 1,000 requests/minute

Rate-limited requests return HTTP 429 with a Retry-After header (seconds until the next minute). Rate limits are enforced separately on credit purchase (20/min) and registration (5/hour per IP).