# deploy.withzero.xyz — deploy a full Node app (backend + Postgres + frontend), paid in USDC

You (an agent) built a Node app that runs on localhost with a real database.
This capability HOSTS it: upload the source, pay a small hosting term in USDC,
and get back a live HTTPS URL with a dedicated Postgres. The app can then call
OTHER Zero capabilities (image gen, news, scraping, LLMs, on-chain, …) and pay
for them out of its own prepaid credits — no wallet ever lives inside the app.

This is a FULL Node runtime on Cloud Run: any npm package including native
modules, app.listen(process.env.PORT), a writable filesystem (ephemeral —
see RUNTIME CONTRACT), a normal
DATABASE_URL Postgres connection, backend + static frontend in one service.
(For edge-only apps — a bare fetch handler, no TCP, SQLite/D1 — use
app.withzero.ai instead. Use THIS when you have a normal Node app with a real
database, native deps, heavy compute, or you just don't want to rewrite it.)

If you discovered only one of the endpoints below, read this whole file: the
capability is the whole lifecycle, not a single call.

====================================================================
IDENTITY & PAYMENT MODEL (read first)
====================================================================
There is no signup. You arrive on one of two PURCHASING CHANNELS, and either
one identifies you and owns the apps you create:
  • DIRECT RAIL — your USDC wallet (MPP or x402; both prove the same wallet).
  • ZEROCLICK RAIL — buying through the ZeroClick marketplace, identified by
    your marketplace agent id.
Apps and credits are keyed to your buyer ACCOUNT, which either channel resolves
to. If you have used BOTH channels, link them (BUYER CHANNEL LINKING below) so
they reach the same apps. Responses to create/renew include billing_rail
("direct" | "zeroclick" | "key") telling you which rail the request rode, and a
replayed flag on idempotent replays.

There IS an optional API KEY, and it is neither a signup nor a third identity.
A buyer who has proved a WALLET can mint one (dpl_…), then send it as an
ordinary Authorization: Bearer instead of signing every request. The key acts
as the same buyer account that minted it, draws a prepaid ACCOUNT balance
instead of answering a 402 per call, and is revocable. Full lifecycle in
API KEYS below. Nothing else in this file needs one — if you already sign, you
can keep signing and ignore that section entirely.

Two kinds of money move, from two different mechanisms:

1) HOSTING TERM — on the DIRECT rail: a charge-intent (MPP/x402) on create +
   renew. A fixed fee buys one term (a fixed number of days). Dynamic-price
   route: you DECLARE the amount and it must equal the current rate.
     • Send header  X-Pay-Amount-Micros: <micro-USDC>  (1 USDC = 1_000_000 micros)
     • Send the SAME value in the JSON body field named for the route
       (term_fee_micros for create/renew, credit_micros for credits).
     • The 402 challenge is issued for exactly that amount; pay it with your
       wallet and retry. The server ENFORCES header == body == rate, so a wrong
       amount is a 4xx, never a silent over/under-charge.
   On the ZEROCLICK rail: for create/renew, OMIT term_fee_micros and the
   header — ZeroClick's app-terms usage ledger is authoritative and bills you
   there. Credits top-ups always use the direct charge mechanics above.
   With an API KEY: OMIT both as well. No 402 is issued; the current rate is
   drawn from your prepaid ACCOUNT balance and the response reports
   billing_rail: "key". Keyed create/renew instead require an Idempotency-Key
   header — see API KEYS.

2) PREPAID CREDITS — a balance you top up that funds your app's OUTBOUND calls
   to other Zero capabilities. Each outbound call reserves up to a max price,
   pays the sibling's real 402, and settles the actual cost against your
   credits (the remainder is released). This is how a hosted app pays for
   image/news/LLM/etc. without holding a key.
   This balance comes in TWO SCOPES and each app is permanently on exactly one:
   PER-APP credits (POST /api/v1/apps/:id/credits) for an app created by a
   signing buyer, or one shared ACCOUNT purse (POST /api/v1/credits) for an app
   created with an API key. GET /api/v1/apps/:id reports which, in "purse".
   See TWO BALANCES under API KEYS — do not guess, and do not assume they pool.

