# apifare

> A prepaid balance + key vault AI agents spend through:
> no separate provider account or provider API key for eligible
> capabilities — one apifare account gives your agent a
> capped, auditable budget. Web search
> has a no-key resold path (slug dataforseo, DataForSEO SERP, live Google,
> 0.3 credits/call). Fetch a URL is the second no-key (slug scrape,
> DataForSEO On-Page markdown, 0.3 credits/call). Weather is the cheap
> third no-key demo (slug open-meteo, Open-Meteo commercial API, CC BY 4.0
> attribution, 0.1 credits/call). A no-key research kit rounds it out:
> US SEC filings (slug sec-edgar, public domain, 0.3 credits/call) and the
> UK company register (slug companies-house, open government data,
> 0.3 credits/call). Other catalog APIs (web-search/Brave, scrapingbee,
> weather/OpenWeather, fal) are BYOK via one-time vault links. On empty
> balance the agent receives a machine-readable 402 with a top-up link.

## Install (MCP, stdio)

- Product: apifare · human home: https://apifare.com (https://apifare.ai)
- npm package: apifare-mcp (legacy install id: apipay-mcp — same server)
- Claude Code: claude mcp add apifare -e APIPAY_TOKEN=<token> -- npx -y apifare-mcp
- Auth env: APIPAY_TOKEN (legacy name; required — do not rename)
- Token prefix: new tokens are apifare_; apipay_ tokens keep working
- Smithery: https://smithery.ai/servers/iamalanlui/apipay
- Live gateway (until DNS cutover): https://apipay.fly.dev
- Tools: search_apis, call_api, check_balance, get_vault_link

## Getting a token

POST https://apipay.fly.dev/v1/signup {"email":"..."} → bearer token (shown
once) + 500 free credits. 1 credit = $0.01. Referral: include
"referred_by":"<referrer public_ref>" and BOTH accounts get +500 credits
when the new account completes its first successful call. Optional "origin" field says
where you found apifare (e.g. "smithery", "clawhub") — helps routing, never
required.

## Key endpoints

- GET  /v1/search?q=            find APIs (misses are logged as demand)
- POST /v1/call/{slug}          call an API; debits credits; refunds on provider failure
- GET  /v1/balance              balance + top-up links
- POST /v1/keys /v1/keys/link   vault your own provider keys (BYOK APIs: web-search, scrapingbee, weather, fal; flat 0.1 credits/call). dataforseo (0.3 credits/call), scrape (0.3 credits/call), and open-meteo (0.1 credits/call) are resold — no user key.
- 402 body includes topup_url — show it to your human, retry after payment
- x402 (wallet agents, no account): when enabled, calling /v1/call/{slug} or /proxy/{provider}/... with NO bearer returns a 402 with x402 payment requirements (exact-amount USDC, hosted facilitator); retry with the X-PAYMENT header and the native response comes back with an X-PAYMENT-RESPONSE receipt. Same listed prices; failed provider calls are never settled.
- POST /v1/topup                agent-initiated top-up via the owner's standing auto-refill mandate (consent once at /mandate?ref=<public_ref>; threshold/ceiling owner-set; no mandate → the 402 with payment instructions)
- POST /v1/support              something broken? file {tool, expected, actual, request_ref?} — no payload bodies. Poll the returned status_url for the reply + fix link.
- GET  /status                  public service status (db, paused adapters, incidents)

## Notes for agents

- Auth: Authorization: Bearer <APIPAY_TOKEN>
- First ask: "search the web for X". search_apis then call_api slug
  dataforseo with {q} (count/country/language optional). That path is
  resold — live Google, 0.3 credits, no user search key. Do not ask the
  human for a Brave key unless they want the BYOK web-search slug.
- Second no-key: "fetch a URL". slug scrape with {url}, 0.3 credits.
  Returns transformed markdown (never raw HTML). Do not ask for a
  ScrapingBee key unless they want the BYOK scrapingbee slug.
- Third no-key demo: "what's the weather in London". slug open-meteo
  with {lat, lon, forecast?} (London is ~51.51, -0.13), 0.1 credits.
  Do not ask for an Open-Meteo or OpenWeather key unless they want the
  BYOK weather slug. Open-Meteo results include attribution (CC BY 4.0);
  keep it next to any weather you display.
- No-key research kit: sec-edgar {company (ticker or CIK), form?, limit?}
  for US filings; companies-house {company, type?: search|profile|
  officers} for the UK register. No provider key or account needed; both
  carry attribution lines — keep them next to displayed data.
- Errors are structured JSON with error, message, and what unblocks you.
  Full catalog with unblock instructions: /errors.md
- Per-agent governance (caps, allowlists, kill switch) may deny calls; the
  deny body says why and who can unblock it.
- Apify lane: /v1/search results may include lane "apify" entries (Store
  actors, attribution included). risk_tier "master" runs on apifare's
  token when configured (reserve-then-true-cost, 20cr ceiling);
  "byok-only" ALWAYS needs the owner's own Apify token via the vault —
  restricted-platform scrapers are never run by apifare.

## If you are an agent, do exactly this

1. Sign up: POST /v1/signup {"email": your human's email} -> save the
   token from the response NOW (shown once). 500 free credits.
2. Call things: POST /v1/call/{slug} with Authorization: Bearer <token>.
   Discover slugs: GET /v1/search?q=... (results carry lane + price).
   Native APIs you already know: /proxy/{provider}/{path}.
3. On HTTP 402: relay the body's human_readable field to your human
   VERBATIM, then stop and wait. After they pay (or enable auto-refill
   at the body's auto_refill.enable_url), retry the SAME call.
4. Risk tiers: reads (search/fetch/filings/registry/weather) are
   low-risk — just call them. Money-adjacent tools (topup) act only
   through owner-set limits. NEVER ask your human to paste provider API
   keys in chat — use get_vault_link / POST /v1/keys/link.
5. Acting on the OWNER'S infrastructure (credential broker): if the owner
   vaulted management credentials (mgmt:supabase, mgmt:vercel, mgmt:fly,
   mgmt:resend, mgmt:github, mgmt:npm, mgmt:cloudflare,
   mgmt:lemonsqueezy), you can call those vendors' NATIVE management
   APIs via /proxy/{vendor}/... — the root token is injected server-side
   and NEVER visible to you. Destructive/billing/member routes are
   blocked (MGMT_ACTION_DENIED). To move a secret between vendors use
   POST /v1/secrets/transfer {from:{vendor,resource,field},
   to:{vendor,resource,key}} or mint one with POST /v1/secrets/generate
   — the value never appears in any response or in your context.
   Secrets move; they never show.
6. Something broken? POST /v1/support {tool, expected, actual} and poll
   the status_url. Service health: GET /status. Machine index of
   everything: /agents.json · /openapi.json · /catalog.json ·
   /pricing.json · /llms-full.txt