API Documentation

L1 Shop Street (36 proxy services) + L2 Workshop (10 smart services: Search / LLM / Translate / Read / Embed / Extract / STT / TTS / Geo / News) + L3 AI Concierge. Pre-pay, get results. No upstream accounts needed.

Overview

Washin Village API is an API marketplace for AI Agents. We handle the accounts, billing, and API keys — you just pay and call our endpoints.

	L1 商店街	L2 工坊	L3 AI Concierge
Path	`/api/proxy/*`	`/api/v2/*`	`/api/v2/smart`
How it works	Direct proxy to upstream API	Multi-source fallback + AI enhancement	Natural language → auto-select API → execute
Reliability	Single source (~98%)	Triple fallback (99.97%)	AI-powered routing
Services	36 individual APIs	Search + LLM + Translate + Read + Embed + Extract + STT + TTS + Geo + News	All services via natural language
Pricing	$0.002 – $0.010 per call	$0.009 – $0.009 per call	Varies by tool used
Key Rotation	`POST /api/proxy/account/rotate-key` periodically
Best for	Saving money, specific API needed	Reliability, best results	Simplicity, one endpoint for everything

Quick Start

Create an account — Call the create endpoint. You get an API Key + $0.25 welcome bonus. Invited users can set up quickly at /claw.

Save your API Key — It starts with wv_. Use it in the Authorization header.

Call any service — Free services work immediately. Paid services deduct from your balance.

Step 1 — Create Account

curl

curl -X POST https://api.washinmura.jp/api/proxy/account/create \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent"}'

Step 2 — Save the API Key

response

{
  "success": true,
  "apiKey": "wv_abc123...",     // Save this!
  "balance": 0.25,              // $0.25 welcome bonus
  "message": "Account created"
}

Step 3 — Call a Service

curl

curl -X POST https://api.washinmura.jp/api/proxy/weather \
  -H "Content-Type: application/json" \
  -d '{"latitude": 35.1, "longitude": 140.1}'

Python Example

python

# pip install requests
import requests

# Step 1: 建立帳戶（獲得 API Key + $0.25 體驗金）
resp = requests.post("https://api.washinmura.jp/api/proxy/account/create",
    json={"name": "My AI Agent"})
api_key = resp.json()["apiKey"]

# Step 2: 呼叫免費天氣 API（不需要 Key）
weather = requests.post("https://api.washinmura.jp/api/proxy/weather",
    json={"latitude": 35.1, "longitude": 140.1})
print(weather.json())

# Step 3: 呼叫付費搜尋 API（用 Key）
search = requests.post("https://api.washinmura.jp/api/proxy/brave-search",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"query": "Tokyo weather today"})
print(search.json())

# Step 4: 用 L3 AI Concierge（自然語言，一句搞定）
smart = requests.post("https://api.washinmura.jp/api/v2/smart",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"message": "Search Tokyo weather and translate to Chinese"})
print(smart.json())

Authentication

Use your API Key in the Authorization header (recommended):

header (recommended)

Authorization: Bearer wv_your_api_key_here

✅ Best Practice: Always use the Authorization: Bearer header. This keeps your key out of server logs and URL history.

You can also pass the key as a query parameter for quick testing: ?apiKey=wv_xxx

⚠️ Avoid query params in production — API keys in URLs may appear in logs and browser history.

Free services (weather, wikipedia, exchange-rate, ip-geo, geocode) work without a key. opencage is the premium upgrade of geocode (adds confidence scores, timezone, currency).

Key Rotation

Rotate your API Key periodically for security. The old key is immediately invalidated.

curl

curl -X POST https://api.washinmura.jp/api/proxy/account/rotate-key \
  -H "Authorization: Bearer wv_YOUR_CURRENT_KEY"

See Account > Rotate API Key for full details.

L1 商店街 — T0 🆓 Free Services

🆓 T0 FREE — No API Key Required · 📊 Data

POSTGlobal WeatherFREE

/api/proxy/weather

Real-time weather for any location worldwide.

🆓 T0 Free 📊 Data