Owner-only routes (read/manage an app) take EITHER a signed PROOF of your
channel identity (wallet proof on the direct rail; marketplace identity on
ZeroClick) OR an API-key bearer — no funds move on either, but you must
establish that you are the buyer on record.

Authoritative pricing is always GET /api/v1/rates (below). Do not hardcode.

====================================================================
DISCOVERY (free, no auth)
====================================================================
- GET /api/v1/rates    → { termFeeMicros, buildFeeMicros, termDays,
                           perProxyCallMicros, creditsTopUpCapMicros }
                         all micro-USDC strings. Read this BEFORE any paid call
                         to size X-Pay-Amount-Micros.
- GET /openapi.json    → full request/response schemas for every route.
- GET /health          → liveness.

====================================================================
PACKAGING YOUR APP (the "source" field)
====================================================================
"source" is a base64-encoded ZIP of your app directory.

Rules the upload validator enforces AT ACCEPT (violations are an immediate
400 VALIDATION_ERROR, before any build starts):
- It must be a real ZIP archive (not tar/gz).
- package.json MUST be at the ARCHIVE ROOT — not nested in a subdirectory. A
  manifest at app/package.json is rejected (no_package_json). Zip the CONTENTS
  of your app dir, not the dir itself.
- Limits: <= 2000 files, <= 50 MiB total uncompressed. No absolute paths or ".."
  entries (path_traversal → rejected).
- SIZE OF THE UPLOAD ITSELF: keep the base64 "source" under ~10 MiB of zip.
  The hard ceiling is ~24 MiB (a 32 MiB request body), above which the request
  dies at the edge with a bare 413 that carries no error code from us. Between
  ~10 and ~24 MiB it will usually work but can fail under concurrent load.
  DO NOT put video, audio, model weights, datasets or large images in the zip
  — see LARGE FILES below, which has no practical size limit.
- package.json depending on sqlite3 / better-sqlite3 is rejected with
  400 { error: { code: "SQLITE_NOT_DURABLE" } }. The filesystem is EPHEMERAL
  (see RUNTIME CONTRACT) — a SQLite file WILL be lost on scale-to-zero, so use
  the injected DATABASE_URL Postgres for durable state. To deploy anyway
  (throwaway/demo data ONLY), pass ackEphemeral: true in the create/redeploy
  body. On create this fires BEFORE the 402 — you are never charged for it.

Rules that only fail LATER, at build time (the create is accepted and charged;
the app then lands in status "failed" — read /logs for why):
- package.json must have a "start" script, and a committed package-lock.json is
  how the build installs your exact deps.
- Do NOT include node_modules — it bloats the upload past the ~10 MiB practical
  limit above and the build ignores it anyway. The build runs Google Cloud
  Native Buildpacks (no Dockerfile needed): it auto-detects the Node app and
  installs deps from your lockfile. Native modules are supported.
- YOUR APP MUST ANSWER HTTP ON `/`. After deploying we fetch it, and the
  deploy only becomes "live" once it responds with a status below 500. Any
  status under 500 counts — 200, a redirect, even 404 — so an app that only
  serves /api/... is fine. What fails is an app that never answers: the classic
  cause is binding PORT and then crashing (e.g. throwing on a database
  connection at startup), which looks healthy to the platform but returns 500
  to every caller. Connect lazily, or retry, rather than throwing at boot.
  A create whose app never answers is marked "failed" and REFUNDED rather than
  billed for a dead app; a REDEPLOY that never answers leaves your existing
  live version untouched and running.

====================================================================
LARGE FILES — video, audio, model weights, datasets
====================================================================

Anything big goes into the app's durable /data volume, NOT into the source zip.
The bytes never pass through this API, so there is no meaningful size limit
(GCS accepts up to 5 TiB per object; your per-app storage cap applies).

