Skip to main content
DZap exposes machine-readable contracts and runtime transports tuned for autonomous agent workflows (retry safety, typed failures, streaming, and deterministic tool invocation).

​
Agent discovery and runtime surfaces

  • Docs corpus: https://docs.dzap.io/llms.txt, https://docs.dzap.io/llms-full.txt
  • OpenAPI contracts: https://docs.dzap.io/openapi.yaml, https://docs.dzap.io/tradeDocs.json, https://docs.dzap.io/zapDocs.json
  • MCP transport: POST|GET|DELETE /mcp
  • WebMCP discovery: /.well-known/mcp and /.well-known/mcp/server-card.json
  • NLWeb endpoint: POST /ask (+ SSE when prefer.streaming: true)
  • Markdown agent routes: /index.md, /api.md, /skill.md

​
API contracts for robust agents

​
Idempotency for mutations

Mutating endpoints accept Idempotency-Key so agents can retry safely:
  • POST /v1/buildTx
  • POST /v1/bundle
  • POST /v1/execute
  • POST /v1/batch
Use UUID-style keys and reuse the same key for retries of the same logical operation.

​
Typed error model

Non-2xx responses return structured JSON: 
{
  "status": "error",
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded",
  "requestId": "req_01J...",
  "retryAfter": 12,
  "details": {}
}

​
Versioning and deprecation

  • Versioned URL paths (/v1/..., future /v2/...)
  • Breaking changes only on major path bumps
  • Deprecations announced with migration notes and sunset windows before removal

​
Rate-limit headers

Every API response includes: 
RateLimit-Limit: 60
RateLimit-Remaining: 42
RateLimit-Reset: 1717117200

​
Async job pattern

Long-running operations return 202 Accepted with pollable status: 
{
  "status": "accepted",
  "jobId": "job_01J...",
  "statusUrl": "/v1/jobs/job_01J..."
}

​
Pagination, batching, and function-calling compatibility

  • List responses use cursor pagination (nextCursor) instead of page/offset.
  • Batch workflows use POST /v1/batch with typed per-item results.
  • Every OpenAPI operation has unique operationId, typed request/response schemas, and descriptions for tool/function calling.

​
NLWeb /ask contract

The natural-language endpoint supports both JSON and streaming responses. Request: 
{
  "query": "Bridge 100 USDC from Arbitrum to Base",
  "session_id": "agent-123",
  "prefer": { "streaming": true },
  "context": {
    "accountInfo": [{ "blockchain": "evm", "chain": "42161", "user_account": "0xabc..." }]
  }
}
Non-stream response includes _meta: 
{
  "_meta": { "response_type": "answer", "version": "1.0" },
  "output": { "text": "..." }
}
Streaming response (Content-Type: text/event-stream) emits start, result, and complete events.

​
MCP safety and error recovery

  • Invalid tool calls return JSON-RPC errors with both code and message.
  • Tool metadata includes behavioral annotations (readOnlyHint, destructiveHint) to support safe planning and confirmation flows.

​
SDK and CLI surfaces

  • Official SDK: @dzapio/sdk (npm)
  • Official AI runtime + CLI: @dzapio/ai (npm; dzap, dzapai, DzapAI)
  • Additional language SDKs are generated from OpenAPI and published per ecosystem release cadence.

​
Next

Last modified on May 30, 2026