Your tools.
Your way in.

01 / Passkeys & access keys

Your access. Your choice.

Gateway offers a passkey or an independent access key. No email is required. Start at account access.

Already have credit?

Use Add passkey to this account, or restore your existing access key before adding a passkey. This preserves your credit, points and receiving address. Creating a second account does not move your existing balance.

Which backup does what?

Suite membership, separate product boundaries. Use your Gateway account to manage ZOO Suite. ZOO Mail can connect to that membership after you approve a matching code. Linking shares membership status; it does not merge accounts, expose mailbox keys, or replace a wallet recovery phrase.

02 / Terminal quickstart

From key to first answer.

1 Create an API key and deposit address

Create a key-only account directly from your terminal. POST /v1/accounts returns your API key as token and your shielded ZEC deposit address as zcash_address. No email, browser account or passkey is required. You can add a passkey to the same account later.

Use Bash or Zsh with curl and jq installed. Run this once for a new account. It saves the response in a new private folder in your home directory, loads the key without printing it, and shows the deposit address. Keep shell tracing off.

export ZOO_BASE_URL='https://zooko.ai/v1'
umask 077
command -v jq >/dev/null &&
ZOO_ACCOUNT_DIR="$(mktemp -d "$HOME/.zoo-gateway.XXXXXX")" &&
export ZOO_ACCOUNT_FILE="$ZOO_ACCOUNT_DIR/account.json" &&
curl --fail-with-body --silent --show-error \
  --cookie "${ZOO_ACCESS_COOKIE_JAR:-/dev/null}" \
  --request POST "$ZOO_BASE_URL/accounts" \
  --output "$ZOO_ACCOUNT_FILE" &&
ZOO_API_KEY="$(jq -er '.token | strings | select(length > 0)' "$ZOO_ACCOUNT_FILE")" &&
export ZOO_API_KEY &&
printf 'Save this private account file: %s\n' "$ZOO_ACCOUNT_FILE" &&
jq -r '.zcash_address // "Address pending: check GET /v1/account with this same key."' "$ZOO_ACCOUNT_FILE"

Save the account file privately before paying. The API key is returned only at creation; anyone with it can spend your credit. This file contains an unencrypted account credential, not your wallet seed. Keep a secure backup outside your project folder. A new account has a separate balance; reuse your saved key if you already have credit.

If creation fails, stop and read the error before retrying. A network failure can occur after creation, so check whether your private response file contains a complete token first. Do not automatically retry account creation. A 429 means the enrollment limit was reached.

printf 'Gateway access key: '
read -r -s ZOO_API_KEY
printf '\n'
export ZOO_API_KEY
export ZOO_BASE_URL='https://zooko.ai/v1' 

curl --fail-with-body --silent --show-error \
  "${ZOO_BASE_URL%/v1}/cli/pair-passkey.mjs" \
  --output zoo-pair-passkey.mjs &&
node zoo-pair-passkey.mjs

2 Send ZEC and check your credit

Send shielded ZEC from your wallet to the returned zcash_address. You can retrieve that same address and check credit directly from the terminal:

curl --fail-with-body --silent --show-error "$ZOO_BASE_URL/account" \
  -H "Authorization: Bearer $ZOO_API_KEY" | jq '{
    deposit_address: .zcash.address,
    usd_per_zec: .zcash.usd_per_zec,
    available_units: .available,
    payment_status: .payment_status
  }' 

If the address is null, wait and repeat this GET request with the same key; do not create another account. Once you send ZEC, check periodically until the payment is credited and available_units is positive before using paid AI routes. Credit uses 6 decimal places: 1000000 units = $1. The live deposit rail is ZEC only, even if an API field uses the legacy internal accounting label USDT.

3 Try GPT-6 Sol

Start with OpenAI GPT-6 Sol using the exact Gateway model ID openai/gpt-6-sol. The cURL, Python and Node.js examples below all use this selection and your existing credit. To switch models, choose another enabled ID from the live catalog and update ZOO_MODEL.

export ZOO_MODEL='openai/gpt-6-sol'

