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 (bearer-token gated when DZAP_MCP_HTTP_TOKEN is set)
  • Natural-language endpoint: POST /ask_stream (Server-Sent Events)

​
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.

​
/ask_stream contract

The natural-language endpoint streams over Server-Sent Events. Request: 
{
  "user_query": "Bridge 100 USDC from Arbitrum to Base",
  "session_id": "agent-123",
  "metadata": {
    "accountInfo": [{ "blockchain": "evm", "chain": "42161", "user_account": "0xabc..." }]
  }
}
Response (Content-Type: text/event-stream) emits one step event per tool call, a final finalText event, then [DONE]: 
data: {"chatId":"agent-123","response":{"type":"step","tool_name":"ZapCallDataGeneratorTool","data":"...","session_id":"agent-123"}}
data: {"chatId":"agent-123","response":{"type":"finalText","data":"...","session_id":"agent-123","chain_id":"42161"}}
data: [DONE]

​
MCP safety and error recovery

  • Invalid tool calls return JSON-RPC errors with both code and message.
  • Each tool is registered with a readOnlyHint annotation (false for the interactive execution tools) 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 June 18, 2026