Docs

Build with Waterfall

Waterfall is an OpenAI-compatible API gateway. Point your app at our base URL, pick a routing strategy, and let Waterfall choose the smartest capable model for each request.

Base URL

https://api.getwaterfall.org/v1

Auth

Use a Waterfall API key for free traffic or card-funded credits. x402 can pay a paid request directly in USDC on Base.

Format

OpenAI-compatible chat completions. Most OpenAI SDK code works with a base URL change.

Review the trust model before pointing agents at Waterfall.

The Trust Center covers architecture, logging, privacy, security controls, BYOK status, and what data should not be routed through a third-party API.

Open Trust Center

Quick Start

1. Choose how to pay

Add $10 or more in card credits, or let an x402 client settle paid requests in USDC on Base.

2. Pick a strategy

Start with free_smart for free agent work, or auto for the default cascade.

3. Send the request

We handle model choice, fallbacks, and cost-aware routing.

Examples

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.getwaterfall.org/v1",
    api_key="wf-sk-your-key"
)

response = client.chat.completions.create(
    model="auto",
    extra_body={"routing_strategy": "free_smart"},
    messages=[{"role": "user", "content": "Write a short launch checklist"}],
)

print(response.choices[0].message.content)

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.getwaterfall.org/v1",
  apiKey: "wf-sk-your-key",
});

const response = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Write a short launch checklist" }],
  extra_body: { routing_strategy: "free_smart" },
});

console.log(response.choices[0].message.content);

curl

curl https://api.getwaterfall.org/v1/chat/completions \
  -H "Authorization: Bearer wf-sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "routing_strategy": "free_smart",
    "messages": [
      {"role": "user", "content": "Write a short launch checklist"}
    ]
  }'

Routing strategies

Discover strategy IDs from the live registry

Strategy availability and status can change as evidence improves. ReadGET /api/v1/routing/strategiesor use the strategy browser instead of copying a static list from documentation.

Open live registry

Coding-agent CLI

The local waterfall entrypoint configures Claude Code or Codex with a Waterfall base URL and model. It references an environment variable for the API key; it never accepts or prints a secret argument.

Configuration is a dry-run unless you provide an explicit output file. An existing file is only replaced with --backup. Status reads measured model, strategy, cost, cache, and fallback evidence from request logs or a saved response.

# Preview first; this never writes a file or prints your secret.
./waterfall configure claude --model auto

# Write only to an explicit target. Existing files require --backup.
./waterfall configure codex --output ~/.codex/config.toml --backup

# Read actual route evidence for the latest request.
export WATERFALL_API_KEY=wf-sk-your-key
./waterfall status

x402 Payments

x402 lets software settle an individual paid request with USDC on Base. It is not a credit top-up: an x402-enabled client reads the HTTP 402 payment terms, pays, and retries that same request.

Non-crypto users can add card credits through Stripe Checkout. A successful card payment funds the registered API key that started checkout.

Free strategies stay free. Card-funded paid requests debit Waterfall's quoted request price; image generation settles against its provider-priced image cost.

# Send a normal paid request. An x402-enabled client pays the
# HTTP 402 USDC-on-Base terms and retries it; there is no prepaid top-up endpoint.
curl https://api.getwaterfall.org/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'

Privacy and Regulated Data

privacy_smart uses Zero Data Retention routes and direct-provider routes where available. That is useful for privacy-sensitive apps.

Zero Data Retention means prompt and response content should not be stored after the request is processed. It does not mean the request was never processed by a provider, and it does not automatically make the route HIPAA compliant or safe for privileged legal work.

BYOK credentials currently apply to non-streaming requests only. Streaming requests continue through eligible Waterfall shared credentials with normal Waterfall billing, even when you saved a provider key. Disable streaming when a request must use BYOK.

If you handle PHI, client secrets, or regulated data, you may need a BAA, DPA, approved subprocessors, audit logs, region controls, and retention controls. Use a covered direct-provider route for that work. Do not rely on a generic privacy route as your compliance plan.

Models

Waterfall keeps a live catalog of chat, reasoning, coding, vision, image, audio, embedding, rerank, safety, and moderation models. Use Models to inspect the current list and see which strategies each model belongs to.