Three steps:

1. Ask for an upload URL (free, owner-authenticated):

     POST /api/v1/apps/<appId>/assets
     { "path": "media/intro.mp4", "contentType": "video/mp4" }

   → { uploadUrl, method: "PUT", headers: {...}, dataPath, maxBytes, expiresAt }

2. PUT the raw bytes to uploadUrl, sending the returned `headers` EXACTLY as
   given. They are signed into the URL — change or drop one and GCS rejects the
   upload. Send the file raw: not multipart, not base64, no form encoding.

     curl -X PUT "$uploadUrl" \
       -H "content-type: video/mp4" \
       -H "x-goog-content-length-range: 0,10737418240" \
       --data-binary @intro.mp4

3. Read it from the running app at the returned `dataPath`, building the path
   from process.env.ZERO_DATA_DIR rather than hardcoding /data:

     const file = process.env.ZERO_DATA_DIR + "/media/intro.mp4";

Notes that will otherwise cost you an hour:
- The /data mount caches metadata for about a minute. A file you just PUT can
  take up to ~60s to appear to the running app. This is normal; retry rather
  than re-uploading.
- Re-PUT the same path to replace a file. There is no separate update call.
- The URL expires (default 15 min, max 60). Mint a new one rather than reusing.
- You can upload BEFORE the app's first successful deploy — staging assets
  ahead of the code is fine, as long as the app exists.
- /data storage is metered nightly and is subject to a per-app cap. When an app
  goes over cap (or its balance goes negative) /data flips read-only and this
  route returns 409 until you free space or top up.

====================================================================
CREATE & FUND (paid — charge-intent; see PAYMENT MODEL #1)
====================================================================
- POST /api/v1/apps
    Body: { source: "<base64 zip; see PACKAGING>", term_fee_micros: "<rate>",
            env?: { KEY: "val", ... }, slug?: "<subdomain>",
            ackEphemeral?: true /* required iff package.json has a sqlite dep */ }
    Header: X-Pay-Amount-Micros: <rate>   (== term_fee_micros == termFeeMicros)
    (fee body field + header are DIRECT rail only — omit both via ZeroClick)
    → 202 { appId, slug, url: null, status: "building", billing_rail, replayed }
    Pays one hosting term and queues the build. url is null on accept — poll
    GET /api/v1/apps/:id for the real serving URL once it goes live.
    DATABASE_URL / PORT / ZERO_* are injected at deploy — do NOT set them in env.
    slug: omit it for a unique generated id (recommended); a custom slug must be
    globally unique. A taken slug is a 409 { error: { code: "SLUG_TAKEN" } }
    issued BEFORE the 402 — you are never charged for a slug conflict.

- POST /api/v1/apps/:id/renew
    Body: { term_fee_micros: "<rate>" }  + X-Pay-Amount-Micros header.
    Extends the term. If the app had lapsed to "paused", this also re-queues a
    deploy from its last source (response includes resumed:true).

- POST /api/v1/apps/:id/credits
    Body: { credit_micros: "<amount>" }  + X-Pay-Amount-Micros header.
    Buys prepaid credits for THIS APP's outbound Zero calls. Amount must be
    within [1, creditsTopUpCapMicros]. → { appId, creditsMicros } (new balance).
    An app that draws the shared ACCOUNT purse (created with an API key) is
    refused here — 400 { error: { code: "PURSE_IS_ACCOUNT",
    details: { top_up: "POST /api/v1/credits" } } }, before any 402 — rather
    than minting a second balance it could never spend. Fund the named route.

====================================================================
MANAGE (owner-proof or API key — no charge)
====================================================================
These routes require either a signed PROOF that you are the buyer who owns the
app (MPP proof intent on the direct rail; marketplace identity via ZeroClick —
no funds move either way) or an API-key bearer (API KEYS below). You do NOT
construct the proof by hand: standard Zero buyer tooling (the `zero` CLI / SDK)
answers the proof challenge automatically with your wallet, the same way it
answers a 402. Just call the route as yourself.

- GET    /api/v1/apps            list your apps.
- GET    /api/v1/apps/:id        one app's full state (poll this until live):
                                 { appId, slug, status, url|null, termExpiresAt|null (ISO-8601),
                                   creditsMicros (micro-USDC string, AVAILABLE balance net of
                                   in-flight outbound-call holds),
                                   purse ("app" | "account" — WHICH balance that number is,
                                   and therefore which route tops it up; see TWO BALANCES),
                                   keepWarm, logsUrl, createdAt }.
- POST   /api/v1/apps/:id/deployments  redeploy new source within the term.
                                 Body: { source: "<base64 zip>", env?: {...},
                                 ackEphemeral?: true (sqlite deps; see PACKAGING) }. → 202.
                                 Dedupes against an in-flight build; an idempotent
                                 replay returns the original deployment.
- GET    /api/v1/apps/:id/deployments  LIST this app's deployment history (NOT the
                                 redeploy route above — same path, different verb):
                                 newest first, paginated (?limit=&cursor=), each row
                                 { id, status, logsUrl, createdAt }.
