> Per gli agenti AI: guida passo passo alla configurazione — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), indice della documentazione — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Tariffe e account

Prezzi dei modelli, commissioni di deposito e prelievo, tasso GNK. API dell'account tramite chiave: saldo, spesa per giorno e per modello, cronologia delle operazioni e dei depositi.

## Prezzi dei modelli

I prezzi includono già il ricarico della piattaforma 10%. I valori aggiornati sono su `GET /api/pricing`, senza chiave.

| `model` | Input, $ per 1M token | Output, $ per 1M token | nGNK per token: input / output |
| --- | ---: | ---: | ---: |
| `MiniMaxAI/MiniMax-M2.7` | $0.008349 | $0.02505 | 33 / 99 |
| `deepseek-ai/DeepSeek-V4-Flash-0731` | $0.008349 | $0.02505 | 33 / 99 |
| `zai-org/GLM-5.3-Flash` | $0.008349 | $0.02505 | 33 / 99 |

- Costo della richiesta = token di input × prezzo di input + token di output × prezzo di output. Il ragionamento del modello viene conteggiato come token di output.
- L'addebito è in GNK (1 GNK = 10⁹ `nGNK`); i prezzi in dollari seguono il cambio GNK $0.253.
- Prima della richiesta il gateway confronta il saldo con la stima del costo; se non basta, `402 insufficient_funds`.
- Dopo la registrazione arrivano sul conto 0.1 GNK — circa 3M token al prezzo di input.

## Commissioni

| Operazione | Commissione | Nota |
| --- | --- | --- |
| Ricarico sulle richieste ai modelli | 10% | Già incluso nei prezzi qui sopra. |
| Ricarica GNK | gratis | Trasferimento all'indirizzo del gateway con il tuo `memo`; accredito automatico. |
| Ricarica USDT | 5% → 2.5% | Pagamento tramite OxaPay; più alto è l'importo, più bassa è la commissione — [Scaglioni di commissione USDT](https://gate.joingonka.ai/it/docs/billing#usdt-tiers). |
| Ricarica WGNK da Ethereum | 1% | Copre il gas della rete Ethereum durante il trasferimento in Gonka. |
| Prelievo GNK | 5% | Solo dalla dashboard, da 1 GNK. |
| Cambio GNK | $0.253 | Su di esso si calcolano le ricariche e i prezzi in dollari; si aggiorna automaticamente. |

### Scaglioni di commissione USDT

L'aliquota dipende dall'importo della ricarica, soglia inclusa:

| Importo della ricarica | Commissione |
| --- | ---: |
| da $0 | 5% |
| da $25 | 4.5% |
| da $50 | 4% |
| da $100 | 3.5% |
| da $250 | 3% |
| da $500 | 2.75% |
| da $1000 | 2.5% |

## API dell'account

Saldo, spesa e ricariche sono accessibili con la stessa chiave delle richieste ai modelli (`Authorization: Bearer jg-…`). Queste richieste non consumano token.

Errori: senza chiave — `401 authentication_error`, parametri non validi — `400 validation_error`, percorso della dashboard con API key — `403 forbidden`.

### GET `/api/balance`

Saldo attuale.

| Campo | Descrizione |
| --- | --- |
| `balance_ngonka` | Saldo in nGNK — come stringa, per non perdere precisione |
| `balance_usd` | Saldo in dollari al cambio attuale |
| `cost_per_token_ngonka` | Prezzo del token di input del modello consigliato con ricarico, nGNK |
| `tokens_remaining` | A quanti token di input basta il saldo a questo prezzo — stima |

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

### GET `/api/usage`

Consumo per giorno: richieste, token, costo.

- `period` — `day`, `week`, `month`, `quarter`, predefinito `month`.
- Oppure `from` e `to` nel formato `YYYY-MM-DD`, entrambi insieme, fino a 92 giorni inclusi — in quel caso la risposta è `period: custom`.
- `tz` — offset in minuti, come `getTimezoneOffset()` nel browser: per UTC+3 è `-180`. Senza, è UTC.

La risposta è un array di giorni con i campi `date, requests, tokens, costNgonka`. I record dettagliati delle richieste sono conservati per 90 giorni.

```bash
curl -s "https://gate.joingonka.ai/api/usage?period=week&tz=-180" \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

### GET `/api/usage/by-model`

Consumo per modello: totali in `models` e serie "periodo × modello" in `series` — ore con `period=day`, altrimenti giorni. Parametri come in `/api/usage`.

### GET `/api/usage/by-key`

Consumo per chiave — `keys`. Parametri come in `/api/usage`.

### GET `/api/transactions`

Storico delle operazioni: ricariche, addebiti per le richieste, bonus, prelievi.

- `limit` — fino a 200, predefinito 50; `offset` — spostamento.
- `type` — filtro: `DEPOSIT_USDT`, `DEPOSIT_GNK`, `DEPOSIT_FIAT`, `INFERENCE`, `REFERRAL_REWARD`, `BONUS`, `WITHDRAWAL`.
- `from` e `to` — date, fine inclusa.

La risposta contiene record con i campi `id, type, amountNgonka, feeNgonka, description, createdAt` e il totale `total`. I record `INFERENCE` più vecchi di 90 giorni vengono consolidati in uno per giorno.

### GET `/api/deposits`

Solo ricariche. Parametri `limit`, `offset`, `from` e `to` — come nello storico delle operazioni; nella risposta c'è `total`.

### POST `/api/deposit/gnk`

Coordinate per la ricarica GNK: `address` e `memo`. Invia GNK a questo indirizzo con questo `memo` — l'accredito è automatico.

### GET `/api/deposit/usdt/rate`

Tasso e commissione per la ricarica USDT: `gnk_usd_price`, `fee_percent`, `fee_tiers`.

### POST `/api/deposit/usdt`

Fattura per il pagamento in USDT: corpo `{"amount": 25}` — importo in dollari da 1 a 10000; nella risposta `payment_url`. Se la ricezione di USDT è temporaneamente chiusa — `503`.

### GET `/api/pricing`

Prezzi e commissioni senza chiave: `models[]`, `deposit_usdt_fee_tiers`, tasso GNK e bonus alla registrazione.

### Solo nella dashboard

La gestione dell'account è nella dashboard [gate.joingonka.ai/dashboard](https://gate.joingonka.ai/dashboard). Queste route non sono pensate per le integrazioni; alcune rispondono alla chiave API con `403 forbidden`:

- chiavi API — [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys);
- prelievo GNK — da 1 GNK;
- ricarica con carta e indirizzi dei mittenti WGNK;
- codici promozionali;
- programma referral e impostazioni delle comunicazioni.