Skip to main content

​
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 ──┘
StateMeaning
pending_reviewAutomated review in progress (security, reachability, content).
publishedLive on the marketplace. Buyers can activate it.
pausedTemporarily hidden. Can be republished.
archivedPermanently retired. Terminal state.
Only published providers appear in marketplace search results or accept activations.

​
Run contracts

A run contract defines how ZAM executes a listing. It contains:
FieldRequiredDescription
methodYesHTTP method (GET, POST, PUT, PATCH, DELETE)
endpointPathYesThe URL ZAM calls when a buyer activates the listing
inputSchemaNoJSON Schema describing the expected request body
outputSchemaNoJSON Schema describing the response
requestExampleJsonNoExample request for documentation
responseExampleJsonNoExample response for documentation
healthEndpointNoURL that ZAM probes periodically (GET, 2xx = healthy)
When a listing has an 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:
  1. Validates the request body against the listing’s inputSchema (if present).
  2. Creates an order in pending state.
  3. Signs the request with HMAC (if the seller has a signing secret) and calls the seller’s endpoint.
  4. Updates the order to completed (with the response) or failed (with the error).
pending → running → completed
                  → failed
If the seller’s endpoint responds within 50ms, the 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:
HeaderContents
X-ZAM-PayloadBase64-encoded envelope with version, timestamp, request ID, body hash, buyer/listing info
X-ZAM-Signaturesha256= followed by an HMAC-SHA256 of the payload using the seller’s signing secret
Sellers can generate and rotate signing secrets via the CLI (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"
Your first API key is created when you create your wallet. You can create additional keys with narrower scopes for different use cases.

​
Scopes

Each API key carries a set of scopes that control what it can do:
ScopePermission
listing:createCreate listings
listing:readRead own listings
listing:updateUpdate own listings
listing:deleteDelete own listings
provider:createCreate providers
provider:readRead own providers
provider:updateUpdate own providers
provider:deleteDelete own providers
order:createActivate listings (create orders)
order:readRead own orders
api_key:createCreate new API keys
api_key:readList own API keys
api_key:updateUpdate own API keys
api_key:deleteDelete own API keys
Grant the minimum scopes each key needs. A key that only activates listings needs 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.
StatusMeaning
healthyHealth endpoint returned 2xx recently
degradedHealth endpoint intermittently failing
downHealth endpoint consistently failing
unknownNo health endpoint configured, or not yet probed