Documentation Index
Fetch the complete documentation index at: https://docs.zeroclick.am/llms.txt
Use this file to discover all available pages before exploring further.
Wallets
A wallet is your identity on ZAM. When you create an account, ZAM generates:
- Wallet address — your unique identifier on the platform
- API key — starts with
zam_, used to authenticate all API calls
- Recovery phrase — a 12-word mnemonic to recover your account
Account creation uses a proof-of-work challenge to prevent spam. You can create additional API keys with different scopes after your account exists.
Providers and listings
ZAM has two related concepts for sellers:
- A provider is the seller-side resource — it holds your service’s title, description, endpoint URL, schemas, and signing secret. You create and manage providers with
zam providers.
- A listing is the marketplace-facing view — it’s what buyers see and activate. ZAM automatically creates a listing when your provider passes review.
As a seller, you work with providers. As a buyer, you work with listings. The CLI reflects this: zam providers create (seller), zam activate LISTING_ID (buyer).
Provider states
When you create a provider, it goes through automated review before appearing on the marketplace:
pending_review → published → paused → archived
↗
paused ──┘
| State | Meaning |
|---|
pending_review | Automated review in progress (security, reachability, content). |
published | Live on the marketplace. Buyers can activate it. |
paused | Temporarily hidden. Can be republished. |
archived | Permanently retired. Terminal state. |
published providers appear in marketplace search results or accept activations.
Run contracts
A run contract defines how ZAM executes a listing. It contains:
| Field | Required | Description |
|---|
method | Yes | HTTP method (GET, POST, PUT, PATCH, DELETE) |
endpointPath | Yes | The URL ZAM calls when a buyer activates the listing |
inputSchema | No | JSON Schema describing the expected request body |
outputSchema | No | JSON Schema describing the response |
requestExampleJson | No | Example request for documentation |
responseExampleJson | No | Example response for documentation |
healthEndpoint | No | URL that ZAM probes periodically (GET, 2xx = healthy) |
inputSchema, ZAM validates the buyer’s request body against it before executing. Malformed input never reaches the seller’s endpoint.
Orders
An order records one activation of a listing. When a buyer activates a listing, ZAM:
- Validates the request body against the listing’s
inputSchema (if present).
- Creates an order in
pending state.
- Signs the request with HMAC (if the seller has a signing secret) and calls the seller’s endpoint.
- Updates the order to
completed (with the response) or failed (with the error).
pending → running → completed
→ failed
POST /v1/orders response contains the final result. Otherwise, it returns the order in pending state and the buyer polls for the result.
HMAC request signing
When ZAM calls a seller’s endpoint, it signs the request so the seller can verify it came from ZAM. Each request includes:
| Header | Contents |
|---|
X-ZAM-Payload | Base64-encoded envelope with version, timestamp, request ID, body hash, buyer/listing info |
X-ZAM-Signature | sha256= followed by an HMAC-SHA256 of the payload using the seller’s signing secret |
zam listings get-secret, zam listings rotate-secret) or the API. See Secure Your Service for verification examples.
Authentication
ZAM uses API key authentication. Pass the key in the x-zam-api-key header:
curl https://api.zeroclick.am/v1/listings \
-H "x-zam-api-key: zam_your_key_here"
Scopes
Each API key carries a set of scopes that control what it can do:
| Scope | Permission |
|---|
listing:create | Create listings |
listing:read | Read own listings |
listing:update | Update own listings |
listing:delete | Delete own listings |
provider:create | Create providers |
provider:read | Read own providers |
provider:update | Update own providers |
provider:delete | Delete own providers |
order:create | Activate listings (create orders) |
order:read | Read own orders |
api_key:create | Create new API keys |
api_key:read | List own API keys |
api_key:update | Update own API keys |
api_key:delete | Delete own API keys |
order:create and order:read.
Health checks
If a listing’s run contract includes a healthEndpoint, ZAM probes it periodically with a GET request. Health status is shown on the marketplace so buyers can see which services are operational before activating.
| Status | Meaning |
|---|
healthy | Health endpoint returned 2xx recently |
degraded | Health endpoint intermittently failing |
down | Health endpoint consistently failing |
unknown | No health endpoint configured, or not yet probed |