- POST   /api/v1/apps/:id/rollback  roll back to a PRIOR deployment from that history.
                                 Body: { deploymentId: "<id from GET .../deployments>" }.
                                 → 202, same shape as redeploy. Redeploys that
                                 deployment's ALREADY-STORED source — no upload, no
                                 new charge. 404 if deploymentId isn't this app's;
                                 409 { code: "NO_ROLLBACK_SOURCE" } if it has none
                                 (e.g. failed before any source was stored).
- PATCH  /api/v1/apps/:id        update env / scale (applied on next deploy; see SCALE).
- GET    /api/v1/apps/:id/logs   tail build + runtime logs (build failures show here).
- DELETE /api/v1/apps/:id        tear down (app + Postgres + service). → 202; GET keeps
                                 answering with the pre-delete status until the worker
                                 finishes, then 404s. Poll until the 404.

SCALE (PATCH /api/v1/apps/:id { scale: {...} }): real Cloud Run knobs —
cpu <= "2", memory <= "1Gi", maxInstances 1..10 (all applied, clamped, on the
NEXT deploy) — plus keepWarm: true|false, applied IMMEDIATELY when live:
- keepWarm keeps ONE instance always warm (minInstances 1) instead of
  scale-to-zero, killing cold starts. Idle time bills from your PREPAID
  CREDITS at the idle rates in GET /api/v1/rates (~$0.23/day for the default
  cpu=1/512Mi shape). Enabling requires a minimum credit balance (else 402
  INSUFFICIENT_CREDITS with the required amount in details); it AUTO-DISABLES
  if your credits run out. Keep the balance funded.

METERED RUNTIME: beyond the flat term fee, your app's ACTUAL compute
(vCPU-seconds, GiB-seconds, requests — measured hourly from Cloud Run) bills
from prepaid credits at the at-cost rates in GET /api/v1/rates, net of a
monthly per-app free allowance that covers light/demo traffic entirely. Quiet
apps pay ~nothing; busy apps pay what they use. If credits go NEGATIVE the
app keeps serving through a grace period (~72h) — top up to clear the debt,
or the app is paused (renew/top-up resumes it).

Polling: status transitions provisioning → building → deploying → live. Poll
GET /api/v1/apps/:id every ~3-5s; TERMINAL states are "live" (url is now set) and
"failed" (read /logs for why). "paused" = the term lapsed (renew to resume).
A typical build takes ~1-3 minutes.

====================================================================
API KEYS (optional — hold one bearer instead of signing every call)
====================================================================
Signing every request is fully supported and none of this is required. Mint a
key when you would rather hold a single long-lived token: it acts as the buyer
account that minted it, on the same routes, with the same ownership rules.

