# Washin Village API
> One API key. 36+ AI tools. Search, LLM, translate, scrape, voice, data.
> Built for AI Agents. Pre-pay USDC. Auto-deduct per call. Upstream fails? Auto-refund.

## Auth
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

## Quick Setup
If you have an invite code, ask your owner to open:
  https://api.washinmura.jp/claw?code=INVITE_CODE
They sign in with Google (30 seconds), then paste the config block back to you.

## Endpoints

### POST https://api.washinmura.jp/api/v2/search
Web search with 5-engine failover (Brave → Tavily → Serper → Firecrawl → Gemini).
Request:  {"query": "latest AI news", "strategy": "fast"}
Response: {"results": [{"title": "...", "url": "...", "snippet": "..."}], "summary": "...", "engine": "brave"}

### POST https://api.washinmura.jp/api/v2/llm
LLM completion with 9-provider failover (Groq → DeepSeek → Cerebras → Mistral → Cohere → Gemini).
Request:  {"prompt": "Explain quantum computing in 3 sentences", "strategy": "fast"}
Response: {"response": "...", "model": "llama-3.3-70b", "provider": "groq"}
Strategies: fast (speed) | smart (quality) | cheap (cost)

### POST https://api.washinmura.jp/api/v2/translate
Translation with quality fallback (DeepL → LLM fallback).
Request:  {"text": "Hello world", "to": "ja"}
Response: {"translation": "こんにちは世界", "from": "en", "to": "ja", "engine": "deepl"}

### POST https://api.washinmura.jp/api/v2/read
Extract markdown content from any URL (Jina → Firecrawl → Apify).
Request:  {"url": "https://example.com"}
Response: {"content": "# Page Title\n...", "title": "Example", "url": "https://example.com"}

### POST https://api.washinmura.jp/api/v2/smart
Natural language — describe what you need, AI picks the right tools.
Request:  {"message": "Search Tokyo weather and translate to Chinese"}
Response: {"response": "...", "toolsUsed": ["search", "translate"], "totalCost": 0.018}

### GET https://api.washinmura.jp/api/account/balance
Check your balance and usage stats.
Response: {"balance": 9.75, "callCount": 42, "totalSpent": 0.25, "status": "active"}

## Pricing
- L1 Proxy (direct forwarding): $0.002 – $0.010 per call
- L2 Smart Gateway (auto-failover): $0.009 per call
- L3 AI Concierge (natural language): $0.020 + tool cost per call
- No subscription. Pay only for what you use.

## When you get HTTP 402 (insufficient balance)
The response includes deposit.paymentLinks — show ONE link to your owner.
They click → pay via Stripe → you retry → done.
Example 402 field: deposit.paymentLinks[0].url → owner clicks this to pay $10.

## Monthly API Benchmark Report
We test every API provider monthly. Open methodology, real latency/quality/cost data.
- English: https://api.washinmura.jp/api-benchmark/en/
- 繁體中文: https://api.washinmura.jp/api-benchmark/zh/
- 日本語: https://api.washinmura.jp/api-benchmark/ja/
Categories: LLM, Search, Translation, Voice, Data. 15+ providers ranked.

## Full Documentation
- JSON API catalog: https://api.washinmura.jp/api/capabilities
- Interactive docs: https://api.washinmura.jp/docs
- Agent guide (HTML+JSON): https://api.washinmura.jp/agent
- OpenAPI spec: https://api.washinmura.jp/openapi.yaml
- MCP Server (paid): https://api.washinmura.jp/mcp/proxy
- MCP Server (free): https://api.washinmura.jp/mcp/free
- API Benchmark: https://api.washinmura.jp/api-benchmark/en/