⁠Integration Guidelines

Overview

This document provides comprehensive guidelines for integrating with the Nedal AI platform. Whether you're building applications, extending functionality, or connecting services, these guidelines ensure smooth integration while maintaining security and performance standards.

API Integration

REST API

// Base URL
const API_BASE = 'https://api.nedal.ai/v1';

// Authentication
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};

// Example Request
async function createAgent(config) {
  const response = await fetch(`${API_BASE}/agents`, {
    method: 'POST',
    headers,
    body: JSON.stringify(config)
  });
  return response.json();
}

GraphQL API

# Example Query
query GetAgentStatus {
  agent(id: "agent_id") {
    status
    currentTask
    performance {
      cpuUsage
      memoryUsage
    }
  }
}

Smart Contract Integration

Contract Interfaces

interface INedalAgent {
    function deploy(bytes32 configHash) external returns (uint256 agentId);
    function configure(uint256 agentId, bytes calldata config) external;
    function execute(uint256 agentId, bytes calldata input) external returns (bytes memory);
}

Event Handling

event AgentDeployed(uint256 indexed agentId, address indexed owner);
event TaskCompleted(uint256 indexed agentId, bytes32 indexed taskId);

SDK Integration

JavaScript/TypeScript

import { NedalAI } from '@nedal/sdk';

const nedal = new NedalAI({
  apiKey: 'YOUR_API_KEY',
  environment: 'production'
});

// Initialize agent
const agent = await nedal.createAgent({
  type: 'trading',
  config: {
    strategy: 'momentum',
    risk_level: 'moderate'
  }
});

Python

from nedal_ai import NedalAI

client = NedalAI(
    api_key='YOUR_API_KEY',
    environment='production'
)

# Deploy agent
agent = client.agents.create(
    type='content_creator',
    config={
        'language': 'en',
        'tone': 'professional'
    }
)

Webhook Integration

Configuration

{
  "webhook_url": "https://your-app.com/webhook",
  "events": ["agent.deployed", "task.completed"],
  "secret": "your_webhook_secret"
}

Event Format

{
  "event_type": "agent.deployed",
  "timestamp": "2024-01-09T12:00:00Z",
  "data": {
    "agent_id": "ag_123",
    "status": "active",
    "configuration": {}
  },
  "signature": "..."
}

Authentication Methods

API Key Authentication

• Generate API keys in dashboard

• Include in Authorization header

• Rotate keys periodically

• Implement key scoping

OAuth2 Flow

1. Client registration

2. Authorization request

3. Token exchange

4. Access token usage

Rate Limiting

Limits

• 1000 requests/minute for standard tier

• 5000 requests/minute for premium tier

• Custom limits for enterprise

Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704819600

Error Handling

Error Codes

{
  "error": {
    "code": "insufficient_resources",
    "message": "Agent deployment failed due to insufficient resources",
    "details": {
      "required": "4GB",
      "available": "2GB"
    }
  }
}

Error Categories

• Authentication errors (401, 403)

• Validation errors (400)

• Resource errors (404)

• System errors (500)

Best Practices

Security

1. Store API keys securely

2. Implement retry with backoff

3. Validate webhook signatures

4. Monitor API usage

Performance

1. Use connection pooling

2. Implement caching

3. Batch requests when possible

4. Handle rate limits gracefully

Testing & Development

Environments

• Sandbox: https://sandbox.api.nedal.ai

• Staging: https://staging.api.nedal.ai

• Production: https://api.nedal.ai

Test Credentials

{
  "api_key": "test_key_123",
  "webhook_secret": "test_secret_456"
}

Support & Resources

Documentation

• API Reference

• SDK Guides

• Example Projects

• Integration Tutorials

Support Channels

• Developer Forum

• Discord Community

• Email Support

• Office Hours

These integration guidelines provide a comprehensive framework for building with Nedal AI while ensuring security, performance, and reliability.