> For the complete documentation index, see [llms.txt](https://docs.neurochain.ai/nc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neurochain.ai/nc/neurochainai-guides/api-reference/api-reference.md).

# 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