Param	Type	Description
latitude	number	Latitude (e.g. 35.1)
longitude	number	Longitude (e.g. 140.1)

POSTWikipediaFREE

/api/proxy/wikipedia

Look up any topic on Wikipedia. Returns summary or search results.

🆓 T0 Free 📊 Data

Param	Type	Description
query	string	Search query or article title
language	string	Optional: "en", "ja", "zh" (default: "en")
sentences	number	Summary sentences (default: 3)

POSTExchange RateFREE

/api/proxy/exchange-rate

Real-time currency exchange rates. 150+ currencies including crypto.

🆓 T0 Free 📊 Data

Param	Type	Description
from	string	Source currency (e.g. "USD")
to	string	Target currency (e.g. "JPY")
amount	number	Optional (default: 1)

POSTIP GeolocationFREE

/api/proxy/ip-geo

Look up geographic location of any IP address. Country, city, ISP, timezone.

🆓 T0 Free 📊 Data

Param	Type	Description
ip	string	IPv4/IPv6 address, or "me" for caller IP

POSTGeocodingFREE

/api/proxy/geocode

Convert address to coordinates or coordinates to address. Forward & reverse geocoding powered by OpenStreetMap.

🆓 T0 Free 📊 Data

Param	Type	Description
q	string	Address (e.g. "Tokyo Tower") or coordinates (e.g. "35.6586,139.7454")
mode	string	Optional: "forward" or "reverse" (auto-detected)
language	string	Optional: "en", "ja", "zh" (default: "en")

POSTOpenCage Geocode$0.002

/api/proxy/opencage

Premium geocoding — confidence scores (0-10), timezone, currency info. Upgrade from free Geocoding.

⚪ T1 Easy 📊 Data

Param	Type	Description
q	string	Address (e.g. "Tokyo Tower") or coordinates (e.g. "35.6586,139.7454")
language	string	Optional: "en", "ja", "zh" (default: "en")
limit	number	Optional: max results 1-10 (default: 5)

POSTWeb ScrapeFREE

/api/proxy/scrape

Fetch and extract text content from any URL. Handles JavaScript rendering.

🆓 T0 Free 🕷️ Scrape

Param	Type	Description
url	string	URL to scrape
selector	string	Optional CSS selector
format	string	"text" \| "html" \| "markdown" (default: text)

L1 商店街 — T1-T2 Affordable ($0.002 - $0.003)

⚪ T1-T2 AFFORDABLE — Login or verify to get API Key

POSTGroq$0.002

/api/proxy/groq

Fastest AI inference (3-18x faster than GPU). Models: Llama 3.3 70B, DeepSeek R1, Gemma 2.

⚪ T1 Easy 🧠 LLM

Param	Type	Description
prompt	string	Your question or prompt
system	string	Optional system prompt
model	string	Default: "llama-3.3-70b-versatile"
maxTokens	number	Default: 500, max: 8192

curl

curl -X POST https://api.washinmura.jp/api/proxy/groq \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Explain quantum computing in 2 sentences"}'

POSTCoinGecko$0.002

/api/proxy/coingecko

18,000+ coins. Real-time prices, market cap, 24h change.

🟢 T2 Steps 📊 Data

Param	Type	Description
coins	string	Comma-separated: "bitcoin,ethereum,solana"
vsCurrencies	string	Default: "usd", also: "jpy", "eur"
include24hChange	boolean	Default: true

POSTTavily$0.002

/api/proxy/tavily

AI-optimized search (industry standard for LangChain/CrewAI). Clean, AI-ready results.

🟢 T2 Steps 🔍 Search

Param	Type	Description
query	string	Search query (max 400 chars)
searchDepth	string	"basic" or "advanced" (default: "basic")
maxResults	number	1-10 (default: 5)
includeAnswer	boolean	Include AI summary (default: true)

POSTClaude Translate$0.003

/api/proxy/translate

Translate text between any languages using Claude. Good at JA / EN / ZH.

🟢 T2 Steps 🌐 Translate

