Riferimento API¶

Concetti comuni ¶

Volume, prezzi, tipi di ordine e validità temporale

Volume¶

Il volume è specificato in centesimi (unità di 0,0000001 lotti).

Lotti	Volume (centesimi)
0,01	`100.000`
0,1	`1.000.000`
1,0	`10.000.000`

Prezzi¶

I valori dei prezzi sono in pipette. Per convertire: display_price = pipette_value / 10^pipDigits

Per EURUSD (5 cifre), un valore pipette di 112345 = 1,12345.

Tipi di ordine¶

Tipo	Descrizione	Campi obbligatori
`MARKET`	Esegui immediatamente al prezzo corrente	`symbolId`, `tradeSide`, `volume`
`LIMIT`	Esegui al prezzo limite o migliore	+ `limitPrice`
`STOP`	Attiva quando il mercato raggiunge il prezzo stop	+ `stopPrice`
`MARKET_RANGE`	Esegui entro un intervallo di prezzo	+ `baseSlippagePrice`
`STOP_LIMIT`	Ordine limite attivato al prezzo stop	+ `stopPrice`, `limitPrice`

Validità temporale¶

Politica	Descrizione
`GOOD_TILL_CANCEL`	L'ordine rimane attivo fino all'esecuzione o alla cancellazione
`GOOD_TILL_DATE`	L'ordine scade al `expirationTimestamp` specificato
`IMMEDIATE_OR_CANCEL`	Esegui ciò che è disponibile immediatamente, cancella il resto

Informazioni sul conto ¶

GET /v1/balance Get account balance

Restituisce saldo del conto, capitale netto e margine disponibile.

Parametri

Nessun parametro.

Risposte

200 Risposta riuscita

Response body

{
  "balance": 10000.00,
  "equity": 10250.75,
  "freeMargin": 9800.50,
  "balanceVersion": 42,
  "moneyDigits": 2,
  "depositAssetId": 1
}

Field	Tipo	Descrizione
`balance`	double	Saldo del conto nella valuta di deposito
`equity`	double	Saldo + P&L fluttuante
`freeMargin`	double	Margine disponibile per nuove operazioni
`balanceVersion`	int64	Contatore versione saldo
`moneyDigits`	int32	Cifre decimali per i valori monetari
`depositAssetId`	int64	ID asset della valuta di deposito

GET /v1/symbols Ottieni i simboli disponibili

Restituisce tutti i simboli disponibili per il trading sul conto.

Parametri

Nessun parametro.

Risposte

200 Array di oggetti Symbol

Response body

[
  {
    "symbolId": 1,
    "symbolName": "EURUSD",
    "enabled": true,
    "baseAssetId": 2,
    "quoteAssetId": 1,
    "description": "Euro vs US Dollar"
  }
]

Symbol

Field	Tipo	Descrizione
`symbolId`	int64	ID simbolo (utilizzato in altre chiamate API)
`symbolName`	string	Nome simbolo (ad es., "EURUSD")
`enabled`	boolean	Se il simbolo è negoziabile
`baseAssetId`	int64	ID asset di base
`quoteAssetId`	int64	ID asset di quotazione
`description`	string	Descrizione leggibile

GET /v1/assets Ottieni gli asset disponibili

Restituisce gli asset disponibili (valute).

Parametri

Nessun parametro.

Risposte

200 Array di oggetti Asset

Response body

[
  {
    "assetId": 1,
    "name": "USD",
    "displayName": "US Dollar"
  }
]

Asset

Field	Tipo	Descrizione
`assetId`	int64	ID asset
`name`	string	Codice asset (ad es., "USD")
`displayName`	string	Nome visualizzato

Dati di mercato ¶

GET /v1/prices Ottieni prezzi spot

Restituisce i prezzi bid/ask correnti per i simboli specificati. Si tratta di un 'istantanea – l'API non supporta lo streaming.

Parametri

Nome	Posizione in	Tipo	Obbligatorio	Descrizione
`symbolId`	query	int64[]		ID simbolo separati da virgola

Risposte

200 Array di oggetti SpotPrice

Response body

[
  {
    "symbolId": 1,
    "bid": 112340,
    "ask": 112355,
    "high": 112890,
    "low": 111950,
    "sessionClose": 112100,
    "timestamp": 1700000000000
  }
]

SpotPrice

Field	Tipo	Descrizione
`symbolId`	int64	ID simbolo
`bid`	int64	Miglior prezzo bid (pipette)
`ask`	int64	Miglior prezzo ask (pipette)
`high`	int64	Massimo di sessione (pipette)
`low`	int64	Minimo di sessione (pipette)
`sessionClose`	int64	Chiusura sessione precedente (pipette)
`timestamp`	int64	Timestamp quotazione (epoch ms)

