# 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


# Full capability detail

## companies-house — Companies House (UK)
The UK company register: search companies, get a company profile, or list officers. Open government data; no key from you.
lane: master · price: 0.3 credits/call
params:
  - company (string): Company name to search, or an exact company number
  - type (string): "search" (default), "profile", or "officers" (the latter two need a company number)
  - limit (number): Max search results, 1-20 (default 5)

## dataforseo — Web Search (DataForSEO SERP)
Live Google organic search results (titles, URLs, snippets) via DataForSEO SERP API. Resold through apipay — no user-supplied key. Data is transformed into agent answers (not resold raw).
lane: master · price: 0.3 credits/call
params:
  - q (string): Search query
  - count (number): Results to return, 1-100 (default 10)
  - country (string): Country code (e.g. "us", "gb", "hk"). Default "us".
  - language (string): Language code (e.g. "en", "zh"). Default "en".

## fal — fal.ai AI Inference
Run fal.ai models (FLUX image generation, whisper, upscalers, …) by model id with the model's JSON input. BYOK: vault your own fal key.
lane: vault · price: BYOK — flat 0.1 credits/call
params:
  - model (string): fal model id, e.g. "fal-ai/flux/schnell"
  - input (object): Model input JSON per fal docs, e.g. {"prompt": "a red fox"}

## open-meteo — Weather & Forecast (Open-Meteo)
Current conditions and optional 7-day forecast for a lat/lon. Resold via our Open-Meteo commercial subscription — no user-supplied weather key. Weather data by Open-Meteo.com (CC BY 4.0).
lane: master · price: 0.1 credits/call
params:
  - lat (number): Latitude (-90..90)
  - lon (number): Longitude (-180..180)
  - forecast (boolean): Also return the 7-day daily forecast (same single provider request)
  - units (string): "metric" (default) or "imperial"

## scrape — Web Fetch (DataForSEO markdown)
Fetch a URL and return transformed page markdown via DataForSEO On-Page Content Parsing. Resold through apipay — no user-supplied key. Markdown only; never raw HTML or full provider JSON.
lane: master · price: 0.3 credits/call
params:
  - url (string): http(s) URL to fetch

## scrapingbee — Web Scraper (ScrapingBee)
Fetch a URL through a scraping proxy and return the page HTML (ScrapingBee).
lane: vault · price: BYOK — flat 0.1 credits/call
params:
  - url (string): URL to fetch
  - render_js (boolean): Render JavaScript (costs ~5x)

## sec-edgar — SEC EDGAR Filings
US company filings from SEC EDGAR: resolve a ticker or CIK, get the latest filings (10-K, 10-Q, 8-K, …) with direct document links. Public-domain data; no key from you.
lane: master · price: 0.3 credits/call
params:
  - company (string): Ticker (e.g. AAPL) or numeric SEC CIK
  - form (string): Filter by form type, e.g. "10-K", "10-Q", "8-K"
  - limit (number): Max filings to return, 1-20 (default 5)

## weather — Weather & Forecast
Current conditions for a lat/lon, optionally with a 10-day daily forecast (OpenWeatherMap One Call 4.0).
lane: vault · price: BYOK — flat 0.1 credits/call
params:
  - lat (number): Latitude (-90..90)
  - lon (number): Longitude (-180..180)
  - forecast (boolean): Also return the 10-day daily forecast (adds a second metered provider call)
  - units (string): "metric" (default), "imperial", or "standard"

## web-search — Web Search
Live web search returning titles, URLs, and snippets (Brave Search).
lane: vault · price: BYOK — flat 0.1 credits/call
params:
  - q (string): Search query
  - count (number): Results to return, 1-20 (default 10)