# 1ToolRing Documentation

> 1ToolRing is one API key and one prepaid wallet in front of a catalog of callable tools, built so an AI agent can search the catalog, read the price, call the tool, and see the exact charge. Today the catalog covers email verification (backed by MillionVerifier). This file is a plain-text index of the documentation for LLM ingestion.

## Product

- Base URL: https://api.1toolring.com
- Dashboard: https://app.1toolring.com
- Product home and pricing: https://1toolring.com/pricing/
- MCP server: https://mcp.1toolring.com/mcp (tools: search_catalog, call_service)
- Agent onboarding text: https://api.1toolring.com/llms.txt

## Pricing

- Pay as you go, prepaid credits. 1 credit = Rp1. No plans, no subscriptions.
- Top-ups: Rp29.000, Rp59.000, Rp109.000, Rp249.000, paid through Polar (merchant of record), credited after the payment is confirmed.
- Every catalog entry carries price_credits and price_unit. Email verification: 105 credits per chargeable address.
- A failed call is never charged. The X-ToolRing-Credits response header is the amount actually charged.

## Auth

- Metered calls: `Authorization: Bearer <key>` (keys stored as SHA-256 hashes). Email verification also accepts `x-api-key`.
- Account endpoints: `Authorization: Bearer <JWT>` (HS256, 7-day TTL).
- OAuth: Google and GitHub.
- Bot protection: Cloudflare Turnstile on register and login.

## Key endpoints

- GET /api/v1/catalog, /api/v1/catalog/search?q=, /api/v1/catalog/{id} (public, free)
- POST /api/v1/email/verify (one address), POST /api/v1/email/verify/bulk (CSV/TXT job)
- GET /api/v1/email/verify/jobs, /jobs/{job_id}, /jobs/{job_id}/report; POST /jobs/{job_id}/cancel
- GET /api/v1/email/verify/credits
- POST /billing/topup (Polar checkout), GET /billing/topup/status/{invoice_id}, GET /billing/credits

## Errors

Envelope: `{"error":{"code","message"}}`. Common: UNAUTHORIZED(401), INVALID_API_KEY(401), VALIDATION_ERROR(400), INSUFFICIENT_CREDITS(402), BUDGET_EXCEEDED(402), RATE_LIMITED(429), NOT_FOUND(404), UPSTREAM_ERROR(502).

## Docs navigation

- Overview: /overview
- Quickstart: /getting-started
- Auth: /authentication/api-keys
- Concepts: /concepts/rate-limits
- Reference: /reference/catalog, /reference/email-verification, /reference/account
- MCP: /sdks/mcp
- Troubleshooting: /troubleshooting

Raw Markdown for any page: /md/<slug> (e.g. /md/reference/email-verification).