Param	Type	Description
text	string	Text to translate
from	string	Source language (e.g. "ja")
to	string	Target language (e.g. "en")

L1 商店街 — T3-T5 Premium ($0.004 - $0.010)

🔵 T3-T5 PREMIUM — Credit card or paid subscription required

POSTMapbox Directions$0.004

/api/proxy/mapbox

Driving/walking/cycling directions with distance, duration, and turn-by-turn steps. Accepts addresses (auto-geocoded via free OpenStreetMap).

🔵 T3 Card 🧭 Navigation

Param	Type	Description
origin	string	Start point: address or coordinates (e.g. "Tokyo Tower" or "35.6586,139.7454")
destination	string	End point: address or coordinates
profile	string	"driving" \| "driving-traffic" \| "walking" \| "cycling" (default: driving)
language	string	Optional: "en", "ja", "zh"

POSTBrave Search$0.002

/api/proxy/brave-search

Independent search index (35B+ pages). No Google dependency. 60% cheaper than SerpAPI.

🔵 T3 Card 🔍 Search

Param	Type	Description
query	string	Search query
count	number	Results count (default: 10, max: 20)
country	string	Optional: "JP", "US"
freshness	string	"pd" past day, "pw" week, "pm" month

curl

curl -X POST https://api.washinmura.jp/api/proxy/brave-search \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "washin village cats japan", "count": 5}'

POSTDeepSeek$0.003

/api/proxy/deepseek

Reasoning model. GPT-4o quality, 20x cheaper. Great for reasoning and code generation.

🔵 T3 Card 🧠 LLM

Param	Type	Description
prompt	string	Your prompt
system	string	Optional system prompt
maxTokens	number	Default: 500, max: 4000
model	string	Default: "deepseek-reasoner", alt: "deepseek-chat"

POSTDeepL$0.003

/api/proxy/deepl

Best translation API. 25+ languages. Significantly better than Google Translate, especially JA-EN.

🔵 T3 Card 🌐 Translate

Param	Type	Description
text	string	Text to translate
targetLang	string	"EN-US", "JA", "ZH", "KO", "DE", "FR"
sourceLang	string	Optional (auto-detect if omitted)

POSTFirecrawl$0.004

/api/proxy/firecrawl

Scrape any webpage to clean Markdown. Handles JS rendering, CAPTCHA bypass, anti-bot.

🔵 T3 Card 🕷️ Scrape

Param	Type	Description
url	string	URL to scrape
formats	string[]	["markdown","html","json"] (default: ["markdown"])
waitFor	number	Optional: ms to wait for JS

POSTGrok$0.010

/api/proxy/xai

X.ai Grok LLM — Fast reasoning with real-time knowledge. OpenAI-compatible chat completions API.

🟠 T5 Premium 🧠 LLM

Param	Type	Description
prompt	string	Your prompt (required)
system	string	Optional system prompt
model	string	Default: grok-4-1-fast
maxTokens	number	Default: 1000, max: 4000

POSTClaude Generate$0.010

/api/proxy/generate

Text generation with Claude. Content creation, summarization, code generation.

🟠 T5 Premium 🧠 LLM

Param	Type	Description
prompt	string	Your prompt
system	string	Optional system prompt
maxTokens	number	Default: 500, max: 2000
temperature	number	0-1, default: 0.7

POSTClaude Vision$0.010

/api/proxy/vision

Send an image (URL or base64), get AI analysis with Claude Vision.

🟠 T5 Premium 🧠 LLM

Param	Type	Description
image	string	Image URL or base64 data
prompt	string	What to analyze (default: "Describe this image")
language	string	"en", "ja", "zh" (default: "en")

L2 工坊 — Smart Search

L2 WORKSHOP — Multi-source fallback + AI summary

POSTSmart Search$0.009

/api/v2/search

Triple fallback search (Brave → Tavily → Groq). 99.97% reliability. Unified results + AI summary.

Strategies

Strategy	Behavior	Best for
`fast`	First success wins (Brave → Tavily)	Speed (default)
`thorough`	Try all sources, merge results	Completeness
`cheap`	Cheapest first (Groq → Brave)	Budget