GET /v1/trendbars Ottieni dati OHLCV storici

Restituisce dati storici a candela (OHLCV) per un simbolo.

Parametri

Nome	Posizione in	Tipo	Predefinito	Descrizione
`symbolId`	query	int64	–	ID simbolo
`period`	query	string	–	Periodo barra
`fromTimestamp`	query	string	–	Ora di inizio (ISO-8601)
`toTimestamp`	query	string	–	Ora di fine (ISO-8601)
`count`	query	int32	`100`	Numero massimo di barre da restituire

Periodi disponibili

M_1 M_2 M_3 M_4 M_5 M_10 M_15 M_30 H_1 H_2 H_3 H_4 H_6 H_8 H_12 D_1 W_1 MN_1

Risposte

200 Array di oggetti Trendbar

Response body

[
  {
    "timestamp": 1700000000000,
    "open": 112340.0,
    "high": 112890.0,
    "low": 111950.0,
    "close": 112500.0,
    "volume": 4521
  }
]

Trendbar

Field	Tipo	Descrizione
`timestamp`	int64	Ora di apertura barra (epoch ms)
`open`	double	Prezzo di apertura (pipette)
`high`	double	Prezzo massimo (pipette)
`low`	double	Prezzo minimo (pipette)
`close`	double	Prezzo di chiusura (pipette)
`volume`	int64	Volume di tick

Ordini ¶

POST /v1/orders Inserisci un nuovo ordine

Inserisce un nuovo ordine di trading. Restituisce un ExecutionResponse.

Parametri

Nessun parametro di percorso o query.

Corpo della richiesta application/json

Field	Tipo	Descrizione
`symbolId`	int64	Simbolo da negoziare
`orderType`	string	`MARKET`, `LIMIT`, `STOP`, `MARKET_RANGE`, `STOP_LIMIT`
`tradeSide`	string	`BUY` o `SELL`
`volume`	int64	Volume in centesimi
`limitPrice`	double	Prezzo limite – richiesto per `LIMIT`, `STOP_LIMIT`
`stopPrice`	double	Prezzo di attivazione stop – richiesto per `STOP`, `STOP_LIMIT`
`stopLoss`	double	Prezzo stop loss
`takeProfit`	double	Prezzo take profit
`comment`	string	Commento in testo libero (max 256 caratteri)
`label`	string	Etichetta bot (max 100 caratteri)
`timeInForce`	string	`GOOD_TILL_CANCEL`, `GOOD_TILL_DATE`, `IMMEDIATE_OR_CANCEL`
`baseSlippagePrice`	double	Prezzo base per slippage – richiesto per `MARKET_RANGE`
`slippageInPoints`	int32	Slippage massimo in punti
`expirationTimestamp`	int64	Timestamp di scadenza (epoch ms) – per `GOOD_TILL_DATE`

Example request body

{
  "symbolId": 1,
  "orderType": "MARKET",
  "tradeSide": "BUY",
  "volume": 10000000,
  "stopLoss": 112000,
  "takeProfit": 113000
}

Risposte

200 ExecutionResponse – ordine accettato o eseguito

400 INVALID_REQUEST o TRADING_BAD_VOLUME

422 NOT_ENOUGH_MONEY

409 MARKET_CLOSED

Example success response

{
  "orderId": 12345,
  "positionId": 67890,
  "executionType": "ORDER_FILLED",
  "order": { "..." : "..." },
  "position": { "..." : "..." },
  "deal": { "..." : "..." }
}

GET /v1/orders Ottieni ordini in sospeso

Restituisce tutti gli ordini in sospeso (non eseguiti).

Parametri

Nessun parametro.

Risposte

200 Array di oggetti Order in sospeso

PUT /v1/orders/{orderId} Modifica un ordine in sospeso

Modifica un ordine in sospeso esistente. Restituisce un ExecutionResponse.

Parametri

Nome	Posizione in	Tipo	Obbligatorio	Descrizione
`orderId`	path	int64		L'ordine da modificare

Corpo della richiesta application/json

Qualsiasi sottoinsieme dei seguenti campi.

Field	Tipo	Descrizione
`volume`	int64	Nuovo volume in centesimi
`limitPrice`	double	Nuovo prezzo limite
`stopPrice`	double	Nuovo prezzo stop
`stopLoss`	double	Nuovo prezzo stop loss
`takeProfit`	double	Nuovo prezzo take profit
`expirationTimestamp`	int64	Nuovo timestamp di scadenza (epoch ms)

