Client Integration

Guides for integrating applications with NCN Network.

---

Overview

NCN Network provides multiple interfaces for client integration:

Interface	Best For	Documentation
gRPC	High-performance, streaming	gRPC Guide
HTTP REST	Simple integrations, web apps	HTTP Guide
WebSocket	Real-time updates	WebSocket Events

---

Client Guides

gRPC Client

High-performance gRPC integration:

• Protobuf code generation

• Connection setup

• Request submission

• Streaming responses

HTTP Client

Simple REST API integration:

• Endpoint reference

• Request/response formats

• Error handling

Payment Integration

Blockchain payment flow:

• Wallet setup

• Payment submission

• Confirmation handling

Examples

Complete code examples:

• Python client

• JavaScript client

• Rust client

---

Quick Start

Simplest Integration (HTTP)

# Submit inference request
curl -X POST http://gateway.example.com/api/v1/inference \
  -H "Content-Type: application/json" \
  -d '{
    "model_uuid": "bark_semantic",
    "input_data": "{\"text\": \"Hello world\"}"
  }'

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

# Poll for result
curl http://gateway.example.com/api/v1/inference/req-abc123

With gRPC (Higher Performance)

import grpc
from common_types_pb2 import InferenceRequest
from common_types_pb2_grpc import GatewayClientServiceStub

# Connect
channel = grpc.insecure_channel('gateway.example.com:50051')
stub = GatewayClientServiceStub(channel)

# Submit request
request = InferenceRequest(
    model_uuid="bark_semantic",
    input_data='{"text": "Hello world"}'
)
status = stub.SubmitInferenceTask(request)
print(f"Request ID: {status.request_id}")

# Subscribe to results
for response in stub.SubscribeToTaskUpdates(RequestID(id=status.request_id)):
    print(f"Result: {response.output_data}")

---

Integration Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                         Client Integration Flow                              │
│                                                                             │
│   1. Setup                                                                  │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │ • Generate gRPC client code (if using gRPC)                         │   │
│   │ • Configure gateway endpoint                                         │   │
│   │ • Set up wallet (if using payments)                                  │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│   2. Submit Request                                                         │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │ • Prepare input data (JSON format)                                   │   │
│   │ • Specify model_uuid                                                 │   │
│   │ • Call SubmitInferenceTask / POST /api/v1/inference                  │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│   3. Handle Payment (if required)                                           │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │ • Receive payment info from status                                   │   │
│   │ • Submit blockchain transaction                                      │   │
│   │ • Confirm with gateway                                               │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│   4. Receive Result                                                         │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │ • Poll status endpoint, or                                           │   │
│   │ • Subscribe to gRPC stream, or                                       │   │
│   │ • Listen to WebSocket events                                         │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│   5. Process Result                                                         │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │ • Parse output_data (JSON)                                           │   │
│   │ • Verify signatures (optional)                                       │   │
│   │ • Handle errors                                                      │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Choosing an Interface

Use Case	Recommended	Reason
Web application	HTTP	Simple, CORS support
Backend service	gRPC	Performance, streaming
Real-time app	WebSocket	Live updates
Mobile app	HTTP	Wide library support
High-throughput	gRPC	Efficient binary protocol
Quick prototype	HTTP	No code generation needed

---

Input/Output Formats

Input Data

All input data is JSON-encoded:

{
  "text": "Hello world",
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 100
  }
}

Output Data

Output is also JSON-encoded:

{
  "tokens": [1, 2, 3, 4, 5],
  "metadata": {
    "inference_time_ms": 1250
  }
}

---

Error Handling

HTTP Errors

Status	Meaning	Action
400	Bad request	Check input format
404	Not found	Check request_id
429	Rate limited	Retry with backoff
500	Server error	Retry or report
503	Unavailable	Service down, retry later

gRPC Errors

Code	Meaning	Action
INVALID_ARGUMENT	Bad input	Check request format
NOT_FOUND	Unknown request	Check request_id
RESOURCE_EXHAUSTED	Rate limited	Retry with backoff
UNAVAILABLE	Service down	Retry with backoff
INTERNAL	Server error	Report issue

---

SDKs and Libraries

Available

Language	Status	Usage
Rust	✅ Built-in	test_client crate

Planned

Language	Status
Python	🚧 In progress
JavaScript	🚧 Planned
Go	🚧 Planned

Generate Your Own

# Python
pip install grpcio-tools
python -m grpc_tools.protoc -I./proto --python_out=. --grpc_python_out=. proto/common_types.proto

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

# JavaScript
npm install grpc-tools
grpc_tools_node_protoc --js_out=. --grpc_out=. proto/common_types.proto

---

Testing Your Integration

Local Testing

1. Start local NCN network (see Running Locally)

2. Configure client to use localhost

3. Submit test requests

4. Verify responses

Testnet Testing

1. Configure client for testnet endpoints

2. Get testnet tokens from faucet

3. Submit requests with payment

4. Verify full payment flow

---

Next Steps

• gRPC Client Guide - Detailed gRPC integration

• HTTP Client Guide - REST API integration

• Payment Integration - Blockchain payments

• Examples - Complete code examples