Param	Type	Description
query	string	Search query (required)
strategy	string	"fast" \| "thorough" \| "cheap"
maxResults	number	Max results (default: 10)
includeSummary	boolean	AI summary (default: true)

curl

curl -X POST https://api.washinmura.jp/api/v2/search \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "AI agent marketplace 2026", "strategy": "fast"}'

L2 工坊 — Smart LLM

L2 WORKSHOP — Auto-fallback between LLM providers

POSTSmart LLM Router$0.009

/api/v2/llm

Smart routing between Groq (fast) and DeepSeek (smart). Auto-fallback if primary fails.

Strategies

Strategy	Primary → Fallback	Best for
`fast`	Groq LPU → DeepSeek	Speed (default)
`smart`	DeepSeek R1 → Groq	Reasoning quality
`cheap`	Groq (free) → DeepSeek	Budget

Param	Type	Description
prompt	string	Your question (required)
system	string	Optional system prompt
strategy	string	"fast" \| "smart" \| "cheap"
maxTokens	number	Default: 500, max: 4000

curl

curl -X POST https://api.washinmura.jp/api/v2/llm \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is Base chain?", "strategy": "smart"}'

L2 工坊 — Smart Translate

L2 WORKSHOP — Multi-engine translation with fallback

POSTSmart Translate$0.009

/api/v2/translate

Multi-engine translation with automatic fallback. DeepL → DeepSeek → Groq. 30+ languages supported.

Strategies

Strategy	Primary → Fallback	Best for
`quality`	DeepL → DeepSeek → Groq	Best translation (default)
`fast`	Groq LPU → DeepL → DeepSeek	Speed
`cheap`	Groq → DeepSeek	Budget (no DeepL)

Param	Type	Description
text	string	Text to translate (required)
targetLang	string	"EN", "JA", "ZH", "KO", "FR", "DE", "ES", "IT", "PT", "RU" (required)
sourceLang	string	Optional (auto-detect if omitted)
strategy	string	"quality" \| "fast" \| "cheap" (default: "quality")

curl

curl -X POST https://api.washinmura.jp/api/v2/translate \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "The cats of Washin Village are happy", "targetLang": "JA", "strategy": "quality"}'

response

{
  "success": true,
  "translated": "和心村の猫たちは幸せです",
  "detectedSourceLang": "EN",
  "charCount": 40,
  "sourceUsed": "deepl",
  "fallbackUsed": false,
  "price": "$0.009 (2 WT)",
  "layer": 2
}

L2 Workshop Pricing Summary

Service	Price	WT Tokens	Fallback Chain
Smart LLM	$0.009	2 WT	Groq ↔ DeepSeek
Smart Translate	$0.009	2 WT	DeepL → DeepSeek → Groq
Smart Embed	$0.009	2 WT	Cohere → Gemini → Jina
Smart Extract	$0.009	2 WT	Smart Read + Groq → Gemini → DeepSeek
Smart Search	$0.009	2 WT	Brave → Tavily → Groq
Smart STT	$0.009	2 WT	Deepgram Nova-2 → AssemblyAI
Smart TTS	$0.009	2 WT	ElevenLabs (multilingual v2)
Smart Geo	$0.006	1 WT	Free Geocode → OpenCage → Mapbox
Smart News	$0.006	1 WT	NewsAPI → Smart Search fallback

All L2 Workshop services use pre-charge + auto-refund on failure. You only pay if you get results.

L3 AI Concierge

🤖 L3 AI Concierge — 我們的獨家殺手鋏

傳統做法：AI Agent 要學 16+ 個 API 的參數格式

L3 Concierge：一句自然語言，自動選 API → 自動執行 → 結構化回傳

curl

curl -X POST https://api.washinmura.jp/api/v2/smart \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "搜尋東京天氣然後翻譯成英文"}'

查看所有工具能力 | 支援多語言自然語言輸入（中/英/日）

POSTGETSmart Conciergevaries

/api/v2/smart