Risposte

200 ExecutionResponse con ORDER_REPLACED

404 Ordine non trovato

DELETE /v1/orders/{orderId} Annulla un ordine in sospeso

Annulla un ordine in sospeso. Restituisce un ExecutionResponse.

Parametri

Nome	Posizione in	Tipo	Obbligatorio	Descrizione
`orderId`	path	int64		L'ordine da annullare

Risposte

200 ExecutionResponse con ORDER_CANCELLED

404 Ordine non trovato

GET /v1/orders/history Ottieni storico ordini

Restituisce gli ordini storici all'interno di un intervallo di tempo.

Parametri

Nome	Posizione in	Tipo	Obbligatorio	Descrizione
`fromTimestamp`	query	string		Ora di inizio (ISO-8601)
`toTimestamp`	query	string		Ora di fine (ISO-8601)

Risposte

200 OrderListResponse

Field	Tipo	Descrizione
`orders`	Order[]	Array di ordini storici
`hasMore`	boolean	Indica se sono disponibili pagine aggiuntive

Posizioni ¶

GET /v1/positions Ottieni posizioni aperte

Restituisce tutte le posizioni aperte e gli ordini in sospeso.

Parametri

Nessun parametro.

Risposte

200 Array di oggetti Position

Response body

[
  {
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "entryPrice": 112345.0,
    "stopLoss": 112000.0,
    "takeProfit": 113000.0,
    "unrealizedPnl": 155.25,
    "commission": -7.00,
    "swap": -1.20
  }
]

Posizione

Field	Tipo	Descrizione
`positionId`	int64	ID posizione
`symbolId`	int64	ID simbolo
`tradeSide`	string	`BUY` o `SELL`
`volume`	int64	Volume in centesimi
`entryPrice`	double	Prezzo di entrata VWAP
`stopLoss`	double	Prezzo stop loss
`takeProfit`	double	Prezzo take profit
`unrealizedPnl`	double	Profitto/perdita fluttuante
`commission`	double	Commissione addebitata
`swap`	double	Importo swap

GET /v1/positions/{positionId} Ottieni dettagli posizione

Restituisce una posizione con i relativi ordini e operazioni.

Parametri

Nome	Posizione in	Tipo	Obbligatorio	Descrizione
`positionId`	path	int64		L'ID della posizione

Risposte

200 PositionDetailResponse

Field	Tipo	Descrizione
`position`	Position	Oggetto Position
`orders`	Order[]	Ordini correlati
`deals`	Deal[]	Operazioni correlate

PUT /v1/positions/{positionId} Modifica SL/TP posizione

Aggiorna lo stop loss e/o il take profit per una posizione aperta. Restituisce un ExecutionResponse.

Parametri

Nome	Posizione in	Tipo	Obbligatorio	Descrizione
`positionId`	path	int64		L'ID della posizione

Corpo della richiesta application/json

Field	Tipo	Descrizione
`stopLoss`	double	Nuovo prezzo stop loss (`null` per rimuovere)
`takeProfit`	double	Nuovo prezzo take profit (`null` per rimuovere)
`trailingStopLoss`	boolean	Abilita trailing stop loss

Example request body

{
  "stopLoss": 111500,
  "takeProfit": 113500,
  "trailingStopLoss": false
}

Risposte

200 ExecutionResponse

POST /v1/positions/{positionId}/close Chiudi una posizione

Chiude una posizione aperta completamente o parzialmente. Utilizza un valore inferiore al volume completo della posizione per una chiusura parziale. Restituisce un ExecutionResponse.

Parametri

Nome	Posizione in	Tipo	Obbligatorio	Descrizione
`positionId`	path	int64		L'ID della posizione

Corpo della richiesta application/json

Field	Tipo	Obbligatorio	Descrizione
`volume`	int64		Volume da chiudere in centesimi

Example – full close (1 lot)

{
  "volume": 10000000
}

Risposte

200 ExecutionResponse

422 NOT_ENOUGH_MONEY – margine insufficiente per chiusura parziale

Operazioni ¶

GET /v1/deals Ottieni cronologia operazioni

Restituisce le operazioni eseguite entro un intervallo di tempo.

Parametri

Nome	Posizione in	Tipo	Predefinito	Descrizione
`fromTimestamp`	query	string	–	Ora di inizio (ISO-8601)
`toTimestamp`	query	string	–	Ora di fine (ISO-8601)
`maxRows`	query	int32	`50`	Numero massimo di operazioni da restituire