curl --fail-with-body --silent --show-error "$ZOO_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ZOO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg model "$ZOO_MODEL" '{
    model: $model, max_tokens: 256,
    messages: [{role: "user", content: "Explain zero-knowledge proofs in three sentences."}]
  }')"

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["ZOO_BASE_URL"],
    api_key=os.environ["ZOO_API_KEY"],
    max_retries=0,
)
response = client.chat.completions.create(
    model=os.environ["ZOO_MODEL"],
    max_tokens=256,
    messages=[{"role": "user", "content": "Explain zero-knowledge proofs in three sentences."}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.ZOO_BASE_URL,
  apiKey: process.env.ZOO_API_KEY,
  maxRetries: 0,
});
const response = await client.chat.completions.create({
  model: process.env.ZOO_MODEL,
  max_tokens: 256,
  messages: [{ role: "user", content: "Explain zero-knowledge proofs in three sentences." }],
});
console.log(response.choices[0].message.content);

cURL recipes require curl and jq. Python: install with python3 -m pip install openai inside a virtual environment. Node.js: npm install openai, then save the example as an .mjs file. Each successful request spends credit. The SDK examples disable automatic retries so you can inspect ambiguous failures first.

When finished, run unset ZOO_API_KEY in that shell. This removes the environment variable; it does not revoke the key.

03 / Models & pricing

The catalog is the source of truth.

Use /v1/models for exact IDs, availability, context limits, modalities and route privacy. Catalog presence alone does not mean a model is enabled. No fixed model count is promised.

curl --fail-with-body --silent --show-error "$ZOO_BASE_URL/models" \
  | jq '.data[] | select(.zooko.available != false) | {
      id, name: .zooko.name, route: .zooko.provider,
      context: .zooko.context, output: .zooko.output_modalities,
      web: .zooko.supports_web, privacy: .zooko.privacy,
      input_usd_per_million: .zooko.usd_per_million_input,
      output_usd_per_million: .zooko.usd_per_million_output
    }'

curl --fail-with-body --silent --show-error "$ZOO_BASE_URL/info" \
  | jq '{rails, fee_bps, assets, points, passkeys}'

Catalog token rates are the upstream rates before the Gateway fee. fee_bps uses basis points: 1000 means 10%. The live setting was 10% at this review. Search, images, audio and reasoning can have additional usage costs; the final usage and zooko response fields report settlement.

max_tokens limits output, not your total dollar spend. It defaults to 1,024 or the lower server cap, and requests above that cap are clamped. Input, tool schemas, search and media can also cost money. The Gateway reserves credit before a call and settles after it; large requests can fail with 402 even when a smaller request would fit.

04 / Streaming & clients

Use your own workspace.

Clients need a custom OpenAI Chat Completions endpoint, base URL https://zooko.ai/v1, a Gateway access key, and an enabled model ID. ZOO does not require your personal model-provider API keys.

This is Chat Completions compatibility, not a promise that every OpenAI endpoint works. Responses, Assistants, embeddings, file uploads and standalone image/audio endpoints are not exposed by this Gateway.

curl --no-buffer --fail-with-body --silent --show-error \
  "$ZOO_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ZOO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg model "$ZOO_MODEL" '{
    model: $model, stream: true, max_tokens: 256,
    messages: [{role: "user", content: "Give me three privacy-friendly app ideas."}]
  }')"

The response is Server-Sent Events: read data: JSON chunks, assemble choices[].delta, and stop at [DONE]. The final successful chunk includes usage and zooko. A stream can return HTTP 200 and then an error event with finish_reason: "error"; check both.

An interrupted connection may miss the settlement event even when work was charged. Stopping a stream is not a guarantee of zero cost. Check the outcome before retrying. Never give an agent shell access to secrets beyond what its task needs.

05 / Tools & structured output

Let a model request a function.

On a supporting OpenAI-compatible route, the Gateway forwards tools, tool_choice, parallel_tool_calls and response_format. Support depends on the selected model and route. The current direct Anthropic adapter does not forward custom tool calls or structured-output options; choose an appropriate OpenAI-compatible route for these examples.

curl --fail-with-body --silent --show-error "$ZOO_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ZOO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg model "$ZOO_MODEL" '{
    model: $model, max_tokens: 256,
    messages: [{role: "user", content: "What block height does my local demo report?"}],
    tools: [{type: "function", function: {
      name: "get_demo_height", description: "Read a fictional local demo height.",
      parameters: {type: "object", properties: {}, additionalProperties: false}
    }}], tool_choice: "auto"
  }')"

1. Read choices[0].message.tool_calls. Validate the function name and parsed arguments against your allowlist.
2. Your application executes the approved function. The Gateway does not execute your shell, fetch chain data or run arbitrary tools for you.
3. Append the returned assistant message, then one role: "tool" message per call, with its tool_call_id and a string content result.
4. Send the updated messages to Chat Completions for the answer. Bound the number of tool rounds and request sizes; each model call can spend credit.