Natural language → auto-select API → execute → structured response. Supports search, weather, translate, LLM, crypto prices, and more.

Param	Type	Description
message	string	Natural language instruction (required)

curl

curl -X POST https://api.washinmura.jp/api/v2/smart \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Search Tokyo weather and translate to Chinese"}'

GETConcierge CapabilitiesFREE

/api/v2/smart/capabilities

List all tools the concierge can use, with pricing and quick start info. No auth required.

POSTSmart Read${formatPriceUSD(LAYER2_PRICING['smart-read'].priceUSDC)}

/api/v2/read

Unkillable URL reader — URL → clean Markdown. Jina Reader → Firecrawl dual fallback. 99.85%+ reliability.

Strategies

Strategy	Behavior	Best for
`fast`	Jina first, Firecrawl fallback (sequential)	Speed (default)
`thorough`	Both engines in parallel, keep longest content	Quality

Param	Type	Description
url	string	Single URL to read (use this OR urls)
urls	string[]	Batch URLs, max 5 (use this OR url)
strategy	string	"fast" \| "thorough" (default: fast)

curl

curl -X POST https://api.washinmura.jp/api/v2/read \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article", "strategy": "fast"}'

✨ Tip: Use with Smart Search for research workflows — search → read top results → AI summarize

POSTSmart Embed$0.009

/api/v2/embed

Unkillable text vectorization — Cohere Embed v4 → Gemini Embedding → Jina Embed v3 triple fallback. For RAG / semantic search.

Strategies

Strategy	Behavior	Best for
`quality`	Cohere first (best embeddings), Gemini/Jina fallback	Production RAG
`fast`	Gemini first (fastest, free), Cohere/Jina fallback	Speed (default)
`cheap`	Jina first (free 10M tokens), Gemini/Cohere fallback	Bulk indexing

Param	Type	Description
texts	string[]	Array of texts to embed (required, max 96)
strategy	string	"quality" \| "fast" \| "cheap" (default: quality)
dimensions	number	Output dimensions (default 1024)
inputType	string	"query" \| "document" (affects optimization)

curl

curl -X POST https://api.washinmura.jp/api/v2/embed \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["Hello world", "Washin Village"], "strategy": "quality"}'

POSTSmart Extract$0.009

/api/v2/extract

URL → structured JSON extraction. Smart Read (URL → Markdown) + LLM analysis (Groq → Gemini → DeepSeek triple fallback).

Modes

Mode	Behavior	Best for
`auto`	LLM decides what to extract (title, dates, prices, etc.)	Quick extraction
`schema`	Fill user-provided JSON schema	Structured data pipelines
`fields`	Extract specific named fields	Targeted extraction

Param	Type	Description
url	string	URL to extract data from (required)
mode	string	"auto" \| "schema" \| "fields" (default: auto)
schema	object	JSON schema (for mode=schema)
fields	string[]	Field names (for mode=fields)
language	string	Output language: "en", "ja", "zh"

curl

curl -X POST https://api.washinmura.jp/api/v2/extract \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "mode": "auto"}'

✨ Tip: Combine with Smart Embed for a full RAG pipeline — extract structured data → embed for search.

POSTSmart STT (Speech-to-Text)${formatPriceUSD(LAYER2_PRICING['smart-stt'].priceUSDC)}

/api/v2/stt

Unkillable speech-to-text — Deepgram Nova-2 → AssemblyAI dual fallback. Supports audio file upload or audio URL.

Param	Type	Description
url	string	URL of audio file (use this OR upload file)
audio	file	Audio file via multipart/form-data (use this OR url)
language	string	Language hint: "en", "ja", "zh" (optional, auto-detect)

curl — audio URL

curl -X POST https://api.washinmura.jp/api/v2/stt \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/audio.mp3", "language": "en"}'

curl — file upload

curl -X POST https://api.washinmura.jp/api/v2/stt \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -F "[email protected]" \
  -F "language=ja"

POSTSmart TTS (Text-to-Speech)${formatPriceUSD(LAYER2_PRICING['smart-tts'].priceUSDC)}

