ZZanoraDocs

Get paid

The problems sellers run into most, what causes each one, and the fix.

Buyers can't find my capability ({"results":[]})

You're almost certainly not verified yet. Unverified sellers are hidden from discovery completely. Check with GET /v1/providers/:id, or zanora_provider_status, and request verification. If you're verified, check that the capability is active and that your description matches what buyers search for.

Buyers get INVOKE_FAILED — fetch failed

Your URL isn't reachable from where their agent runs. Zanora never calls your server; the buyer's agent does. A localhost or private-network URL can't be bought by anyone else. Deploy it publicly, or use a tunnel (ngrok http 4024) and publish that URL. Nothing is charged when this happens.

My endpoint returns 402 forever, or complete fails with PROVIDER_NOT_FOUND

The middleware's gateway (HttpBackend's gatewayUrl, or ZANORA_GATEWAY_URL) isn't the gateway the capability was published on. Settlement follows the capabilityId the middleware was given. Both default to https://api.zanora.dev, so check for a leftover override from local testing.

My endpoint serves calls for free

The route isn't behind the middleware. Publishing a capability doesn't make a URL charge; zanora(...) or paid(...) does.

zanoraSeller() refuses my key, or can't find my capability

Use a provider key in ZANORA_API_KEY: a buyer's workspace key can't publish. The gateway defaults to https://api.zanora.dev. If ZANORA_GATEWAY_URL is set, for example left over from local testing, check it points where you meant.

sell() reports a price I didn't pass

That's intended. It reports the stored price, and changed lists what it just updated to match your code. If the two differ after a restart, the listing had drifted from your source and has been corrected.

VALIDATION_FAILED when publishing
  • priceMinor must be a string of cents: "100", not 100.
  • protocol must be "rest" or "mcp", and category is required.
  • mcp needs toolName, and rest must not have one.
  • Give exactly one of endpoint or address.
  • A package address must pin an exact version in both version and the command line.
Buyers were refunded and I wasn't paid

Your handler threw, responded with an error status (4xx or 5xx), or returned an MCP result with isError: true, so the call failed and the buyer was refunded. Three of your own failures in a row (a 5xx, a throw, an isError result or a timeout) pause you for that buyer's wallet (WALLET_PROVIDER_PAUSED). A 4xx is refunded but doesn't count toward the pause. Check your logs for the transactionId in the failed receipt.

The receipt's responseHash doesn't match for buyers

Something changed the response after the middleware hashed it: a proxy that rewrites bodies, or middleware that adds fields afterwards. For MCP, return structuredContent, which is what the hash covers.

A payout says DESTINATION_COOLING_DOWN

You changed your payout destination within the last 24 hours. It lifts on its own. See Earnings and payouts.

Still stuck?

Check GET /v1/whoami first. Then email support@zanora.dev with your prv_… id and the errorId, transactionId or capabilityId involved. Never send your API key.