EU AI Act Article 50 — 20 days to seal |
Get passport
🔧 Technical Integration Guide
REST API, WebSocket events, Python SDK, A2A Agent Card, MCP protocol. Everything a developer needs to integrate DEFONEOS into existing defence systems.
300+MCP Tools
Full JSON-RPC tool surface. Every DEFONEOS capability is an MCP tool.
JSON-RPCProtocol
Standard MCP over HTTP/SSE. Compatible with Claude, GPT, Gemini, any MCP client.
Ed25519SIGIL Signing
Every API call is hash-chained and Ed25519-signed. Immutable audit trail.
🌐 REST API
📡 WebSocket
🐍 Python SDK
🤖 A2A Protocol
📋 API Reference
🌐 REST API — JSON-RPC over HTTP
The DEFONEOS API uses JSON-RPC 2.0 over HTTP POST. The endpoint is /mcp on the sovereign substrate (default port 3101).
Health Check
curl -X POST http://localhost:3101/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
→ {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18",
"serverInfo":{"name":"defoneos","version":"1.0.0"}}}
List Available Tools
curl -X POST http://localhost:3101/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
→ {"tools":[{"name":"sigil_emit","description":"Emit SIGIL to audit chain"},
{"name":"bft_vote","description":"Cast BFT council vote"},
{"name":"swarm_launch","description":"Launch drone swarm"},
... 300+ tools]
Call a Tool — Emit SIGIL
curl -X POST http://localhost:3101/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
"params":{"name":"sigil_emit",
"arguments":{"line":"C|defoneos|test|Integration test"}}}'
→ {"digest":"a3f7b2e1...","signature":"Ed25519:...","prev_hash":"8c4f..."}
Authentication
API key passed via X-API-Key header. Keys issued via dorado_api_auth tool. Tier-based rate limits:
| Tier | Rate Limit | Tools Available | Cost |
|---|
| Free | 100 req/day | Read-only tools | £0 |
| Pro | 10K req/day | All tools + BFT | £499/mo |
| Governance | Unlimited | All + council + audit | £2,499/mo |
| Enterprise | Unlimited + SLA | All + multi-region + PQC | £9,999+/mo |
📡 WebSocket Events — Real-time Stream
DEFONEOS pushes real-time events over WebSocket. Subscribe to channels for live updates: SIGIL emissions, BFT votes, swarm status, sensor alerts, ISR detections.
Connect & Subscribe
wscat -c ws://localhost:3101/ws
# Subscribe to channels
> {"action":"subscribe","channel":"sigil"}
> {"action":"subscribe","channel":"bft"}
> {"action":"subscribe","channel":"swarm"}
> {"action":"subscribe","channel":"sensor"}
> {"action":"subscribe","channel":"isr"}
# Live events stream in:
< {"channel":"sigil","digest":"a3f7...","line":"C|swarm|launch|dragonfly-8"}
< {"channel":"bft","proposal":"engage-Alpha-7","vote":"for","agent":"agent-14"}
< {"channel":"swarm","mission":"msn-001","coverage":47,"drones_active":6}
< {"channel":"sensor","node":"bat-03","detection":"drone","bearing":142}
Available Channels
| Channel | Events | Use Case |
|---|
| sigil | All SIGIL emissions | Audit trail monitoring |
| bft | BFT proposals, votes, consensus | Governance dashboard |
| swarm | Drone launches, status, recalls | C2 real-time map |
| sensor | Batear detections, satellite passes, AIS | Sensor fusion feed |
| isr | YOLOv8 detections, target geolocation | ISR analyst terminal |
| council | Council proposals, deliberations | Decision tracking |
| audit | Compliance assertions, chain verification | Regulator view |
🐍 Python SDK
The defoneos Python package provides a typed wrapper around the MCP API. Install via pip.
Installation
pip install defoneos
Quick Start
from defoneos import DEFONEOS
# Connect to sovereign substrate
df = DEFONEOS(host="localhost", port=3101, api_key="dk_...")
# Emit a SIGIL
result = df.sigil_emit("C|test|hello|Hello from Python SDK")
print(f"Digest: {result.digest}")
print(f"Signature: {result.signature}")
# Launch swarm
mission = df.swarm_launch(pattern="dragonfly", n_drones=6, area="SE-1444")
print(f"Mission ID: {mission.mission_id}")
# Monitor
import time
while True:
status = df.swarm_status(mission_id=mission.mission_id)
print(f"Active: {status.active}, Coverage: {status.coverage}%")
if status.coverage >= 95:
df.swarm_recall(mission_id=mission.mission_id)
break
time.sleep(10)
# BFT vote
vote = df.bft_vote(proposal="recall-swarm", choice="for")
print(f"Consensus: {vote.consensus}, Votes: {vote.votes_for}/33")
Async Support
import asyncio
from defoneos import AsyncDEFONEOS
async def main():
df = AsyncDEFONEOS(host="localhost", port=3101)
# Subscribe to WebSocket events
async for event in df.subscribe("swarm"):
print(f"Swarm event: {event}")
if event.type == "mission_complete":
break
asyncio.run(main())
🤖 A2A (Agent-to-Agent) Protocol
DEFONEOS supports Google's A2A protocol for inter-agent communication. Other AI agents can discover DEFONEOS capabilities, submit tasks, and receive results asynchronously.
Agent Card Discovery
# Get DEFONEOS Agent Card (JSON-LD)
curl http://localhost:3101/.well-known/agent.json
→ {
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:csoai:defoneos",
"name": "DEFONEOS Sovereign Defence OS",
"description": "UK sovereign defence AI operating system",
"capabilities": ["sigil_emit","bft_vote","swarm_launch",...],
"skills": [
{"id":"eu-ai-act-compliance","name":"EU AI Act Compliance"},
{"id":"jsp936-audit","name":"JSP 936 Audit Generator"},
{"id":"isr-pipeline","name":"ISR Pipeline (YOLOv8+OpenAthena)"},
{"id":"swarm-coordination","name":"Drone Swarm Coordinator"}
],
"authentication": {"type":"api-key","header":"X-API-Key"}
}
Submit Task to DEFONEOS
# From another AI agent (e.g., Claude, GPT)
POST http://localhost:3101/a2a/tasks
{
"message": "Launch ISR mission over grid SE-1444-NW, report detections",
"skill_id": "isr-pipeline",
"arguments": {"area": "SE-1444-NW", "duration": 300}
}
→ {"task_id":"task-2026-0705-001","status":"submitted"}
# Poll for result
GET http://localhost:3101/a2a/tasks/task-2026-0705-001
→ {"status":"completed","result":{"detections":3,"targets":[...]}}
Federation Topology
| Protocol | Use | Status |
|---|
| A2A (Google) | Agent-to-agent task delegation | ✅ Live |
| MCP (Anthropic) | Tool calling | ✅ Live |
| SIGIL | Signed inter-agent messaging | ✅ Live |
| x402 (Coinbase) | Per-outcome payment | ✅ Live |
| DID (W3C) | Sovereign identity | ✅ Live |
| JWT | Session auth | ✅ Live |
| WebSocket | Real-time events | ✅ Live |
| gRPC | High-perf internal comms | 🔧 Planned |
📋 Full API Reference — Key Endpoints
| Endpoint | Method | Description |
|---|
| /mcp | POST | MCP JSON-RPC endpoint (all tools) |
| /ws | WS | WebSocket event stream |
| /.well-known/agent.json | GET | A2A Agent Card |
| /a2a/tasks | POST | Submit A2A task |
| /a2a/tasks/:id | GET | Get A2A task status |
| /v1/sigil/events | GET | Query SIGIL chain |
| /v1/sigil/stats | GET | SIGIL chain statistics |
| /v1/sigil/export | GET | Export SIGIL chain (CSV/JSON) |
| /v1/dorado/cust-report | GET | Customer audit report |
| /v1/dorado/replay | GET | Audit trail replay for regulators |
Rate Limiting
Rate limits applied per API key. Headers return quota:
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1720195200
Error Codes
| Code | Meaning |
|---|
| 200 | Success |
| 400 | Bad request (invalid params) |
| 401 | Unauthorized (missing/invalid API key) |
| 403 | Forbidden (tier insufficient for tool) |
| 429 | Rate limited |
| 500 | Internal error (SIGIL logged) |
DEFONEOS Technical Integration Guide · REST · WebSocket · Python SDK · A2A · MCP · UK Sovereign · CSOAI Certified · SIGIL-signed