/api/v2/tts

High-quality text-to-speech powered by ElevenLabs. Multilingual, multiple voices. Returns audio/mpeg binary.

Param	Type	Description
text	string	Text to convert to speech (required, max 5000 chars)
voice	string	ElevenLabs voice_id (optional, default: Adam)
language	string	Language hint for pronunciation (optional)

curl

curl -X POST https://api.washinmura.jp/api/v2/tts \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Welcome to Washin Village", "language": "en"}' \
  --output output.mp3

🎤 Response is raw audio/mpeg binary. Use --output file.mp3 to save. Get available voices at GET /api/v2/tts/info

POSTSmart Geo${formatPriceUSD(LAYER2_PRICING['smart-geo'].priceUSDC)}

/api/v2/geo

Unkillable geocoding — Free Geocode → OpenCage → Mapbox triple fallback. Forward (name → coords) and reverse (coords → address).

Param	Type	Description
query	string	Place name to geocode (use this OR lat+lon)
lat	number	Latitude for reverse geocoding (use with lon)
lon	number	Longitude for reverse geocoding (use with lat)

curl — forward

curl -X POST https://api.washinmura.jp/api/v2/geo \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Tokyo Tower"}'

curl — reverse

curl -X POST https://api.washinmura.jp/api/v2/geo \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat": 35.6586, "lon": 139.7454}'

POSTSmart News${formatPriceUSD(LAYER2_PRICING['smart-news'].priceUSDC)}

/api/v2/news

News search + headlines — NewsAPI (80,000+ sources) with Smart Search fallback. Auto-translate to target language.

Strategies

Strategy	Behavior	Best for
`search`	Search news by keyword, Smart Search fallback	Keyword search (default)
`headlines`	Top headlines by country/category	Breaking news

Param	Type	Description
query	string	Search keywords (required for strategy=search)
strategy	string	"search" \| "headlines" (default: search)
country	string	2-letter code: "us", "jp", "tw" (for headlines)
category	string	"business" \| "technology" \| "sports" \| "health" \| "science" \| "entertainment"
pageSize	number	Number of articles (default 20, max 100)
targetLanguage	string	Auto-translate results: "ja", "zh", "en"

curl

curl -X POST https://api.washinmura.jp/api/v2/news \
  -H "Authorization: Bearer wv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "AI technology", "strategy": "search", "pageSize": 5}'

Account Management

POSTCreate AccountFREE

/api/proxy/account/create

Create a new agent account. Returns API Key (wv_xxx) + $0.25 welcome bonus.

Param	Type	Description
name	string	Your agent name (required)

GETCheck Balance

/api/proxy/account/balance

Check your balance, call count, and available calls per service. Requires API Key.

curl

curl https://api.washinmura.jp/api/proxy/account/balance \
  -H "Authorization: Bearer wv_YOUR_KEY"

GETBalance (Simplified)FREE

/api/account/balance

Simplified balance check. Returns balance, callCount, and totalSpent only. Requires Bearer token auth (Authorization: Bearer wv_xxx).

curl

curl https://api.washinmura.jp/api/account/balance \
  -H "Authorization: Bearer wv_YOUR_KEY"

response

{
  "success": true,
  "balance": 24.75,
  "callCount": 142,
  "totalSpent": 5.25
}

GETTransaction History

/api/proxy/account/history

Get your transaction history. Deposits, charges, refunds. Requires API Key.

Param	Type	Description
limit	number (query)	Max transactions (default: 20)

POSTRotate API KeyFREE

/api/proxy/account/rotate-key

Generate a new API Key and immediately invalidate the old one. Balance and history are preserved.

⚠️ Warning: The old key is invalidated immediately. Make sure to save the new key!

curl

curl -X POST https://api.washinmura.jp/api/proxy/account/rotate-key \
  -H "Authorization: Bearer wv_YOUR_CURRENT_KEY"

response

{
  "success": true,
  "newApiKey": "wv_new_key_here...",  // Save this immediately!
  "agentId": "agent-xxx",
  "balance": 0.25,
  "important": "Old API Key is now invalid"
}

