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 basehttps://api.neuraxcopute.it
FormatoJSON in UTF-8, in richiesta e in risposta
Autenticazionechiave API nell'intestazione Authorization: Bearer …
Valutaeuro; nessuna criptovaluta
Specifica OpenAPIfile openapi.yaml nel repository pubblico per sviluppatori
Un principio vale per tutta l'API: il costo viene riservato all'invio e addebitato solo quando il risultato è stato verificato. Se un lavoro fallisce, la riserva torna sul tuo credito.

Primi passi in 5 minuti

  1. Registrati come azienda su clienti.neuraxcopute.it e ricarica il credito.
  2. 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.
  3. 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

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

  1. Preventivo — POST /v1/quote: stesso corpo dell'invio, nessun addebito.
  2. Invio — POST /v1/jobs: risposta 201 con l'id del lavoro e stato queued. Il costo è riservato.
  3. Attesa — GET /v1/jobs/{id} ogni pochi secondi: lo stato passa a running e poi a succeeded (oppure failed o canceled). Il campo events è il registro di esecuzione.
  4. Risultato — GET /v1/jobs/{id}/result: valori verificati, impronta del risultato, nodo che lo ha prodotto e sua firma. Aggiungi ?full=1 per avere anche il dettaglio di tutti i blocchi.
  5. 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

ParametroSignificato
spotprezzo attuale del sottostante
strikeprezzo di esercizio
ratetasso privo di rischio annuo (0.03 = 3%)
volatilityvolatilità annua (0.2 = 20%)
maturity_yearsscadenza in anni
option_typecall o put
pathssimulazioni 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
  }
}
ParametroSignificato
positionsnome e valore in euro di ogni posizione; un valore negativo è una posizione corta
pricesuna 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)
datesfacoltative, una per riga: servono a dirti quando è avvenuto lo scenario peggiore
horizon_daysorizzonte della perdita, da 1 a 60 periodi
periods_per_year365 se i prezzi sono di tutti i giorni (criptovalute), 252 per i giorni di borsa; serve solo per la volatilità annua

Il risultato contiene:

Il contributo all'ES è il numero chiave per chi detiene BTC: mostra se un altro titolo compensa le cadute di BTC (contributo basso o negativo) o le amplifica (contributo alto).

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.

Il metodo parametrico presuppone oscillazioni "normali". Per attività con crolli improvvisi, come le criptovalute, tende a sottostimare il rischio: in quei casi usa il metodo storico, o confronta i due.

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}}'
CampoSignificato
functionnome della funzione (elenco su GET /v1/edge/functions)
inputi dati della funzione
regionfacoltativo: EUROPE o CH
nearfacoltativo: posizione dell'utente finale, quando la chiamata parte dal tuo server
timeout_msfacoltativo: 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…

I tempi di NEURAX Edge si misurano in millisecondi: la luce in fibra ottica impiega circa 5 ms ogni 1000 km. Nel livello standard i dati della chiamata sono visibili al nodo che risponde: non inviare dati personali, oppure usa i confini e il Livello Sovrano.

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.

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:

CampoValoriEffetto
region"", EUROPE, CHtutta la rete; solo UE/SEE e Svizzera; solo Svizzera
sovereigntruesolo nodi di partner con identità verificata da NEURAX; richiede region; 150% del prezzo
confidentialtruesolo 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à:

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

CalcoloVerifica prima dell'addebito
Opzioni, VaR Monte Carloricalcolo di blocchi scelti a caso dopo la consegna, con lo stesso generatore casuale, più controlli matematici
VaR storicoricalcolo completo di tutti gli scenari
Matricialgoritmo di Freivalds
Contenitori e renderingdoppia esecuzione su partner diversi; per le immagini PSNR ≥ 35 dB
NEURAX Edgetutte 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 percorsoUso
GET /v1/infopubblicoversione e prezzi
GET /v1/workloadspubblicocalcoli disponibili con esempi
POST /v1/quotepreventivo
POST /v1/jobsinvio di un lavoro
GET /v1/jobsultimi 200 lavori
GET /v1/jobs/{id}stato e registro
DELETE /v1/jobs/{id}annullamento con rimborso
GET /v1/jobs/{id}/resultrisultato verificato
GET /v1/jobs/{id}/evidencefascicolo di prova firmato
POST /v1/evidence/verifypubblicoautenticità di un fascicolo
GET /v1/evidence/keypubblicochiave pubblica dei fascicoli
POST /v1/edge/runchiamata NEURAX Edge
GET /v1/edge/functionspubblicofunzioni Edge e prezzi
GET /v1/edge/recentultime chiamate Edge
POST /v1/jobs/containerprogramma in contenitore
POST /v1/jobs/renderrendering 3D
POST /v1/uploads …caricamento di file grandi a pezzi
GET /v1/meprofilo e credito
GET /v1/billingcredito e movimenti
GET · POST /v1/keys, DELETE /v1/keys/{id}chiavi API
GET /v1/network/statspubblicostato della rete in tempo reale
GET /v1/network/mappubbliconodi per paese e città

Codici di errore

HTTP e codiceSignificato e cosa fare
400 invalidparametri non validi: il messaggio dice quale
400 unsupported_workloadnome del calcolo sconosciuto
401 unauthorizedchiave mancante, errata o revocata
402 insufficient_fundscredito insufficiente: ricarica
403 forbiddenla chiave non ha accesso a questa risorsa
404 not_foundlavoro o risorsa inesistente
409 not_readyrisultato non ancora disponibile: riprova più tardi
409 no_nodes_in_regionnessun nodo attivo nel confine scelto: amplia il confine o riprova
429 rate_limitedtroppe richieste: attendi Retry-After secondi
429 quota_exceededtroppi lavori aperti contemporaneamente
503 standby, no_leaderil server sta passando al server di riserva: riprova dopo qualche secondo
504 edge_timeoutnessuna 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
    Risposta

Per 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:

I sistemi di rischio delle banche o le piattaforme come Bloomberg non si collegano da soli: serve un piccolo adattatore che legga i loro dati e chiami l'API. Lo costruiamo con il cliente, caso per caso.

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