Zaira API Overview

Zaira is Bakkt's conversational AI agent designed to help you interact with the Bakkt platform using natural language. Whether you're onboarding users, processing payments, or managing crypto transactions, Zaira provides intelligent assistance to streamline your operations.

Natural Language Queries - Ask questions in plain English and get instant answers
Guided Operations - Get step-by-step guidance for complex workflows like KYC verification or payment processing
Customer Support - Provide intelligent, context-aware support to your users
API Automation - Execute API operations through conversational commands without writing code

Capabilities

Feature	Description
User onboarding	Account creation through conversation
KYC verification	Identity verification, document collection, compliance checks
Beneficiary management	Add and manage transfer recipients
Money transfers	International remittances with multi-currency support
Account operations	Balances, transaction history, settings

Under the hood, Zaira coordinates a swarm of specialized AI agents. Each handles a specific domain (transfers, compliance, user management). You send a message, the right agents work together to deliver the result.

How It Works

Zaira uses an asynchronous execution model:

Submit a Prompt: Send your question or request to Zaira
Receive Execution ID: Get a unique identifier to track your request
Poll for Results: Check the status until your request is processed
Get Response: Retrieve Zaira's answer and any suggested actions

Endpoints

Base URL: https://zaira.dtr.org/webhook

Endpoint	Description
`POST /initiate`	Create a user, returns `user_uuid`
`POST /ask`	Send a message, get an execution ID
`POST /ask/stream`	Send a message, stream the response
`POST /check-execution`	Poll for a response
`GET /sessions`	Fetch session history
`GET /info`	Get client info
`/webhooks`	Manage webhook endpoints
`GET /health`	Health check

Basic Flow

Call /initiate to create a user
Send messages with /ask or /ask/stream
Get responses via polling, streaming, or webhooks

Zaira maintains session context across requests.

Use Cases

Customer Support Automation

Deploy Zaira as a first-line support agent to handle common customer inquiries:

curl -X POST https://zaira.dtr.org/webhook/ask \
  -H "x-api-key: your_api_key" \
  -H "x-user-uuid: customer_uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "support_session_123",
    "message": "How do I verify my identity?"
  }'

Account Management

Users can check balances, review transactions, and manage their accounts:

curl -X POST https://zaira.dtr.org/webhook/ask \
  -H "x-api-key: your_api_key" \
  -H "x-user-uuid: user_uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "account_session_456",
    "message": "What is my current balance?"
  }'

Money Transfers

Send international remittances through conversational commands:

curl -X POST https://zaira.dtr.org/webhook/ask \
  -H "x-api-key: your_api_key" \
  -H "x-user-uuid: user_uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "transfer_session_789",
    "message": "I want to send 500 USD to my brother in Mexico"
  }'

Transaction History

Users can query their transaction status and history:

curl -X POST https://zaira.dtr.org/webhook/ask \
  -H "x-api-key: your_api_key" \
  -H "x-user-uuid: user_uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "history_session",
    "message": "Show me my recent transactions"
  }'

Session Management

Zaira supports session-based conversations for context-aware interactions. Use the session_id parameter to maintain conversation history:

Start a Session: Send your first prompt with an empty or new session_id
Continue Conversation: Use the same session_id in subsequent requests
Reference Previous Messages: Zaira remembers earlier parts of the conversation

Example Multi-Turn Conversation:

// First message
{
  "session_id": "conv_789",
  "message": "I need to onboard a new user"
}

// Follow-up message (same session)
{
  "session_id": "conv_789",
  "message": "Make them a corporate user instead"
}
// Zaira understands you're still talking about the same user

Input Modes

Text Prompts

Send text-based questions and commands (most common):

POST /webhook/ask
x-api-key: your_api_key
x-user-uuid: user_uuid
Content-Type: application/json

{
  "session_id": "session_123",
  "message": "What can you help me with?"
}

Binary/File Input

Upload images or audio files for analysis using multipart form data:

POST /webhook/ask
x-api-key: your_api_key
x-user-uuid: user_uuid
Content-Type: multipart/form-data

session_id: session_123
file: [binary file]
message: (optional) "send 100 USD to attached bank account"

Supported File Types: Images (PNG, JPG), Documents (PDF), Audio (MP3, WAV). Maximum file size: 10MB.

Response Structure

Successful Response

{
  "executionId": "773e183b-512f-4b12-ae7e-52361d903a6e",
  "status": "completed",
  "result": {
    "response": "I can help you with user onboarding, payment processing, transaction monitoring, and API integration guidance.",
    "actions": [
      {
        "type": "suggestion",
        "description": "Would you like me to guide you through onboarding a new user?"
      }
    ]
  }
}

Failed Response

{
  "executionId": "773e183b-512f-4b12-ae7e-52361d903a6e",
  "status": "failed",
  "error": {
    "code": "PROCESSING_ERROR",
    "message": "Unable to process the prompt. Please try again."
  }
}

Polling Best Practices

When polling for execution status:

Practice	Recommendation
Polling Interval	Start with 2-3 second intervals. Most responses complete within 5-10 seconds.
Timeout Strategy	Set a maximum timeout of 60 seconds. If no response, handle gracefully.
Error Handling	Check for `failed` status and handle errors appropriately.
Rate Limiting	Respect rate limits. Use exponential backoff if you receive 429 errors.

Rate Limits

Endpoint	Limit
`POST /webhook/ask`	10 per minute
`POST /webhook/ask/stream`	10 per minute
`POST /webhook/check-execution`	30 per minute

Examples

Basic Question

curl -X POST https://zaira.dtr.org/webhook/ask \
  -H "x-api-key: your_api_key" \
  -H "x-user-uuid: your_user_uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session_123",
    "message": "What services do you offer?"
  }'

const response = await fetch('https://zaira.dtr.org/webhook/ask', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key',
    'x-user-uuid': 'your_user_uuid',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    session_id: "session_123",
    message: "What services do you offer?"
  })
});

const { executionId } = await response.json();

import requests

response = requests.post(
    'https://zaira.dtr.org/webhook/ask',
    headers={
        'x-api-key': 'your_api_key',
        'x-user-uuid': 'your_user_uuid',
        'Content-Type': 'application/json'
    },
    json={
        'session_id': 'session_123',
        'message': 'What services do you offer?'
    }
)

execution_id = response.json()['executionId']

Check Execution Status

curl -X POST https://zaira.dtr.org/webhook/check-execution \
  -H "x-api-key: your_api_key" \
  -H "x-user-uuid: your_user_uuid" \
  -H "Content-Type: application/json" \
  -d '{
    "executionId": "773e183b-512f-4b12-ae7e-52361d903a6e"
  }'

Getting Started

Request your API key from [email protected]
Add x-api-key header to all requests
Call /initiate to create your first user
Start sending messages with /ask

Keep your API key secure and never expose it in client-side code.

Support

Need help with Zaira?

Email: [email protected]