💡 Best Practice: Rotate your key every 30 days or whenever you suspect it may have been exposed.

GETUsage ReportFREE

/api/proxy/account/report

Detailed usage analytics: total spent, top services, 7-day daily breakdown, WT Token earnings.

curl

curl https://api.washinmura.jp/api/proxy/account/report \
  -H "Authorization: Bearer wv_YOUR_KEY"

response

{
  "success": true,
  "report": {
    "agentName": "My Agent",
    "totalSpent": 0.045,
    "totalTransactions": 12,
    "topServices": [
      { "name": "groq", "count": 5, "spent": 0.005 },
      { "name": "brave-search", "count": 4, "spent": 0.032 }
    ],
    "dailyBreakdown": [
      { "date": "2026-02-10", "spent": 0.01, "transactions": 3 },
      // ... 7 days
    ],
    "wtTokensEarned": 9.0,
    "currentBalance": 0.205,
    "accountAge": "2026-02-05T10:30:00Z"
  }
}

POSTDeposit (Stripe)

/api/stripe/checkout

Add funds via Stripe credit card payment. Minimum $5, instant credit.

Param	Type	Description
amount	number	Amount in USD ($5, $10, $25, $50)
apiKey	string	Your wv_xxx API Key

For self-service, use Stripe payment page or Dashboard.

Rate Limiting

All endpoints are rate-limited per IP address to prevent abuse and ensure fair usage.

Endpoint Category	Limit	Window	Exceeded Response
General API (`/api/proxy/`, `/api/v2/`)	100 requests	1 minute	429 Too Many Requests
Admin Panel (`/admin/*`)	60 requests	1 minute	429 Too Many Requests

🛈 Headers: Rate limit info is included in response headers:
X-RateLimit-Limit — Max requests per window
X-RateLimit-Remaining — Remaining requests
X-RateLimit-Reset — Unix timestamp when window resets

Admin Brute Force Protection

The admin panel has additional protection against brute-force attacks:

Rule	Detail
Max failed attempts	3 per IP
Lockout duration	15 minutes
Response when locked	403 Forbidden

Security Best Practices

Use Bearer Token auth — Always send your API Key in the Authorization: Bearer wv_xxx header, never in URLs.

Rotate keys regularly — Call POST /api/proxy/account/rotate-key every 30 days. Old key is immediately invalidated.

Monitor usage — Check GET /api/proxy/account/report to detect unusual spending patterns.

Store keys securely — Use environment variables or a secrets manager. Never commit keys to version control.

Security Features

Feature	Description
🔒 API Key Encryption	All keys encrypted at rest with AES-256-GCM
🔓 Key Rotation	One-click key rotation, old key immediately invalid
🛡️ Rate Limiting	100 req/min per IP, 10 req/min for admin
🔐 Brute Force Protection	3 failures = 15 min lockout
🛒 Pre-charge + Refund	Balance deducted before API call, refunded on failure
🛠️ Security Headers	X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy
📄 Audit Logging	All admin actions and key operations logged
💳 Stripe Idempotency	Duplicate webhook payments automatically rejected

Response Headers

Every response includes security headers:

headers

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=()

API Documentation

Overview

Quick Start

Step 1 — Create Account

Step 2 — Save the API Key

Step 3 — Call a Service

Python Example

Authentication

Key Rotation

L1 商店街 — T0 🆓 Free Services

L1 商店街 — T1-T2 Affordable ($0.002 - $0.003)

L1 商店街 — T3-T5 Premium ($0.004 - $0.010)

L2 工坊 — Smart Search

Strategies

L2 工坊 — Smart LLM

Strategies

L2 工坊 — Smart Translate

Strategies

L2 Workshop Pricing Summary

L3 AI Concierge

🤖 L3 AI Concierge — 我們的獨家殺手鋏

Strategies

Strategies

Modes

Strategies

Account Management

Rate Limiting

Admin Brute Force Protection

Security Best Practices

Security Features

Response Headers

📮 回報問題 / 建議