MINT / LIST / REVOKE (these three take a channel PROOF, never a key — holding a
key never lets you mint more keys or revoke your others):
- POST /api/v1/keys      Body: { name?: "<label>" }
    → { id, key, prefix, name, created_at }
    Requires a WALLET proof specifically. A ZeroClick-rail-only buyer gets
    403 { error: { code: "WALLET_PROOF_REQUIRED" } } — link a wallet first
    (BUYER CHANNEL LINKING below), then mint. Nothing is created by the refusal.
    "key" IS THE SECRET AND IS RETURNED EXACTLY ONCE. It is stored only as a
    SHA-256 hash, so no route, log line, or operator can ever show it again.
    Persist it the moment you read it. "id" (key_…) and "prefix" are public —
    safe to log, and how you name a key later.
    At most 10 LIVE keys per account → 409 { code: "KEY_LIMIT_REACHED" }
    (revoke one and retry).
- GET /api/v1/keys       → { keys: [{ id, name, prefix, last_used_at,
                             revoked_at, created_at }] } — never the secrets.
                           last_used_at is refreshed at most once a minute.
                           Revoked keys stay listed so an id in an old log line
                           is still resolvable.
- DELETE /api/v1/keys/:keyId  → { id, revoked_at }. Idempotent (a re-revoke
                           returns the original timestamp). A key id that is
                           not yours is 404 { code: "KEY_NOT_FOUND" }, never a
                           403 — this route is not an enumeration oracle.

USING IT:   Authorization: Bearer <the "key" value from the mint response>
            (it already begins with dpl_live_ in production and dpl_test_
             elsewhere — that marker is part of the secret; send it verbatim)

Accepted on all TEN app routes — create, renew, list, get, deployments
(redeploy), rollback, deployment history, update, logs, delete — and on GET
/api/v1/account. A keyed request skips the
402 and the proof challenge entirely and reaches the same handler under the
same rules: you still only see and touch apps owned by your account. A key that
is unknown or revoked is 401 { code: "KEY_INVALID" } on the very next call —
revocation is immediate, there is no cache to wait out. A bearer that is not
shaped like a key at all is not treated as one: it falls through to the route's
normal 402 / proof challenge, so send the secret exactly as issued.

  • Keyed CREATE and RENEW additionally REQUIRE an Idempotency-Key header (any
    unique string of yours, one per logical attempt; reuse it verbatim when you
    retry). With no payment credential on the request there is nothing else a
    retry could collide on, so this header is the ONLY thing standing between a
    network retry and a second app plus a second term fee. Omitting it is a
    400 VALIDATION_ERROR before any money moves. Redeploys, rollbacks, updates,
    reads and deletes need no such header — they buy nothing.
  • Omit term_fee_micros and X-Pay-Amount-Micros on a keyed create/renew.
  • Everything else is byte-identical to the signed call: same body, same
    response, same 202, same replayed flag — only billing_rail differs ("key").

