Self-healing API proxy for AI agents. Pay per fix, not per month.
npm version PyPI version License: MIT Website
Your agent hits a 422. It has no idea why. It retries the same broken payload five times, burns through your token budget, and crashes.
SelfHeal is an API proxy that intercepts failed requests, analyzes them with an LLM, and returns structured fix instructions — charging only when the fix succeeds via x402 micropayments (USDC on Base). Successful calls pass through free.
Agent → POST /api/x402/proxy → Forward to target API
↓ Success (2xx) ↓ Failure (4xx/5xx)
→ Free pass-through (0ドル) → Return 402 with x402 payment spec
→ Agent pays 0ドル.001-0ドル.005 USDC
→ LLM analyzes error
→ Structured fix returned
→ Payment settled only if heal succeeds
No API keys. No signup. No subscriptions.
# Successful request — free pass-through curl -X POST https://selfheal.dev/api/x402/proxy \ -H "Content-Type: application/json" \ -d '{"url": "https://api.example.com/users", "method": "GET"}' # Failed request — returns 402 with payment spec curl -X POST https://selfheal.dev/api/x402/proxy \ -H "Content-Type: application/json" \ -d '{"url": "https://api.openai.com/v1/chat/completions", "method": "POST", "body": "{\"model\":\"gpt-4o-mini\"}"}'
from graceful_fail import GracefulFail gf = GracefulFail() # No API key needed (x402 mode) response = gf.post("https://api.example.com/users", json={"name": "Alice"}) if response.healed: print(response.error_analysis.actionable_fix_for_agent) elif response.payment_required: print("Payment needed:", response.payment_required) else: print("Success:", response.data)
import { GracefulFail } from "graceful-fail"; const gf = new GracefulFail({ onPaymentRequired: async (spec) => { // Your x402 payment logic here return paymentProof; }, }); const resp = await gf.post("https://api.example.com/users", { json: { name: "Alice" }, }); if (resp.healed) { console.log(resp.errorAnalysis!.actionable_fix_for_agent); }
# Still works — backward compatible gf = GracefulFail(api_key="gf_your_key") resp = gf.post(url, json=payload)
{
"healed": true,
"settled": true,
"transaction": "0xbf023f9c...",
"original_status_code": 401,
"error_analysis": {
"is_retriable": false,
"human_readable_explanation": "No API key was provided in the Authorization header.",
"actionable_fix_for_agent": "Add Authorization header with your OpenAI API key.",
"suggested_payload_diff": {
"remove": [],
"add": {},
"modify": {}
},
"error_category": "auth"
},
"meta": {
"tier": "complex",
"cost_usdc": 0.003,
"latency_ms": 3038
}
}| Scenario | Cost | When |
|---|---|---|
| Success (2xx/3xx) | 0ドル | Always free |
| Simple error (400, 404, 422) | 0ドル.001 USDC | Only on successful heal |
| Moderate error (500, 502, 503) | 0ドル.002 USDC | Only on successful heal |
| Complex error (429, 403, auth) | 0ドル.003-0ドル.005 USDC | Only on successful heal |
| Failed analysis | 0ドル | Never charged |
Payments via x402 protocol — USDC on Base. Gasless for payers (EIP-3009).
| Method | Path | Description |
|---|---|---|
| POST | /api/x402/proxy |
Proxy request with x402 payment on failure |
| POST | /api/x402/heal |
Direct error analysis |
| GET | /api/x402/pricing |
Current pricing tiers |
| GET | /api/x402/usage |
Usage statistics |
| GET | /metrics |
Prometheus metrics |
| GET | /health |
Health check |
| POST | /api/proxy |
Legacy proxy (API key auth) |
| SDK | Install | Version |
|---|---|---|
| Python | pip install graceful-fail |
0.4.0 |
| Python + LangChain | pip install 'graceful-fail[langchain]' |
0.4.0 |
| Node.js / TypeScript | npm install graceful-fail |
0.4.0 |
Both SDKs support x402 mode (default) and legacy API key mode. LangChain and CrewAI integrations included.
- Outcome-based pricing — pay only when fixes succeed, via x402 micropayments
- Zero-overhead pass-through — 2xx/3xx returned verbatim, 0ドル cost
- LLM-powered analysis — structured JSON with fix instructions, payload diffs, error categories
- Provider-aware — specialized handling for OpenAI, Anthropic, Google, Cohere, Mistral errors
- Credential stripping — auth headers and API keys never reach the LLM
- Prometheus metrics — proxy requests, heals, latency, x402 payments, LLM token usage
- Webhook alerting — traffic spikes, LLM cost overruns, low heal success rates
- Response caching — TTL cache for successful GET requests
- Dashboard — API key management, request logs, usage analytics
- OpenAPI 3.1 spec — import into Postman or any OpenAPI client
git clone https://github.com/carsonlabs/graceful-fail.git cd graceful-fail npm install cp .env.example .env # configure database, LLM keys, x402 wallet npm run db:push # run database migrations npm run dev # start development server
Key environment variables for x402:
X402_RECEIVING_WALLET=0xYourWalletAddress X402_NETWORKS=base-sepolia # or "base" for mainnet X402_TESTNET=true ANTHROPIC_API_KEY=sk-ant-... # for LLM error analysis
See .env.example for the full list.
Built by Freedom Engineers.
MIT License