For supported structured-output models, add "response_format": {"type": "json_object"} and explicitly ask for JSON. Validate the response in your client. Tool output is untrusted data, not permission to perform another action.

06 / Images, audio & Web

More than text.

Use Chat Completions for these features. Choose a model with the matching capability first; a model that answers text is not necessarily an image or audio generator.

curl --fail-with-body --silent --show-error "$ZOO_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ZOO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg model "$ZOO_MODEL" '{
    model: $model, modalities: ["image"],
    image_config: {aspect_ratio: "1:1", image_size: "1K"},
    messages: [{role: "user", content: "A friendly illustrated monkey among green leaves."}]
  }')"

import base64
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(base_url=os.environ["ZOO_BASE_URL"],
                api_key=os.environ["ZOO_API_KEY"], max_retries=0)
data = base64.b64encode(Path("reference.png").read_bytes()).decode("ascii")
response = client.chat.completions.create(
    model=os.environ["ZOO_MODEL"], max_tokens=256,
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Describe this image."},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64," + data}},
    ]}],
)
print(response.choices[0].message.content)

{
  "modalities": ["text", "audio"],
  "audio": {"voice": "alloy", "format": "mp3"}
}

06B / Video Studio & API

Turn a still into a scene.

Video uses a separate, asynchronous API and the same prepaid Gateway account. First check /v1/info: video_generation.enabled must be true. Open Video Studio in your browser, or use the API and terminal helper below. In Video Studio, choose a model, optionally upload a first-frame image, describe the movement, review the maximum charge, then create. Your recent jobs stay attached to your Gateway account; prompts and images are not saved with them.

The browser accepts PNG, JPEG and WebP images up to 20 MB and 64 megapixels. Larger images are optimized on your device to fit the upload limit, preserving their proportions; the original file is unchanged. The API and terminal helper accept prepared images up to 1 MiB.

Supported routes include Seedance, Veo, Kling, Sora, Runway, Grok, MiniMax, Wan and HappyHorse, with audio generation disabled and an optional first-frame image where supported. Editing, upscaling and avatar models need separate workflows and are not included. Seedance uses a token-based reservation with a buffer; the actual receipt determines the final charge, capped at your approved maximum. The live catalog lists current supported models and settings. Image-to-video may follow the source image’s proportions rather than the requested aspect ratio; crop your image to the intended shape first. Read the current model catalog for valid settings. The helper requests a quote, checks your spending cap, submits once, reports progress and downloads the result. A five-second H3 Max clip at 480p was quoted at $0.275 including a 10% Gateway fee during integration; the live quote is authoritative.

curl --fail --silent --show-error \
  "$ZOO_BASE_URL/info" | jq '.video_generation'

curl --fail --silent --show-error \
  "$ZOO_BASE_URL/videos/models" | jq '.data[] | {id, supported_durations, supported_resolutions}'

# Download the helper for review; Node.js 22+ is required.
curl --fail --silent --show-error \
  "${ZOO_BASE_URL%/v1}/cli/video.mjs" --output zoo-video.mjs
node zoo-video.mjs --help

# Prepare prompt.txt and a PNG/JPEG/WebP image of at most 1 MiB.
# ZOO_API_KEY is the same account key used in the quickstart.
# This submits a PAID request after checking the quote against your cap.
node zoo-video.mjs \
  --prompt-file prompt.txt --image photo.png \
  --model minimax/hailuo-3-max \
  --duration 5 --resolution 480p --aspect-ratio 16:9 \
  --max-cost 0.60 --accept-temporary-retention \
  --state video-job.json --out video.mp4

Omit --image for text-to-video. Your cap is not a flat charge: the final provider receipt plus Gateway fee determines the debit, capped at the accepted quote. The unused reservation returns to available credit. New videos require paid credit; free trial credit does not apply.

# Resume polling or download again without paying for another generation.
node zoo-video.mjs --resume video-job.json --out video-resumed.mp4

Keep video-job.json. It contains the request identity, not your API key or prompt. If the terminal stops, resume that request instead of starting a second paid job. Download promptly: the provider keeps output temporarily, not as permanent storage. Existing output filenames are not overwritten.

07 / Credit, points & payments

Check the account before retrying.

Your receiving address, available credit, usage counters and recent payment observations are account-scoped.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ZOO_API_KEY" "$ZOO_BASE_URL/account" \
  | jq '{asset, credited, spent, available, calls, points,
         zcash, payment_status}'