THE ACCOUNT PURSE (what a keyed call spends):
- POST /api/v1/credits   Body: { credit_micros: "<amount>" }
                         + X-Pay-Amount-Micros header (same charge mechanics as
                         PAYMENT MODEL #1; within [1, creditsTopUpCapMicros])
    → { accountId, creditsMicros }. Funds the shared account balance.
    This route is PAID and deliberately does NOT accept a key: a key can SPEND
    this balance and can never CREATE it, so a leaked key costs you at most
    what you had already funded. Not available on the ZeroClick rail (nothing
    settles there) — link a wallet and fund on the direct rail.
- GET /api/v1/account    → { accountId, creditsMicros, openHoldsMicros,
                             availableMicros, liveApps, liveKeys, topUp }
    Where you stand, with no app id needed — the read for an agent running ten
    apps on one purse. creditsMicros MAY BE NEGATIVE: metered runtime and
    storage debits never block. availableMicros (stored minus open holds) is
    the number a new charge is checked against.
- When the purse cannot cover a call:
    402 { error: { code: "INSUFFICIENT_CREDITS",
                   details: { available_micros, requested_micros, top_up } } }
    The loop is: read details.top_up, fund THAT EXACT ROUTE, retry the call.
    top_up always names the route that refills the purse which refused you —
    do not hardcode one; an app-purse app and an account-purse app are refilled
    at different routes and each refuses the other's.

TWO BALANCES — this is real, it is permanent per app, and the API tells you:
  • An app created by a SIGNING buyer (wallet or ZeroClick) keeps its OWN
    prepaid credits, funded at POST /api/v1/apps/:id/credits.
  • An app created WITH A KEY draws the shared ACCOUNT purse, funded at
    POST /api/v1/credits. Its per-app column stays 0 forever, and
    POST /api/v1/apps/:id/credits refuses it with 400 PURSE_IS_ACCOUNT rather
    than mint a second balance the app could never spend.
  The purse is fixed when the app is created and never moves; the two never
  pool, and there is no transfer between them. One agent can hold both kinds at
  once — which is exactly why GET /api/v1/apps/:id returns purse ("app" |
  "account") and its creditsMicros is the balance of THAT purse. Read the
  field; do not infer it from how you happened to authenticate today.
  Cost of the account purse: every app on it, plus every sweep and every
  top-up, serializes on one row, so many apps making heavy concurrent outbound
  calls queue slightly more than they would on per-app credits.

LOSING A KEY COSTS YOU NOTHING. The wallet is the durable credential; keys are
disposable. If you lose the secret: sign once with your wallet, mint a new key,
and revoke the old id from GET /api/v1/keys. Your apps, your purse, your
account id and your history are untouched — they hang off the buyer account,
not off any key. Rotation is the same two moves (mint, switch, revoke); there
is no rotate route because it would do nothing those two do not.

DON'T CROSS THE BEARERS. dpl_… is YOUR credential on the control-plane routes
above. ZERO_APP_TOKEN is a DIFFERENT bearer that WE inject into your deployed
app for ITS outbound calls through ZERO_PROXY_URL / ZERO_LLM_URL (CALLING OTHER
ZERO CAPABILITIES below). They are not interchangeable and not a fallback for
each other: a dpl_ key sent to the proxy is 401 TOKEN_INVALID, and an app token
sent to a control-plane route is not recognised as a key at all and falls
through to the 402 / proof gate. Never put a dpl_ key inside a deployed app —
the app already has everything it needs to spend, and a key can create apps.

====================================================================
BUYER CHANNEL LINKING (one account across wallet + ZeroClick)
====================================================================
If you have bought on more than one channel (a direct-rail wallet AND through
ZeroClick), each channel starts as its own buyer account — apps created on one
are invisible to the other until YOU link them. Linking is buyer-initiated and
single-use; no platform discloses one channel's identifier to another.

- POST /api/v1/buyer/link-codes   (no body) on the channel you are
  authenticated on NOW → { code, expires_at, buyer_id }. Code lives 10 minutes,
  single use.
- POST /api/v1/buyer/links        { code } on the OTHER channel → merges that
  channel's account into the code's account: { linked: true, buyer_id, channel }.
  A 409 means the code expired (mint a fresh one and retry); a 400 means it was
  invalid or already used.

After linking, both channels resolve to one account: same apps, same credits.
Keys follow the account, not the channel: a key minted before a link keeps
working afterwards and reaches the merged account's apps and balance.

====================================================================
RUNTIME CONTRACT (what your app gets, and what it must not assume)
====================================================================
- process.env.PORT          — bind your HTTP server to it (required).
- process.env.DATABASE_URL  — a standard Postgres connection string into a
                              dedicated, empty schema. Run your own migrations
                              on boot. Persists across redeploys.
- process.env.ZERO_PROXY_URL, ZERO_LLM_URL, ZERO_APP_TOKEN — injected so your
  app can call other Zero capabilities (below). Never ship a wallet key.
- Any extra env you passed on create/update is injected too (KMS-encrypted at
  rest); injected creds always win over app-supplied keys of the same name.
- Reserved keys (PORT, DATABASE_URL, ZERO_*) you set in env are IGNORED (stripped
  at deploy), not an error — the injected values always apply.
- Your app scales to zero when idle and can run as multiple instances (up to
  maxInstances, default 3, PATCHable to 1..10), so make boot idempotent:
  CREATE TABLE IF NOT EXISTS / guarded migrations (two instances may boot at once).
- THE FILESYSTEM IS EPHEMERAL — EXCEPT process.env.ZERO_DATA_DIR (/data). The
  general filesystem is writable (in-memory) but every instance starts empty
  and dies with its contents — scale-to-zero means that can happen between any
  two requests. SQLite files, caches written outside /data WILL BE LOST.
- process.env.ZERO_DATA_DIR (/data) — DURABLE file storage backed by GCS,
  private to your app: files survive scale-to-zero, restarts, and redeploys.
  Use it for uploads, generated assets, and caches worth keeping. 1 GiB is
  included; overage bills NIGHTLY from your prepaid credits at cost
  (dataGibDayMicros in GET /api/v1/rates). At the hard cap (dataCapBytes,
  10 GiB) or when credits are exhausted the mount turns READ-ONLY — top up to
  restore write access, then prune. It is NOT a database substrate: it is a
  GCS FUSE mount with no POSIX locking, so SQLite on /data corrupts. Durable
  structured state belongs in DATABASE_URL (empty schema, all yours) — if your
  app uses better-sqlite3/SQLite today, point it at Postgres before deploying.

====================================================================
CALLING OTHER ZERO CAPABILITIES FROM YOUR APP (the differentiator)
====================================================================
Your app holds NO wallet. To call a marketplace capability, name the
capabilityId you found on Zero (`zero search`) and a price cap; the managed
proxy resolves the target URL server-side, pays the real x402/MPP 402 from the
managed escrow wallet, and DEBITS YOUR PREPAID CREDITS by the settled amount
(refunding the difference):

    POST ${ZERO_PROXY_URL}/<seg>/<path>           # ZERO_PROXY_URL already ends in /api/v1/_proxy
      Authorization: Bearer ${ZERO_APP_TOKEN}
      X-Capability-Id:    <capabilityId>          # presence routes to the PAID marketplace path
      X-Max-Price-Micros: <cap in micro-USDC>     # same unit as rates; a 402 above this aborts BEFORE signing
      Content-Type: application/json
      <the sibling's own request body>

    → the sibling's response, streamed back. Errors (JSON { error: { code } }):
      INSUFFICIENT_CREDITS(402), PRICE_CAP_EXCEEDED(402), PRICE_UNKNOWN(400),
      CAPABILITY_PROTOCOL_UNSUPPORTED(400), SIBLING_PAYMENT_FAILED(502),
      CAPABILITY_NOT_ALLOWED(403), TOKEN_INVALID(401).

HEADER NOTE — don't cross them: X-Max-Price-Micros is the OUTBOUND price cap (this
section only). X-Pay-Amount-Micros is ONLY for the paid lifecycle routes
(create/renew/credits). Wrong header on the wrong route → 4xx.
BEARER NOTE — two different bearers, and they are not interchangeable. The
Authorization: Bearer above is ${ZERO_APP_TOKEN}: minted by us, injected into
your app, and valid ONLY on this proxy (${ZERO_PROXY_URL} / ${ZERO_LLM_URL}).
An API key (dpl_…, API KEYS above) is YOUR credential and is valid ONLY on the
control-plane routes. Swapping them is a 401 either way (TOKEN_INVALID here;
a 402 or proof challenge there), and a dpl_ key does not belong inside a
deployed app at all.
RESPONSE: the sibling's body comes back with its HTTP status; a JSON body as
application/json, binary as application/octet-stream (the upstream Content-Type
is not preserved on the paid path — know your sibling's media type from its Zero
listing).

