Overview

Complete API documentation for NCN Network v2 services.

---

Overview

NCN Network exposes multiple API interfaces:

Interface	Protocol	Primary Use
Gateway gRPC	gRPC/Protobuf	Compute nodes, high-performance clients
Gateway HTTP	REST/JSON	Web clients, simple integrations
Gateway WebSocket	WebSocket	Real-time updates
Registry gRPC	gRPC/Protobuf	Gateways, validators

---

API Documentation

Protobuf Definitions

Protocol Buffer message and service definitions:

• Complete .proto file documentation

• Message type reference

• Service definitions

Gateway gRPC API

Gateway gRPC service documentation:

• GatewayClientService - Client-facing RPCs

• GatewayComputeService - Compute node RPCs

• Request/Response formats

• Error handling

Registry gRPC API

P2P Registry gRPC service documentation:

• P2PRegistryService - All registry RPCs

• Node management

• Validation RPCs

• Subnet management

HTTP Endpoints

Gateway HTTP REST API:

• Inference endpoints

• Status endpoints

• Health checks

WebSocket Events

Gateway WebSocket API:

• Connection management

• Event types

• Subscription patterns

Error Codes

Error code reference:

• gRPC status codes

• HTTP status codes

• Application-specific errors

---

Quick Reference

Gateway Endpoints

Protocol	Address	Purpose
gRPC	:50051	Compute nodes, gRPC clients
HTTP	:8080	REST API
WebSocket	:9000	Real-time updates

Registry Endpoints

Protocol	Address	Purpose
gRPC	:50050	All registry operations
P2P	:8828	Peer-to-peer networking

---

Common Patterns

Submit Inference Request (gRPC)

// Request
message InferenceRequest {
  string request_id = 1;
  string model_uuid = 2;
  string input_data = 3;
  string originator_client_id = 4;
}

// Response
message InferenceTaskStatus {
  string request_id = 1;
  string status = 2;        // "queued", "processing", "completed", "failed"
  string error_message = 3;
}

Submit Inference Request (HTTP)

POST /api/v1/inference HTTP/1.1
Host: gateway.example.com
Content-Type: application/json

{
  "model_uuid": "bark_semantic",
  "input_data": "{\"text\": \"Hello world\"}"
}

Response:

{
  "request_id": "req-abc123",
  "status": "queued"
}

Subscribe to Updates (WebSocket)

const ws = new WebSocket('wss://gateway.example.com/ws');

ws.send(JSON.stringify({
  type: 'subscribe',
  request_id: 'req-abc123'
}));

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Status:', data.status);
};

---

Authentication

Current Status

NCN Network v2 currently uses wallet-based authentication:

• Clients: Sign requests with wallet

• Compute Nodes: Authenticate via signature

• Validators: Sign validations with registered key

Future: API Keys

API key authentication is planned for HTTP endpoints:

Authorization: Bearer YOUR_API_KEY

---

Rate Limiting

Current Limits

Endpoint	Limit
HTTP Inference	100 req/min
gRPC Submit	1000 req/min
WebSocket	10 connections/IP

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067260

---

Versioning

API Version

Current version: v1

Version Header

X-API-Version: v1

Deprecation Policy

• Breaking changes require major version bump

• Deprecated endpoints marked in headers

• 6-month deprecation notice

---

SDK Support

Official SDKs

Language	Status	Repository
Rust	✅ Built-in	test_client
Python	🚧 Planned	-
JavaScript	🚧 Planned	-
Go	🚧 Planned	-

Generate Client Code

# Python gRPC client
python -m grpc_tools.protoc \
  -I./proto \
  --python_out=./client \
  --grpc_python_out=./client \
  proto/common_types.proto

# Go gRPC client
protoc \
  --go_out=./client \
  --go-grpc_out=./client \
  proto/common_types.proto

---

Testing APIs

gRPC Testing (grpcurl)

# List services
grpcurl -plaintext localhost:50051 list

# Call method
grpcurl -plaintext \
  -d '{"model_uuid": "test", "input_data": "{}"}' \
  localhost:50051 common_types.GatewayClientService/SubmitInferenceTask

HTTP Testing (curl)

# Submit inference
curl -X POST http://localhost:8080/api/v1/inference \
  -H "Content-Type: application/json" \
  -d '{"model_uuid": "test", "input_data": "{}"}'

# Check health
curl http://localhost:8080/health

WebSocket Testing (wscat)

# Connect
wscat -c ws://localhost:9000

# Send message
{"type": "subscribe", "request_id": "req-123"}

---

Next Steps

• Protobuf Definitions - Complete proto documentation

• Gateway gRPC API - Gateway RPC reference

• HTTP Endpoints - REST API reference

• Error Codes - Error handling