Che cos’è l’operatorId e perché è obbligatorio? – Bitvavo Centro assistenza

Riepilogo

Questo articolo spiega cos’è il parametro operatorId, perché è richiesto dalla normativa vigente e come utilizzarlo correttamente per creare ordini tramite l’API di Bitvavo. Se utilizzi bot o script per fare trading via API, qui troverai tutto ciò che serve per impostare e inviare l’operatorId nel corpo della richiesta.

Che cos’è l’operatorId?

L’operatorId è un parametro obbligatorio per tutte le richieste API relative alle attività di trading, come ad esempio la creazione di un ordine. È stato introdotto per motivi normativi e serve a identificare chiaramente quale bot, script o sistema ha inviato un ordine tramite il tuo account.

È un numero intero di tipo int64 (cioè una cifra intera lunga), che devi generare e gestire personalmente. Si consiglia un valore compreso tra 1 e 9.223.372.036.854.775.807.

Se utilizzi più bot o script con la stessa chiave API, puoi assegnare un operatorId univoco a ciascuno, per identificare facilmente quale sistema ha generato ogni ordine.

Perché è obbligatorio?

Le normative sui cripto-asset richiedono che le piattaforme come Bitvavo siano in grado di tracciare chiaramente l’attività di trading degli utenti. L’operatorId consente tutto questo perché:

Identifica chi o cosa ha inviato l’ordine tramite il tuo account
È obbligatorio per ogni richiesta API di tipo trading
Non può essere omesso o disattivato
Deve essere un valore numerico univoco per ogni bot o script

Come usare l’operatorId

L’operatorId è un numero intero (int64) che devi definire manualmente. Esempio: 12234 per uno script e 12235 per un altro.

Suggerimento: Assegna un operatorId diverso a ciascun bot o script per monitorare facilmente chi ha inviato cosa.

Come configurarlo correttamente:

Quando utilizzi il metodo POST /order (o altri endpoint di trading), aggiungi l’operatorId nel corpo della richiesta.
Assicurati di inviarlo come numero, senza virgolette.

✅ Corretto: "operatorId": 12234
❌ Errato:   "operatorId": "12234"

Controlla che tutti gli endpoint API che utilizzi includano il parametro operatorId.

Dove trovare un esempio?

Un esempio completo è disponibile nella documentazione API per la creazione di un ordine.

Ecco un esempio semplificato con operatorId incluso correttamente:

{
  "market": "BTC-EUR",
  "side": "buy",
  "orderType": "limit",
  "amount": "0.1",
  "price": "25000",
  "operatorId": 12234
}

L’operatorId deve essere presente nel corpo della richiesta, come numero intero. Se viene omesso o inviato nel formato sbagliato (ad esempio tra virgolette), l’ordine verrà rifiutato.

Suggerimento: Puoi testare le richieste API prima nell’ambiente di test di Bitvavo, per evitare errori in produzione.

Domande frequenti

Devo usare un operatorId diverso per ogni ordine?

No. Puoi usare lo stesso operatorId per tutti gli ordini generati dallo stesso script o bot. Lo scopo è distinguere tra i sistemi, non tra i singoli ordini.

Cosa succede se invio l’operatorId come stringa (con virgolette)?

L’ordine verrà molto probabilmente rifiutato. L’operatorId deve essere inviato come numero intero (int64), non come stringa.

Esiste un operatorId predefinito se non ne imposto uno?

No. È obbligatorio impostare manualmente un operatorId. Non esiste un valore di default.

Riepilogo