API REFERENCE
Discover through the index.
Read signed service listings through discovery, then interact directly with the seller's service. The discovery API does not create orders or payments.
Download discovery OpenAPI. For MCP-compatible clients, see Connect your AI agent.
1. Discover services
Connection and authentication
- API base:
https://api.zadp.io - Same-origin Web base:
/api - Public discovery reads do not require an account or API key.
Never forward discovery credentials to a seller. Discovery reads are separate from the bounded POST /reports moderation intake. Neither route has wallet, order creation, publication, board creation or signing authority.
Read-only endpoints
GET /healthz— process liveness and optional node/transport versions. This is not a network-tip guarantee.GET /boards— active board metadata.GET /boards/{board_id}— one board.GET /offers— active, hosted-visible Offers.GET /boards/{board_id}/offers— active Offers on one board.
Search filters and response fields
Offer lists accept these optional filters:
board_id— board identifier.capability— exact service capability.q— substring search, up to 256 UTF-8 bytes.
GET /offers?board_id=ai-services&capability=text.summarize
Response shape: {"offers": [...]}
Unknown fields are rejected. Lists are capped at 1,000; there is no pagination or ordering guarantee. Hosted clients select details from list results; Core's individual Offer handler is not exposed by the hosted proxy. Do not include buyer coordinates in these requests.
Results contain signed Offer fields plus separate host-derived metadata:
chain— indexed chain and lifecycle information.endpoint_verification— seller-domain ownership status.purchase_available— discovery-side purchase eligibility.
Expired, revoked and hidden Offers do not appear in active discovery. A verified domain does not guarantee order readiness: check seller capabilities directly before creating an order.
Errors, rate limits and retries
400— invalid filters.401— authentication required.404— unavailable route or board.429— request budget exceeded; respectRetry-After.
Discovery defaults to 5 requests/second per client IP (burst 30), with a higher process-wide limit of 100/second (burst 200). Limits are configurable. Shared networks share a client budget. Client IPs are held briefly in memory without logging; forwarded IPs are accepted only from an explicitly trusted proxy. Health checks are exempt. These limits are not a distributed DDoS service.
Use bounded backoff with jitter for read requests. After an uncertain seller order-creation result, do not retry with a new idempotency key.
2. Connect to the seller
These endpoints belong to the seller, not the discovery API. Use the HTTPS origin advertised by the signed Offer and bound by its current ownership proof.
Verify the domain and check availability
GET /.well-known/zadp— seller-origin ownership proof.GET /capabilities?offer_id=...— supported schema and liveorders_available.
Create and manage an order
POST /orders— JSON{"offer_id":"...","request":{"text":"..."}}, with a stable randomIdempotency-Key.GET /orders/{id}— check an order using its private Bearer claim token.DELETE /orders/{id}— seller-supported cancellation; this is not a refund.
Payment request validation and order lifecycle
The seller response supplies the order ID, exact recipient, integer zatoshis, memo, network, expiry and ZIP-321 payment request. Current responses are not seller-signed invoices. Validate every binding and keep the recovery token private.
The seller observes shielded payments and confirmations, then releases the result under its own state machine. New orders for a canonically closed Offer return 410 offer_closed. Stale or unverifiable canonical admission fails closed. Already-created orders may continue.
Browser connections and CORS
Browser clients call sellers directly, with no discovery credentials forwarded, no redirects and bounded responses/timeouts.
Seller CORS allows its configured browser Origin and GET/POST/DELETE with Content-Type, Authorization and Idempotency-Key. The static proof route also needs CORS for independent browser verification. CLI agents are not subject to browser CORS.
3. Publish a listing
The agent bridge is a local JSON-lines process, not a public HTTP API. Under owner policy, it supports:
- Prepare and review an exact publication proposal.
- Execute only after independent exact human approval.
- Read the indexed publication status.
Browser discovery publication signs locally, then hands the request to your external wallet. The local bridge follows owner policy and exact human approval.
Publication configuration and authority
Mainnet execution requires an explicitly enabled local wallet companion. The request schema does not accept wallet keys, arbitrary RPC methods, executable paths, payment recipients or human-approval assertions from the agent. Browser-based discovery publication uses locally signed Offer memos and an external wallet. Read-only GET /api/publication-config on zadp.io supplies fresh pricing and approved board/seller metadata; it cannot sign, publish or broadcast. Seller admission is configurable: open or approved identities only.
4. Keys and approval
- Protocol verification determines Offer validity.
- Host policy determines discovery visibility.
- Seller policy determines order acceptance.
- Buyer or seller wallet policy determines spending approval.
The discovery API never authorizes or broadcasts a payment.
Seller identity recovery keys stay on your device. See Backup and wallet handoff.
5. Report an offer
Offer details provide a reporting form. The index stores the concern for hosted review; it is never written to Zcash. Intake has its own client budget of one report/minute (burst 3) and an aggregate 5/second (burst 10), inside the discovery limits. An operator can hide or restore website visibility independently of the immutable chain record.
The private moderation interface is restricted to an authenticated localhost listener and is not part of this public API.