Execution

wayforth_execute()

Execute a managed service by its slug. Parameters vary by service — check the catalog or call wayforth_search() first to discover available services.

Examples

# Translation
wayforth_execute(slug="deepl", text="Hello world", target_lang="ES")

# Transcription
wayforth_execute(slug="whisper-large", audio_url="https://example.com/clip.mp3")

# Embeddings
wayforth_execute(slug="openai-embeddings", input="The quick brown fox", model="text-embedding-3-large")

# Web search
wayforth_execute(slug="perplexity-sonar", query="latest AI research 2025", num_results=5)

Response envelope

All responses include billing metadata alongside the service's native output:

{
  // Service-native fields (varies by service)
  "translation": "¡Hola, mundo!",
  "detected_source_lang": "EN",

  // Wayforth billing fields (always present)
  "billed_calls": 1,
  "credits_remaining": 97,
  "latency_ms": 423,
  "provider": "deepl"
}

Error handling

from wayforth import WayforthError, InsufficientCreditsError, ServiceUnavailableError

try:
    result = wayforth_execute(slug="deepl", text="Hello", target_lang="ES")
except InsufficientCreditsError:
    print("Top up at https://wayforth.io/billing")
except ServiceUnavailableError:
    print("Provider degraded — Wayforth will retry automatically")
except WayforthError as e:
    print(f"Error {e.status_code}: {e}")

Managed services

Wayforth manages authentication, rate limits, and retries for these 15 services. You never handle upstream API keys for managed services — use Wayforth credits instead.

BYOK — Bring Your Own Key

For services where you already have an API subscription, BYOK lets you route calls through Wayforth's infrastructure (retry, failover, observability) while using your own upstream credentials. You are only charged the Wayforth gateway fee — not the underlying service cost.

Setup

curl -X POST https://gateway.wayforth.io/v1/byok \
  -H "x-wayforth-api-key: $WAYFORTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "deepl", "upstream_key": "your-deepl-key"}'

# Wayforth routes through your DeepL key transparently
wayforth_execute(slug="deepl", text="Hello", target_lang="FR")

BYOK billing

x402 native execution

x402 is an open HTTP payment protocol that embeds micropayment settlement directly into the request lifecycle. With x402, you pay per call on-chain (USDC on Base) with no subscription or pre-funded credits needed.

How it works

1. Your client sends a request to the gateway without an API key
2. The gateway returns 402 Payment Required with a payment descriptor
3. Your x402-capable client signs and broadcasts a USDC microtransaction on Base
4. The gateway settles the transaction and proxies your request to the service
5. The response is returned along with a payment receipt

from x402 import X402Client  # x402 Python client

client = X402Client(wallet_key="0x...")

# No Wayforth API key needed — payment is on-chain
result = client.post(
    "https://gateway.wayforth.io/v1/execute/deepl",
    json={"text": "Hello", "target_lang": "ES"}
)
print(result.json()["translation"])  # Hola

x402 vs credits

Self-healing payments

Wayforth's execution layer continuously monitors service health and automatically reroutes calls when a provider degrades — without any action from you.

How it works

1. Health monitoring: Each managed service is probed every 30 seconds. WRI score is updated continuously.
2. Threshold detection: If a service's WRI drops below its tier's minimum or 3 consecutive calls fail, it enters degraded state.
3. Automatic failover: Subsequent calls are rerouted to the next-best provider in the same category with the highest WRI score.
4. Billing protection: Failed calls that were rerouted are not charged to your account. The retry is billed once success is confirmed.
5. Recovery: When the original provider recovers (WRI returns above threshold), traffic is automatically shifted back.

Failover visibility

Every response includes a provider field so you can see which upstream handled your call:

{
  "translation": "Hola",
  "provider": "google-translate",
  "failover": true,
  "original_provider": "deepl",
  "billed_calls": 1
}