The URL needs a <seg>/<path> after the base, but on the PAID path they are
IGNORED for routing (the target is resolved from X-Capability-Id) — use a
readable placeholder like the capability's slug. Prefer the paid path: it works
for ANY marketplace capability.

Variants:
- First-party siblings: omit X-Capability-Id; then <seg> IS the sibling's name
  (<seg>.withzero.xyz) and the call rides internal trust — no marketplace
  payment happens, but it is NOT free to you: the advertised perProxyCallMicros
  (GET /api/v1/rates) is settled IN FULL against your credits per call. Only
  specific operator-allowlisted siblings work this way — when unsure, use the
  paid path.
- LLM: POST to ${ZERO_LLM_URL} (same bearer token) — a pre-wired shortcut to a
  chat-completions capability on the PAID marketplace path (OpenAI-compatible;
  send a normal chat body). You pay the model's REAL marketplace price from
  your prepaid credits, exactly as if you had called it with X-Capability-Id
  yourself. Optional X-Max-Price-Micros caps one call; without it a platform
  default ceiling (~$0.10) applies — premium models need an explicit cap from
  you. If a deployment has no LLM target configured you get 503
  { error: { code: 'LLM_NOT_CONFIGURED' } } before any credits are reserved —
  use the paid marketplace path above directly (any chat-completions
  capability found via zero search works through it).

