# ToolCall Store

> API storefront for AI agents. Call tools for domains, DNS, business email, LLM routing, image generation, human approvals, and proof receipts. Every billable or irreversible action goes through quote → approve → execute → receipt.

Base URL: https://toolcallstore.com
API Base: https://toolcallstore.com/v1
Auth: Authorization: Bearer tc_live_... (production) | tc_test_... (sandbox)

## Authentication examples

# Every request needs this header:
Authorization: Bearer tc_live_xxxxxxxxxxxxxxxxxxxx

# Sandbox (mocked providers, no real charges):
Authorization: Bearer tc_test_xxxxxxxxxxxxxxxxxxxx

# Scope grant example — check your key's scopes before calling:
curl https://toolcallstore.com/v1/account/balance   -H Authorization: Bearer tc_live_xxxxxxxxxxxx
# → {balance_usd: 100.0, plan: starter, ...}

# Error if scope missing:
# 403 {error: {code: insufficient_scope, required_scope: domains:buy}}
Idempotency: Idempotency-Key: <uuid4> REQUIRED on all POST /v1/execute and POST /v1/domains/register calls

## Cold-start reading order
Parse in this order: (1) llms.txt — policy and pointers; (2) catalog.json — tool list with input/output schemas and examples; (3) openapi.json — full schemas for edge cases. Stop as soon as you have enough to form your request.

## Discovery files (read these first)
- /llms.txt          — this file; protocol summary for agents
- /llms-full.txt     — extended docs with worked examples
- /catalog.json      — all 9 tools with endpoints, scopes, risk, providers
- /openapi.json      — full OpenAPI 3.1 spec
- /pricing.json      — metered pricing units
- /models.json       — LLM provider routing table
- /.well-known/agent-card.json  — Google A2A agent card
- /.well-known/ai-plugin.json   — ChatGPT / MCP plugin manifest

## Protocol — agents MUST follow this order

1. SEARCH   POST /v1/tools/search {"intent": "<natural language goal>"}
            Returns matching tools with scopes and approval_required flag.
            OR: GET /v1/tools/list for the full catalog.

2. QUOTE    POST /v1/quotes {"items": [{tool_id, ...params}]}
            Returns quote_id, total_estimate_usd, requires_approval, expires_at.
            Re-quote if expires_at has passed (re-quoting returns 422 on expired).
            NEVER call execute without a valid quote_id or approval_id.

3. APPROVE  POST /v1/approvals {"quote_id": "q_...", "notify": "email|webhook"}
            Required when quote.requires_approval == true.
            Returns approval_id, status: "pending".
            Poll: GET /v1/approvals/{id} until status == "granted" | "denied".
            On "denied": stop. Surface denial to the human. Do not retry.

4. EXECUTE  POST /v1/execute {"approval_id": "appr_..."}
            OR pass approval_id directly to the action endpoint.
            ALWAYS include Idempotency-Key header.
            Returns execution_id, receipt_id, per-action status.

5. VERIFY   GET /v1/receipts/{receipt_id}
            Check dns_verified, mx_verified, provider_order_id.
            Keep receipt_id for audit.

6. RECOVER  Use rollback_hint from the receipt if any action failed.
            POST to the rollback endpoint listed in rollback_hint.

## Agent policy

1. Never execute a billable or irreversible action without a valid approval_id.
2. Never retry a denied approval. Surface the denial reason to the human.
3. Always include Idempotency-Key on mutating requests. On 409 conflict, fetch the original receipt — do not re-execute.
4. On 402 payment_required: stop and surface to human. Do not retry.
4b. Any quote where total_estimate_usd >= $25.00 requires human approval regardless of individual tool approval_required flag.

## Tools

### domains.search
Endpoint: POST /v1/domains/search (domain_name:string*, tld_suggestions?:boolean) — check availability
Scopes:   domains:read
Approval: NO
Risk:     low
Cost:     free
Providers: OpenProvider
Body:     {"domains": ["example.com", "example.io"], "suggest_alternatives": true}
Receipt:  {available, price_usd, renewal_usd, premium} per candidate

### domains.register
Endpoint: POST /v1/domains/register (domain_name:string*, years?:int, approval_id:string*) — IRREVERSIBLE; approval_id required
Scopes:   domains:buy
Approval: YES — irreversible and billable
Risk:     high
Cost:     $12–60/yr (TLD-dependent via OpenProvider)
Providers: OpenProvider
Body:     {"domain": "example.com", "years": 1, "approval_id": "appr_..."}
Header:   Idempotency-Key: <uuid>
Receipt:  {provider_order_id, registered_until, nameservers, dns_verified}

