API v1 · in produzione sulla rete pilota
Documentazione API
L'API di NEURAX Compute permette a qualsiasi software di comprare calcolo verificato: prezzi di opzioni, rischio di portafoglio, matrici, programmi in contenitore, rendering 3D e risposte istantanee con NEURAX Edge.
Tutto ciò che si fa dal portale clienti si fa anche dall'API: è un'API REST che parla JSON su HTTPS, lo standard del web. Funziona con qualsiasi linguaggio di programmazione e con Excel.
| Indirizzo base | https://api.neuraxcopute.it |
|---|---|
| Formato | JSON in UTF-8, in richiesta e in risposta |
| Autenticazione | chiave API nell'intestazione Authorization: Bearer … |
| Valuta | euro; nessuna criptovaluta |
| Specifica OpenAPI | file openapi.yaml nel repository pubblico per sviluppatori |
Primi passi in 5 minuti
- Registrati come azienda su clienti.neuraxcopute.it e ricarica il credito.
- Apri Accesso API nel menu e premi Crea chiave. La chiave inizia con
nxk_e viene mostrata una sola volta: salvala in un posto sicuro. - Fai la prima chiamata, un preventivo, che non costa nulla:
export NEURAX_KEY="nxk_la_tua_chiave"
curl -X POST https://api.neuraxcopute.it/v1/quote \
-H "Authorization: Bearer $NEURAX_KEY" \
-H "Content-Type: application/json" \
-d '{"workload":"bs-mc-european@1",
"params":{"spot":100,"strike":105,"rate":0.03,"volatility":0.2,
"maturity_years":1,"option_type":"call","paths":20000000}}'La risposta indica il costo in euro (cost_eur), il tempo di calcolo stimato e il numero di blocchi in cui il lavoro sarà diviso. Per inviarlo davvero basta cambiare l'indirizzo in /v1/jobs.
Autenticazione
Ogni richiesta privata porta la chiave API:
Authorization: Bearer nxk_la_tua_chiave
- Puoi creare più chiavi (per esempio una per ambiente di prova e una per produzione) e revocarle in qualsiasi momento dal portale o con
DELETE /v1/keys/{id}. - Le chiavi di un'azienda vedono solo i lavori di quell'azienda.
- Non inserire mai la chiave nel codice di una pagina web pubblica o di un'app: chiunque potrebbe leggerla. Usala dal tuo server.
- Alcuni endpoint sono pubblici: non richiedono chiave (statistiche della rete, mappa, elenco dei calcoli, verifica dei fascicoli).
Convenzioni
Importi
Gli importi arrivano in due forme: stringa in euro con sei decimali ("cost_eur": "0.001000") e intero in micro-euro ("cost_micro_eur": 1000, dove 1 € = 1.000.000 µ€). Usa i micro-euro per i calcoli contabili: sono interi, quindi senza errori di arrotondamento.
Errori
Ogni errore ha lo stesso formato, con un codice stabile per il tuo programma e un messaggio in italiano per le persone:
{"error": {"code": "insufficient_funds", "message": "credito insufficiente"}}Invii ripetuti: Idempotency-Key
Se la rete cade mentre invii un lavoro, non sai se è arrivato. Aggiungi l'intestazione Idempotency-Key con un valore unico per ogni lavoro (per esempio il numero d'ordine): se ripeti lo stesso invio con la stessa chiave, NEURAX restituisce il lavoro già creato invece di crearne e addebitarne un secondo.
Idempotency-Key: ordine-2026-4711
Limiti
Per proteggere la rete ogni indirizzo può fare in media 10 richieste al secondo, con picchi fino a 40. Oltre il limite ricevi 429 rate_limited con l'intestazione Retry-After: attendi i secondi indicati e riprova. Per volumi più alti scrivi a info@swissgroupnetwork.ch.
Il ciclo di un lavoro
- Preventivo —
POST /v1/quote: stesso corpo dell'invio, nessun addebito. - Invio —
POST /v1/jobs: risposta201con l'iddel lavoro e statoqueued. Il costo è riservato. - Attesa —
GET /v1/jobs/{id}ogni pochi secondi: lo stato passa arunninge poi asucceeded(oppurefailedocanceled). Il campoeventsè il registro di esecuzione. - Risultato —
GET /v1/jobs/{id}/result: valori verificati, impronta del risultato, nodo che lo ha prodotto e sua firma. Aggiungi?full=1per avere anche il dettaglio di tutti i blocchi. - Prova —
GET /v1/jobs/{id}/evidence: il fascicolo firmato (vedi Fascicolo di prova).
Per annullare un lavoro in coda o in corso: DELETE /v1/jobs/{id}; la riserva torna sul credito.
POST /v1/jobs
{
"workload": "bs-mc-european@1",
"params": { "spot": 100, "strike": 105, "rate": 0.03, "volatility": 0.2,
"maturity_years": 1, "option_type": "call", "paths": 20000000 },
"region": "EUROPE",
"sovereign": true
}Calcoli disponibili
L'elenco aggiornato, con descrizione ed esempio di parametri, è sempre disponibile su GET /v1/workloads pubblico.
Caricamento dell'elenco in diretta…
bs-mc-european@1 — Opzione europea
| Parametro | Significato |
|---|---|
spot | prezzo attuale del sottostante |
strike | prezzo di esercizio |
rate | tasso privo di rischio annuo (0.03 = 3%) |
volatility | volatilità annua (0.2 = 20%) |
maturity_years | scadenza in anni |
option_type | call o put |
paths | simulazioni Monte Carlo, da 1.000 a 20 miliardi |
Risultato: price, std_error, intervallo di confidenza al 99% e black_scholes_exact, il prezzo della formula esatta per il confronto.
mc-exotic@1 — Opzioni esotiche
Stessi parametri dell'opzione europea più style (asian a media aritmetica, barrier_up_out, barrier_down_out), steps (date di osservazione) e, per le barriere, barrier.
mc-var@1 — Rischio di portafoglio (Monte Carlo)
VaR ed Expected Shortfall al 95% e 99% di un portafoglio fino a 100 posizioni, partendo da volatilità e correlazioni. Dettagli ed esempio nella sezione Rischio.
hist-var@1 — Rischio di portafoglio (storico) nuovo
VaR ed Expected Shortfall calcolati sui prezzi reali del passato: adatto a BTC e a tutti i titoli con crolli improvvisi. Fino a 50 posizioni e 10.000 date.
matmul@1 — Moltiplicazione di matrici
C = A·B in doppia precisione: m, k, n sono le dimensioni; a e b le matrici, riga per riga, come numeri float64 little-endian codificati in base64. Fino a 600.000 valori in tutto.
Rischio di portafoglio: BTC e altri titoli
Domanda tipica: "Ho 100.000 € in Bitcoin e 200.000 € in un'azione: quanto posso perdere in un giorno, nel 99% dei casi?" NEURAX risponde con due metodi.
Metodo 1 — Storico (consigliato per BTC): hist-var@1
Invii i prezzi giornalieri reali dei titoli, uno per data, dalla data più vecchia alla più recente. NEURAX considera ogni periodo passato come uno scenario possibile ("se domani succedesse quello che è successo il 12 marzo 2020…") e calcola la perdita del tuo portafoglio di oggi in ogni scenario. Non presuppone nessuna distribuzione: i crolli veri del passato restano nel calcolo.
POST /v1/jobs
{
"workload": "hist-var@1",
"params": {
"positions": [ { "name": "BTC", "value_eur": 100000 },
{ "name": "Azione XY", "value_eur": 200000 } ],
"dates": [ "2024-01-02", "2024-01-03", "2024-01-04", "…" ],
"prices": [ [ 41250.0, 52.10 ],
[ 42010.5, 52.35 ],
[ 40875.2, 51.90 ],
[ "…" ] ],
"horizon_days": 1,
"periods_per_year": 365
}
}| Parametro | Significato |
|---|---|
positions | nome e valore in euro di ogni posizione; un valore negativo è una posizione corta |
prices | una riga per data, una colonna per posizione nello stesso ordine; prezzi positivi, nella stessa valuta (meglio in euro: se BTC è in dollari, nel risultato manca il rischio di cambio) |
dates | facoltative, una per riga: servono a dirti quando è avvenuto lo scenario peggiore |
horizon_days | orizzonte della perdita, da 1 a 60 periodi |
periods_per_year | 365 se i prezzi sono di tutti i giorni (criptovalute), 252 per i giorni di borsa; serve solo per la volatilità annua |
Il risultato contiene:
var_99_eur,var_95_eur— la perdita che non viene superata nel 99% (95%) degli scenari;es_99_eur,es_95_eur— Expected Shortfall: la perdita media nell'1% (5%) degli scenari peggiori;worst_loss_eurconworst_fromeworst_to— la perdita peggiore osservata e quando;positions— per ogni titolo: volatilità annua, VaR 99% da solo e contributo all'ES 99%, cioè quanto quel titolo pesa nelle perdite dei giorni peggiori;correlation— le correlazioni osservate tra i titoli.
Questo calcolo è deterministico: il server NEURAX ricalcola tutti gli scenari prima dell'addebito, non solo un campione.
Dal portale clienti basta caricare un file CSV esportato da Excel, con la prima riga data;BTC;Azione XY e poi una riga per data. Il portale accetta punto e virgola, tabulazione o virgola e la virgola decimale italiana.
Metodo 2 — Parametrico (Monte Carlo): mc-var@1
Se hai già volatilità e correlazioni (per esempio dai tuoi sistemi di rischio), NEURAX simula milioni di scenari con rendimenti log-normali correlati:
{
"workload": "mc-var@1",
"params": {
"positions": [ { "name": "BTC", "value_eur": 100000, "volatility": 0.60 },
{ "name": "Azione XY", "value_eur": 200000, "volatility": 0.25 } ],
"correlation": [ [1, 0.3], [0.3, 1] ],
"horizon_days": 10,
"scenarios": 2000000
}
}I valori di volatilità e correlazione qui sopra sono solo un esempio di formato, non dati di mercato.
NEURAX Edge: risposte istantanee
Per i calcoli che servono in millisecondi, NEURAX Edge affida la richiesta al nodo che risponderà prima. L'algoritmo NEURAX Bounce prevede il tempo di risposta di ogni nodo e, se il nodo scelto tarda, fa rimbalzare la richiesta al successivo. Vince la prima risposta corretta, ed è l'unica pagata.
curl -X POST https://api.neuraxcopute.it/v1/edge/run \
-H "Authorization: Bearer $NEURAX_KEY" -H "Content-Type: application/json" \
-d '{"function":"option.price@1",
"input":{"spot":100,"strike":105,"rate":0.03,"volatility":0.2,"years":1,"type":"call"},
"region":"EUROPE",
"near":{"lat":46.0,"lon":8.95}}'| Campo | Significato |
|---|---|
function | nome della funzione (elenco su GET /v1/edge/functions) |
input | i dati della funzione |
region | facoltativo: EUROPE o CH |
near | facoltativo: posizione dell'utente finale, quando la chiamata parte dal tuo server |
timeout_ms | facoltativo: tempo massimo di attesa |
La risposta contiene output, latency_ms, price_eur, bounced (se c'è stato un rimbalzo), audited (se il server ha ricontrollato la risposta) e path, il percorso della chiamata: nodo, città, ruolo (first, bounce, origin), esito e millisecondi.
Caricamento delle funzioni in diretta…
Programmi in contenitore e rendering 3D
Puoi far eseguire il tuo programma in un contenitore Docker isolato (senza rete, senza privilegi, file in sola lettura, limiti di CPU, memoria e tempo) e scene Blender divise tra i nodi. Ogni parte viene eseguita da due nodi di partner diversi e pagata solo se i risultati coincidono.
POST /v1/uploadse seguenti: caricamento dei file grandi a pezzi da 50 MB, fino a 20 GB, che riprende da solo dopo un'interruzione.POST /v1/jobs/container: immagine, comando, file di ingresso e, facoltativamente, un elenco di compiti da eseguire in parallelo.POST /v1/jobs/render: file.blend, fotogrammi, motore di rendering.
La guida completa, con esempi, è nel repository pubblico per sviluppatori.
Confini e Livello Sovrano
Ogni lavoro e ogni chiamata Edge possono dire dove e da chi devono essere eseguiti:
| Campo | Valori | Effetto |
|---|---|---|
region | "", EUROPE, CH | tutta la rete; solo UE/SEE e Svizzera; solo Svizzera |
sovereign | true | solo nodi di partner con identità verificata da NEURAX; richiede region; 150% del prezzo |
confidential | true | solo nodi certificati con accordo di riservatezza; 200% del prezzo |
Il paese di un nodo è quello del suo indirizzo internet, rilevato da Cloudflare: il partner non può dichiararlo né cambiarlo. Se nel confine non ci sono nodi attivi, il lavoro viene rifiutato subito con 409 no_nodes_in_region, senza addebiti.
Fascicolo di prova
Per ogni lavoro puoi scaricare un fascicolo firmato digitalmente da NEURAX: GET /v1/jobs/{id}/evidence. Contiene il lavoro, i confini richiesti, ogni esecuzione verificata (nodo, partner, paese, città, impronta del risultato, ora), il metodo di verifica, il registro degli eventi, le registrazioni contabili e l'esito all_executions_inside_boundaries.
Chiunque, per esempio il tuo revisore, può verificarne l'autenticità:
- sul sito, trascinando il file in Verifica un fascicolo;
- via API, inviando il file così com'è:
POST /v1/evidence/verifypubblico, risposta{"authentic": true}; - in modo indipendente da NEURAX, con la chiave pubblica
GET /v1/evidence/key: la firma è ECDSA P-256 su SHA-256 del campoevidencein forma JSON compatta.
curl -X POST https://api.neuraxcopute.it/v1/evidence/verify \ -H "Content-Type: application/json" \ --data-binary @neurax-fascicolo-job_5676a3f2696bdbcc.json
Come verifichiamo i risultati
| Calcolo | Verifica prima dell'addebito |
|---|---|
| Opzioni, VaR Monte Carlo | ricalcolo di blocchi scelti a caso dopo la consegna, con lo stesso generatore casuale, più controlli matematici |
| VaR storico | ricalcolo completo di tutti gli scenari |
| Matrici | algoritmo di Freivalds |
| Contenitori e rendering | doppia esecuzione su partner diversi; per le immagini PSNR ≥ 35 dB |
| NEURAX Edge | tutte le prime 10 risposte di ogni nodo nuovo, poi un campione che cresce se la reputazione del nodo scende |
Ogni risultato è firmato dal nodo che lo ha prodotto (node_signature). Un nodo che sbaglia non viene pagato e perde reputazione; sotto una soglia va in quarantena.
Tutti gli endpoint
| Metodo e percorso | Uso |
|---|---|
GET /v1/info | pubblicoversione e prezzi |
GET /v1/workloads | pubblicocalcoli disponibili con esempi |
POST /v1/quote | preventivo |
POST /v1/jobs | invio di un lavoro |
GET /v1/jobs | ultimi 200 lavori |
GET /v1/jobs/{id} | stato e registro |
DELETE /v1/jobs/{id} | annullamento con rimborso |
GET /v1/jobs/{id}/result | risultato verificato |
GET /v1/jobs/{id}/evidence | fascicolo di prova firmato |
POST /v1/evidence/verify | pubblicoautenticità di un fascicolo |
GET /v1/evidence/key | pubblicochiave pubblica dei fascicoli |
POST /v1/edge/run | chiamata NEURAX Edge |
GET /v1/edge/functions | pubblicofunzioni Edge e prezzi |
GET /v1/edge/recent | ultime chiamate Edge |
POST /v1/jobs/container | programma in contenitore |
POST /v1/jobs/render | rendering 3D |
POST /v1/uploads … | caricamento di file grandi a pezzi |
GET /v1/me | profilo e credito |
GET /v1/billing | credito e movimenti |
GET · POST /v1/keys, DELETE /v1/keys/{id} | chiavi API |
GET /v1/network/stats | pubblicostato della rete in tempo reale |
GET /v1/network/map | pubbliconodi per paese e città |
Codici di errore
| HTTP e codice | Significato e cosa fare |
|---|---|
400 invalid | parametri non validi: il messaggio dice quale |
400 unsupported_workload | nome del calcolo sconosciuto |
401 unauthorized | chiave mancante, errata o revocata |
402 insufficient_funds | credito insufficiente: ricarica |
403 forbidden | la chiave non ha accesso a questa risorsa |
404 not_found | lavoro o risorsa inesistente |
409 not_ready | risultato non ancora disponibile: riprova più tardi |
409 no_nodes_in_region | nessun nodo attivo nel confine scelto: amplia il confine o riprova |
429 rate_limited | troppe richieste: attendi Retry-After secondi |
429 quota_exceeded | troppi lavori aperti contemporaneamente |
503 standby, no_leader | il server sta passando al server di riserva: riprova dopo qualche secondo |
504 edge_timeout | nessuna risposta Edge entro il tempo massimo |
Esempi completi
Python
import os, time, requests
API = "https://api.neuraxcopute.it"
H = {"Authorization": "Bearer " + os.environ["NEURAX_KEY"]}
job = requests.post(API + "/v1/jobs", headers={**H, "Idempotency-Key": "rischio-btc-001"}, json={
"workload": "mc-var@1",
"params": {"positions": [{"name": "BTC", "value_eur": 100000, "volatility": 0.60},
{"name": "Azione XY", "value_eur": 200000, "volatility": 0.25}],
"correlation": [[1, 0.3], [0.3, 1]], "horizon_days": 10, "scenarios": 2000000},
"region": "EUROPE"}).json()
while True:
j = requests.get(API + "/v1/jobs/" + job["id"], headers=H).json()
if j["status"] in ("succeeded", "failed", "canceled"):
break
time.sleep(2)
r = requests.get(API + "/v1/jobs/" + job["id"] + "/result", headers=H).json()
print("VaR 99%:", round(r["var_99_eur"]), "EUR ES 99%:", round(r["es_99_eur"]), "EUR")VaR storico da un file CSV (Python)
import csv
rows = list(csv.reader(open("prezzi.csv"), delimiter=";")) # data;BTC;Azione XY
names, data = rows[0][1:], rows[1:]
params = {
"positions": [{"name": "BTC", "value_eur": 100000}, {"name": "Azione XY", "value_eur": 200000}],
"dates": [r[0] for r in data],
"prices": [[float(x.replace(",", ".")) for x in r[1:]] for r in data],
"horizon_days": 1, "periods_per_year": 365}
job = requests.post(API + "/v1/jobs", headers=H, json={"workload": "hist-var@1", "params": params}).json()JavaScript (Node.js 18 o successivo)
const API = "https://api.neuraxcopute.it";
const H = { Authorization: "Bearer " + process.env.NEURAX_KEY, "Content-Type": "application/json" };
const r = await fetch(API + "/v1/edge/run", { method: "POST", headers: H, body: JSON.stringify({
function: "option.price@1",
input: { spot: 100, strike: 105, rate: 0.03, volatility: 0.2, years: 1, type: "call" },
region: "EUROPE" }) });
const out = await r.json();
console.log(out.output, out.latency_ms + " ms", out.bounced ? "con rimbalzo" : "");Excel (Power Query)
In Excel: Dati › Recupera dati › Da altre origini › Query vuota, poi Editor avanzato e incolla:
let
Chiave = "nxk_la_tua_chiave",
Corpo = Json.FromValue([workload = "bs-mc-european@1",
params = [spot = 100, strike = 105, rate = 0.03, volatility = 0.2,
maturity_years = 1, option_type = "call", paths = 1000000]]),
Risposta = Json.Document(Web.Contents("https://api.neuraxcopute.it/v1/quote",
[Headers = [Authorization = "Bearer " & Chiave, #"Content-Type" = "application/json"],
Content = Corpo]))
in
RispostaPer non lasciare la chiave nel file, mettila in un parametro di Power Query o in una cella protetta.
Compatibilità
L'API usa solo standard aperti (HTTPS, JSON, OpenAPI 3.1), quindi funziona con:
- linguaggi: Python, R, MATLAB, Julia, Java, Kotlin, C#, Go, JavaScript e TypeScript, PHP, Ruby e qualsiasi altro che sappia fare richieste HTTPS;
- strumenti: Excel e Power BI (Power Query), Jupyter, Postman, curl;
- generatori di client: dal file
openapi.yamlsi genera una libreria per il proprio linguaggio in pochi minuti.
Community e GitHub
Il repository pubblico per sviluppatori contiene la specifica OpenAPI, questa documentazione, esempi pronti in più linguaggi e la libreria Python ufficiale. Lì puoi segnalare problemi, proporre nuove funzioni e discutere con il team e con gli altri sviluppatori.
Il motore di NEURAX, gli algoritmi NEURAX Edge e NEURAX Bounce e il server restano proprietà di Swiss Group Network SNC e non sono pubblicati.
Contatti: info@swissgroupnetwork.ch