Risposte

200 Array di oggetti Deal

Response body

[
  {
    "dealId": 11111,
    "orderId": 12345,
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "filledVolume": 10000000,
    "executionPrice": 112345.0,
    "executionTimestamp": 1700000000000,
    "dealStatus": "FILLED",
    "commission": -7.00
  }
]

Deal

Field	Tipo	Descrizione
`dealId`	int64	ID operazione
`orderId`	int64	Ordine che ha attivato questa operazione
`positionId`	int64	ID posizione
`symbolId`	int64	ID simbolo
`tradeSide`	string	`BUY` o `SELL`
`volume`	int64	Volume richiesto in centesimi
`filledVolume`	int64	Volume completato in centesimi
`executionPrice`	double	Prezzo di esecuzione
`executionTimestamp`	int64	Ora di esecuzione (epoch ms)
`dealStatus`	string	Stato – vedi valori di seguito
`commission`	double	Commissione addebitata

Valori dealStatus

Valore	Significato
`FILLED`	Ordine completamente completato
`PARTIALLY_FILLED`	Ordine completato parzialmente
`REJECTED`	Rifiutato dal server di trading
`INTERNALLY_REJECTED`	Rifiutato internamente prima di raggiungere il server
`ERROR`	Si è verificato un errore durante l'esecuzione
`MISSED`	Ordine mancato (ad es., gap nel mercato)

Schemi { #execution-response-schema } ¶

ExecutionResponse ¶

Tutte le operazioni di inserimento, modifica e cancellazione degli ordini restituiscono questo oggetto.

Field	Tipo	Descrizione
`orderId`	int64	ID ordine interessato
`positionId`	int64	ID posizione interessata
`executionType`	string	Tipo di risultato – vedi valori di seguito
`order`	Order	Dettagli ordine (se applicabile)
`position`	Position	Dettagli posizione (se applicabile)
`deal`	Deal	Dettagli operazione (se applicabile)

Valori executionType

Valore	Significato
`ORDER_ACCEPTED`	Ordine in sospeso accettato
`ORDER_FILLED`	Ordine completamente completato
`ORDER_REPLACED`	Ordine modificato
`ORDER_CANCELLED`	Ordine annullato
`ORDER_EXPIRED`	Ordine scaduto
`ORDER_REJECTED`	Ordine rifiutato
`ORDER_CANCEL_REJECTED`	Richiesta di cancellazione rifiutata
`ORDER_PARTIAL_FILL`	Ordine completato parzialmente
`SWAP`	Swap posizione applicato
`DEPOSIT`	Deposito sul conto
`WITHDRAW`	Prelievo dal conto
`BONUS_DEPOSIT_WITHDRAW`	Deposito o prelievo bonus

Limiti di frequenza ¶

Il gateway applica limiti di frequenza a più livelli.

Livello	Descrizione
Per IP	Limita le richieste totali da un singolo indirizzo IP
Per utente	Limita le richieste totali su tutti i conti per un singolo token
Per conto	Limita le richieste indirizzate a un singolo conto di trading

Limite di frequenza superato

Quando viene superato un limite di frequenza, l'API restituisce 429 Too Many Requests con un'intestazione Retry-After.

Gestione degli errori ¶

Quando una richiesta fallisce, l'API restituisce una risposta di errore JSON.

Error response format

{
  "error": {
    "code": "NOT_ENOUGH_MONEY",
    "message": "Insufficient free margin for this order",
    "httpStatus": 422,
    "retryAfter": null
  }
}

Codici di errore ¶

Codice	HTTP	Descrizione
`INVALID_REQUEST`	400	Parametri di richiesta non validi o mancanti
`UNAUTHORIZED`	401	Token non valido, scaduto o mancante
`TRADING_BAD_VOLUME`	400	Il volume non è valido (inferiore al minimo o supera la posizione)
`NOT_ENOUGH_MONEY`	422	Margine disponibile insufficiente
`SYMBOL_NOT_FOUND`	404	L'ID simbolo non esiste
`MARKET_CLOSED`	409	Il mercato per il simbolo è attualmente chiuso
`MAINTENANCE`	503	Il server di trading è in modalità manutenzione
`TIMEOUT`	504	Il server di trading non ha risposto in tempo
`GATEWAY_RATE_LIMIT`	429	Limite di frequenza superato – vedi intestazione `Retry-After`

Gestione del limite di frequenza

Quando ricevi una risposta 429, l'intestazione Retry-After e il campo retryAfter indicano quanti secondi devi attendere prima di inviare la richiesta successiva.