# 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](/nc/neurochainai-guides/api-reference/protobuf.md)

Protocol Buffer message and service definitions:

* Complete `.proto` file documentation
* Message type reference
* Service definitions

### [Gateway gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/gateway-grpc.md)

Gateway gRPC service documentation:

* `GatewayClientService` - Client-facing RPCs
* `GatewayComputeService` - Compute node RPCs
* Request/Response formats
* Error handling

### [Registry gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/registry-grpc.md)

P2P Registry gRPC service documentation:

* `P2PRegistryService` - All registry RPCs
* Node management
* Validation RPCs
* Subnet management

### [HTTP Endpoints](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/http-endpoints.md)

Gateway HTTP REST API:

* Inference endpoints
* Status endpoints
* Health checks

### [WebSocket Events](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/websocket-events.md)

Gateway WebSocket API:

* Connection management
* Event types
* Subscription patterns

### [Error Codes](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/error-codes.md)

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)

```protobuf
// 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)

```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:**

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

### Subscribe to Updates (WebSocket)

```javascript
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:

```http
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

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

***

## Versioning

### API Version

Current version: **v1**

### Version Header

```http
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

```bash
# 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)

```bash
# 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)

```bash
# 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)

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

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

***

## Next Steps

* [Protobuf Definitions](/nc/neurochainai-guides/api-reference/protobuf.md) - Complete proto documentation
* [Gateway gRPC API](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/gateway-grpc.md) - Gateway RPC reference
* [HTTP Endpoints](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/http-endpoints.md) - REST API reference
* [Error Codes](https://github.com/NeuroChainAi/docs-guides/blob/main/api-reference/error-codes.md) - Error handling


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.neurochain.ai/nc/neurochainai-guides/api-reference/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.