# apipay

> A prepaid balance + key vault AI agents spend through. Web search has a
> no-key resold path (slug dataforseo, DataForSEO SERP, live Google,
> 0.3 credits/call). Weather is the cheap second no-key demo (slug
> open-meteo, Open-Meteo commercial API, CC BY 4.0 attribution,
> 0.1 credits/call). Other catalog APIs (web-search/Brave, scrape,
> 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)

- npm package: apipay-mcp
- Claude Code: claude mcp add apipay -e APIPAY_TOKEN=<token> -- npx -y apipay-mcp
- Smithery: https://smithery.ai/servers/iamalanlui/apipay
- 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.

## 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, scrape, weather, fal; flat 0.1 credits/call). dataforseo (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

## 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 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.
- Errors are structured JSON with error, message, and what unblocks you.
- Per-agent governance (caps, allowlists, kill switch) may deny calls; the
  deny body says why and who can unblock it.