### dns.apply_template
Endpoint: POST /v1/dns/templates/apply (domain_name:string*, template:string*, approval_id:string*) — applies DNS template
Scopes:   dns:write
Approval: YES — mutating (reversible via rollback snapshot)
Risk:     high
Cost:     $0.10/changeset
Providers: OpenProvider DNS
Body:     {"domain": "example.com", "template": "email|website|app|agent_endpoint", "approval_id": "appr_..."}
Header:   Idempotency-Key: <uuid>
Receipt:  {records_applied, rollback_token, rollback_hint}

### email.create_mailbox
Endpoint: POST /v1/email/mailboxes (domain_name:string*, localpart:string*, approval_id:string*) — creates mailbox via Stalwart
Scopes:   email:write
Approval: YES — billable monthly
Risk:     medium
Cost:     $2–4/mailbox/month
Providers: Stalwart SMTP (self-hosted)
Body:     {"domain": "example.com", "mailboxes": ["hello","support"], "approval_id": "appr_..."}
Receipt:  {mailboxes_created, mx_verified, spf_verified, dkim_verified, dmarc_verified, rollback_hint}

### llm.route
Endpoint: POST /v1/llm/chat (messages:array*, policy?:string, max_cost_usd?:number) — LLM routing
Scopes:   llm:call
Approval: NO
Risk:     medium
Cost:     provider cost + 12% routing fee (BYOK reduces to orchestration fee only)
Providers: Anthropic (Claude), OpenRouter (multi-model)
Body:     {"model": "auto|claude-3-5-sonnet|...", "messages": [...], "max_cost_usd": 0.05}
Receipt:  {model_used, provider, tokens_in, tokens_out, cost_usd}

### media.image.generate
Endpoint: POST /v1/media/images (prompt:string*, count?:int, provider_hint?:string, approval_id?:string) — image generation
Scopes:   media:generate
Approval: NO
Risk:     medium
Cost:     $0.01–0.08/image (varies by provider and resolution)
Providers: Stability AI, Together AI (FLUX.1.1-pro), fal.ai
Body:     {"prompt": "...", "provider": "auto|stability|together|fal", "width": 1024, "height": 1024, "count": 1}
Receipt:  {asset_urls, provider, model, cost_usd, content_policy_result}

### media.video.generate
Endpoint: POST /v1/media/videos (prompt:string*, duration_seconds?:int, approval_id:string*) — video; approval always required
Scopes:   media:generate
Approval: YES — can be expensive
Risk:     medium
Cost:     $0.05–0.50/second of output
Providers: fal.ai, Replicate
Body:     {"prompt": "...", "duration_seconds": 4, "approval_id": "appr_..."}
Receipt:  {video_url, duration_seconds, provider, cost_usd}

### approvals.create
Endpoint: POST /v1/approvals (quote_id:string*, reason?:string, webhook_url?:string) — returns approval_id, polls until approved/denied
Scopes:   approvals:create
Approval: NO (this IS the approval mechanism)
Risk:     low
Cost:     included in all plans
Body:     {"quote_id": "q_...", "notify": "email|webhook", "message": "optional context for human"}
Receipt:  {approval_id, status, expires_at}

### proof.receipt
Endpoint: GET /v1/receipts/{id} — returns full proof with provider_id, cost_usd, timestamps, rollback_hint
Scopes:   receipts:read
Approval: NO — read-only
Risk:     low
Cost:     included
Returns:  {receipt_id, tool_id, executed_at, provider, provider_order_id, cost_usd, sell_usd, verified_at, rollback_hint}

(* = required)

## Endpoints quick-reference

POST /v1/quotes (items:string[]*, context?:string) — returns quote_id, total_estimate_usd, requires_approval, expires_at
POST /v1/approvals (quote_id:string*, reason?:string, webhook_url?:string) — returns approval_id, polls until approved/denied
POST /v1/execute (approval_id:string*) — runs approved action; returns receipt_id
GET /v1/receipts/{id} — returns full proof with provider_id, cost_usd, timestamps, rollback_hint

## Error handling

402 payment_required   — spend cap hit or no credit; surface to human; do NOT retry
403 insufficient_scope — key lacks the required scope; do NOT escalate scope silently
403 approval_required  — must obtain approval_id first; call POST /v1/approvals
409 conflict           — duplicate Idempotency-Key; fetch the original receipt instead
422 unprocessable      — quote expired; re-quote with POST /v1/quotes
429 rate_limited       — back off 60 seconds; do NOT hammer

## Pricing model
Subscription ($0–$149+/mo) includes a monthly credit. Metered billing applies to overages.
Quotes lock the price for 30 minutes. Execution deducts from account balance.
Check balance: GET /v1/account/balance → {balance_usd, plan, credit_remaining_usd}

## Human pages (for reference only — agents use JSON endpoints above)
- Home:   https://toolcallstore.com/
- Docs:   https://toolcallstore.com/docs/
- Pricing: https://toolcallstore.com/pricing.html
- Terms:  https://toolcallstore.com/legal/terms.html