> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dzap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Integration

> Integration artifacts and connection options for runtime agents.

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:

```json theme={null}
{
  "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:

```text theme={null}
RateLimit-Limit: 60
RateLimit-Remaining: 42
RateLimit-Reset: 1717117200
```

### Async job pattern

Long-running operations return `202 Accepted` with pollable status:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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]`:

```text theme={null}
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

* [MCP overview](/ai/mcp/overview)
* [Ask mode](/ai/cli/ask-mode)
* [SDK-AI](/ai/sdk-ai)