credited, spent and available are decimal strings in the account asset’s base units. Match asset to /v1/info.assets for decimals and usd_per_unit. The current USD credit unit has six decimals: 9850000 means $9.85. Its legacy API symbol is USDT; that is an accounting label, not permission to deposit USDT. Check rails for funding availability. Keep exact arithmetic until display.

Responses report zooko.charged_units and zooko.remaining_units with the same asset units. Token counts are in usage. Account totals may include concurrent calls; a balance difference alone is not a receipt for one request.

payment_status.stale means last-known status, not proof of settlement or failure. retry_at is an estimate, not a reserved slot or a deadline. The scanner exposes up to 50 recent observations; they rebuild after restart while the durable credit ledger remains authoritative.

08 / Endpoint reference

Know which surface you are using.

Browser passkey ceremonies under /v1/passkeys/* require the configured browser origin and device approval. They are not a terminal password-login API. The legacy /v1/chat format remains for existing integrations; new integrations should use Chat Completions.

Pool receipt endpoints are disabled on the live ZEC-only service. Administrative routes, sale rehearsal and local test controls are not public customer APIs. Suite membership is managed at ZOO Suite. Standalone VPN checkout remains closed. Shared identity and chain-query candidates do not become live endpoints just because their code exists in a review branch.

09 / Errors & retries

Make the next step clear.

Read the response body as well as HTTP status. A failed connection is not proof that the server did no work. Chat Completions has no documented idempotency-key contract here: blindly replaying a paid request can create another charge. Do not log request headers, account keys or private prompts during diagnosis.

10 / History & backups

Account access is not chat storage.

Website history stays in your browser, encrypted at rest. Clearing site data erases it. Use Backup to keep an encrypted copy and save its passphrase. A passkey, recovery key or API access key does not contain those conversations or automatically sync them across devices.

For terminal and API applications, your own client decides whether to retain messages. Shell output, debug logging, saved response files and external client telemetry become part of your privacy boundary.

11 / Privacy boundaries

Know where your prompt goes.

The model host sees the prompt in plain text. Check its host and actual route label:

Only the second label restricts routing to no-retention providers. Video generation is a separate route with explicitly accepted temporary provider retention; neither of these chat labels overrides that notice. Web search may send a model-written query to a search provider. Shielded payment does not hide prompt contents from the model host; identity stripping does not remove identifying information you put in your prompt.

12 / Wallet & Zcash

Private money for your model credit.

ZOO Wallet is a shielded Zcash wallet for Chrome, currently under review in the Chrome Web Store. The verified installation link will appear on the Wallet page after approval. Until then, use another compatible shielded wallet.

1. Create or restore your wallet and store its recovery phrase privately.
2. Obtain ZEC through a service available in your region, then move it to a shielded balance.
3. Use the terminal quickstart or open Add credit in Gateway to get your account’s deposit address, then send shielded ZEC to it. Check confirmation progress before making another payment.

Wallet custody is independent of a ZOO account. A Gateway passkey cannot recover a wallet phrase. Shielding protects on-chain payment information, not all network metadata. See the Wallet’s storage and network boundaries.

13 / ZOO Suite

One annual package. Clear availability.

$179 for one calendar year, including $60 in AI model credit, 5 GB of ZOO Mail storage and ZOO VPN access. One payment, with no automatic renewal. Review the Suite and current checkout availability.

Sign in to your existing Gateway account, add any needed credit with shielded ZEC, then return to Suite to review and confirm the annual purchase. Funding your account alone does not buy a membership. Included AI credit is used before paid credit, cannot pay for the Suite, and is retained if unused after the membership ends.

Suite access lasts one calendar year; included AI credit is retained until used. Gateway credit can also be purchased separately, and ZOO Wallet does not require a Suite subscription. Product subscriptions, usage credit, points and any future token allocation remain different things. Review the current package and payment details on the Suite page before purchasing. AI usage is metered against your credit, with optional top-ups.

14 / Ask the Chain

From a question to inspectable evidence.

Ask the Chain is being developed around bounded, read-only indexer tools: a question, a supported query, source records, exact calculations and an explanation. The current review build uses scripted fixtures; live ZOO indexer access is not enabled on the public Gateway API.

Question → supported query → records → calculation → explanation

Evidence to inspect:
  network and indexed interval
  block height or range and freshness
  source records and coverage gaps

Robinhood Chain and Zcash are the initial intended coverage. Endpoint names, live schema, coverage and limits still need release validation. Shielded Zcash data cannot be exposed just by connecting an LLM. Follow the delivery gates.