Keep credits funded or outbound calls fail INSUFFICIENT_CREDITS — at
POST /api/v1/apps/:id/credits or POST /api/v1/credits depending on the app's
purse. The 402's details.top_up names the right one; GET /api/v1/apps/:id
tells you in advance.

Local dev before you deploy: there is no proxy until your app is hosted, so run
your app with your OWN wallet as the transport (the `zero` CLI / SDK) standing in
for the injected proxy — gate on whether ZERO_PROXY_URL is present. In production
the injected proxy + credits replace it, unchanged. See the examples/ apps.

====================================================================
END-TO-END (an agent shipping an app that uses Zero underneath)
====================================================================
1. GET /api/v1/rates                         → learn termFeeMicros, credits cap.
2. POST /api/v1/apps  { source, term_fee_micros }  + X-Pay-Amount-Micros
                                              → { appId, status:"building" }.
3. Poll GET /api/v1/apps/:id                 → until { status:"live", url }.
4. POST /api/v1/apps/:id/credits { credit_micros } + header  → fund outbound calls.
5. Your app serves at url and, when it needs live data/media/AI, calls
   ${ZERO_PROXY_URL} with X-Capability-Id + X-Max-Price-Micros — paid from the
   credits in step 4. Renew before term expiry; redeploy via /deployments.

Same loop holding an API KEY instead (one signature, then no more):
1. POST /api/v1/keys (wallet proof)          → save "key" — shown once, ever.
2. POST /api/v1/credits { credit_micros } + X-Pay-Amount-Micros (wallet proof;
   a key cannot fund itself)                 → the account purse is loaded.
3. POST /api/v1/apps { source } with Authorization: Bearer dpl_… AND an
   Idempotency-Key header, no fee field, no X-Pay-Amount-Micros
                                             → 202, billing_rail: "key".
4. Poll GET /api/v1/apps/:id with the same bearer → { status:"live", url,
   purse:"account" }. GET /api/v1/account shows the purse after the debit.
5. Outbound calls from the app spend that same account purse. On
   402 INSUFFICIENT_CREDITS, top up details.top_up and retry. Revoke the key
   at any time (DELETE /api/v1/keys/:keyId); the apps and money stay yours.

See /openapi.json for exact schemas, and https://github.com/piedotorg/withzero
capabilities/deploy/examples/ for runnable full-stack apps that use this exact
pattern: hello-pg (minimal runtime-contract smoke), zero-explorer (Zillow real
estate + history), postcard-studio (weather + AI image), morning-brief
(news + LLM), token-radar (live crypto time-series), crow-flies
(geocoding + distance), domain-watch (RDAP domain-expiry monitor).