Documentazione API

Ricariche in criptovaluta

Aggiornato a ottobre 2026

Ricarica il saldo in criptovaluta: ottieni l’indirizzo di deposito e l’importo esatto, invia esattamente quell’importo, segnala l’invio del pagamento (l’ID della transazione è facoltativo), quindi segui la ricarica fino all’accredito sul saldo. Il saldo può essere usato per acquistare qualsiasi nostro piano.

7 min di lettura

Endpoint in questa pagina

GET /v1/catalog/coins: Criptovalute e reti accettate (con il relativo indirizzo di deposito fisso)
POST /v1/topups: Avvia una ricarica crypto del saldo (indirizzo fisso, importo esatto)
POST /v1/topups/{topUpId}/txid: Segnala il pagamento come inviato (TXID facoltativo)
GET /v1/topups/{topUpId}: Ottieni una ricarica (controlla lo stato in tempo reale)
GET /v1/topups: Elenca le ricariche crypto

URL di base https://localserpproxy.com/api/v1. Per autenticazione, errori e limiti, consulta la panoramica dell’API.

Criptovalute e reti accettate (con il relativo indirizzo di deposito fisso)

GET/v1/catalog/coins

Pubblico: non serve una chiave API.

Risposta `200 OK`

{
  "data": [
    {
      "code": "BTC",
      "name": "Bitcoin",
      "networks": [
        {
          "id": "bitcoin",
          "name": "Bitcoin",
          "confirmationsRequired": 2,
          "estimatedMinutes": null,
          "memoRequired": false,
          "address": "DEPOSIT_ADDRESS"
        }
      ]
    }
  ]
}

Esempi di codice

curl

curl -s "https://localserpproxy.com/api/v1/catalog/coins"

Python

import os
import requests

API = "https://localserpproxy.com/api/v1"

r = requests.get(f"{API}/catalog/coins", timeout=30)
r.raise_for_status()
print(r.json())

Node.js

// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/catalog/coins`);
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());

Avvia una ricarica del saldo in criptovaluta (indirizzo fisso, importo esatto)

POST/v1/topups

amountUsd ≥ 25.00 USD e ≤ il massimo (10,000.00 per impostazione predefinita): 422 su amountUsd altrimenti.
coin + network deve essere uno di GET /v1/catalog/coins (409 coin_unavailable altrimenti).
Restituisce l'address fisso della rete e l'amountCrypto esatto = amountUsd / rate arrotondato per eccesso alla precisione della criptovaluta (BTC/LTC/ETH/SOL 8 decimali, USDT/USDC 6), più un piccolo scarto univoco nelle ultime cifre, così che nessuna delle ricariche aperte sulla stessa rete richieda lo stesso importo. rate è bloccato fino a expiresAt (30 minuti); txidDeadline = expiresAt + 72 h.
purchase facoltativo (stesso corpo di POST /v1/orders): convalidato e tariffato subito (422 con i nomi dei campi preceduti da purchase., 409 plan_unavailable…). amountUsd deve coprire il totale di purchase − il saldo attuale (422 too_small su amountUsd). Quando la ricarica viene accreditata, l'ordine viene effettuato dal saldo nella stessa transazione; purchase.status diventa completed (con orderId) oppure failed (failureReason; i fondi restano sul saldo).

Autenticazione: chiave API nell'intestazione Authorization: Bearer API_KEY.

Parametri

Nome	In	Tipo	Obbligatorio	Descrizione
`Idempotency-Key`	header	string	No	Chiave univoca (ad es. un UUID) per ripetere una richiesta POST in sicurezza. Conservata per 24 h. — max. 128 caratteri

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
`amountUsd`	string (USD, 2 decimals)	Sì	USD da aggiungere: ≥ 25.00, ≤ 10,000.00 per impostazione predefinita.
`coin`	string	Sì	—
`network`	string	Sì	—
`purchase`	object	No	Piano da acquistare dal saldo una volta accreditata la ricarica (stesso corpo di `POST /v1/orders`).

Esempio: Saldo

{
  "amountUsd": "50.00",
  "coin": "USDT",
  "network": "tron"
}

Esempio: Checkout

{
  "amountUsd": "25.00",
  "coin": "BTC",
  "network": "bitcoin",
  "purchase": {
    "planId": "res-10",
    "quantity": 1
  }
}

Risposta `201 Created`

{
  "id": "top_7d2kq9x1",
  "status": "verifying",
  "final": false,
  "amountUsd": "25.00",
  "coin": "USDT",
  "network": "tron",
  "address": "DEPOSIT_ADDRESS",
  "amountCrypto": "25.000137",
  "rate": "1.00",
  "paymentUri": "PAYMENT_URI",
  "expiresAt": "2026-10-05T14:33:11Z",
  "txidDeadline": "2026-10-08T14:33:11Z",
  "confirmationsRequired": 20,
  "confirmations": 7,
  "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "txidSubmittedAt": "2026-10-05T14:09:42Z",
  "amountReceivedCrypto": "25.000137",
  "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "creditedUsd": null,
  "creditedAt": null,
  "rejection": null,
  "purchase": {
    "planId": "res-10",
    "planName": "Local team",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "7.50",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}

Esempi di codice

curl

curl -s -X POST "https://localserpproxy.com/api/v1/topups" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amountUsd":"50.00","coin":"USDT","network":"tron"}'

Python

import os, uuid
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}

r = requests.post(f"{API}/topups", headers=HEADERS, json={"amountUsd": "50.00", "coin": "USDT", "network": "tron"}, timeout=30)
r.raise_for_status()
print(r.json())

Node.js

// Node.js 18+ (built-in fetch), ES module
import { randomUUID } from 'node:crypto';

const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/topups`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Idempotency-Key': randomUUID(), 'Content-Type': 'application/json' },
  body: JSON.stringify({ amountUsd: '50.00', coin: 'USDT', network: 'tron' }),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());

Segnala l'invio del pagamento (TXID facoltativo)

POST/v1/topups/{topUpId}/txid

Segnala l'invio del pagamento una volta che ha lasciato il tuo wallet o exchange: è la versione API del pulsante «Ho inviato il pagamento». L'ID della transazione (TXID) è facoltativo: invia un corpo vuoto ({}) oppure aggiungi txid se lo hai. Il pagamento viene associato a questa ricarica in base all'importo esatto (amountCrypto) sulla rete e all'indirizzo della ricarica, quindi invia esattamente tale importo.

La segnalazione è accettata mentre la ricarica è awaiting_payment, expired o rejected, e prima di txidDeadline (expiresAt + 72 h): una segnalazione tardiva non comporta mai la perdita di un pagamento. Se fornito, un txid viene verificato in base al formato della rete (422 su txid) e non deve essere associato a un'altra ricarica (409 txid_already_used). Una ricarica chiusa restituisce 409 topup_closed. La ricarica passa quindi a verifying mentre il pagamento viene verificato sulla blockchain e termina con credited una volta che la rete ha confermato la transazione, oppure con rejected (con rejection).

Autenticazione: chiave API nell'intestazione Authorization: Bearer API_KEY.

Parametri

Nome	In	Tipo	Obbligatorio	Descrizione
`topUpId`	path	string	Sì	—

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
`txid`	string	No	Facoltativo. Hash della transazione: 64 caratteri esadecimali (bitcoin, litecoin, tron), 0x + 64 caratteri esadecimali (ethereum), firma base58 (solana). Se vuoto o assente: il pagamento viene associato in base all'importo esatto. — max. 128 caratteri

Esempio: Pagamento inviato

{}

Esempio: Con il TXID (facoltativo)

{
  "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b"
}

Risposta `200 OK`

{
  "id": "top_7d2kq9x1",
  "status": "verifying",
  "final": false,
  "amountUsd": "25.00",
  "coin": "USDT",
  "network": "tron",
  "address": "DEPOSIT_ADDRESS",
  "amountCrypto": "25.000137",
  "rate": "1.00",
  "paymentUri": "PAYMENT_URI",
  "expiresAt": "2026-10-05T14:33:11Z",
  "txidDeadline": "2026-10-08T14:33:11Z",
  "confirmationsRequired": 20,
  "confirmations": 7,
  "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "txidSubmittedAt": "2026-10-05T14:09:42Z",
  "amountReceivedCrypto": "25.000137",
  "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "creditedUsd": null,
  "creditedAt": null,
  "rejection": null,
  "purchase": {
    "planId": "res-10",
    "planName": "Local team",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "7.50",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}

Esempi di codice

curl

curl -s -X POST "https://localserpproxy.com/api/v1/topups/top_7d2kq9x1/txid" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Python

import os
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.post(f"{API}/topups/top_7d2kq9x1/txid", headers=HEADERS, json={}, timeout=30)
r.raise_for_status()
print(r.json())

Node.js

// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/topups/top_7d2kq9x1/txid`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());

Ricarica il saldo (controlla lo stato in tempo reale)

GET/v1/topups/{topUpId}

Interroga questo endpoint per seguire una ricarica: ogni 10 s mentre status = verifying, ogni 30 s mentre è in attesa del pagamento e interrompi quando final = true. Una ricarica diventa expired se non viene segnalato l’invio del pagamento prima di expiresAt; è comunque possibile segnalarlo fino a txidDeadline.

Autenticazione: chiave API nell'intestazione Authorization: Bearer API_KEY.

Parametri

Nome	In	Tipo	Obbligatorio	Descrizione
`topUpId`	path	string	Sì	—

Risposta `200 OK`

{
  "id": "top_7d2kq9x1",
  "status": "verifying",
  "final": false,
  "amountUsd": "25.00",
  "coin": "USDT",
  "network": "tron",
  "address": "DEPOSIT_ADDRESS",
  "amountCrypto": "25.000137",
  "rate": "1.00",
  "paymentUri": "PAYMENT_URI",
  "expiresAt": "2026-10-05T14:33:11Z",
  "txidDeadline": "2026-10-08T14:33:11Z",
  "confirmationsRequired": 20,
  "confirmations": 7,
  "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "txidSubmittedAt": "2026-10-05T14:09:42Z",
  "amountReceivedCrypto": "25.000137",
  "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "creditedUsd": null,
  "creditedAt": null,
  "rejection": null,
  "purchase": {
    "planId": "res-10",
    "planName": "Local team",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "7.50",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}

Esempi di codice

curl

curl -s "https://localserpproxy.com/api/v1/topups/top_7d2kq9x1" \
  -H "Authorization: Bearer $API_KEY"

Python

import os
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/topups/top_7d2kq9x1", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())

Node.js

// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/topups/top_7d2kq9x1`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());

Elenca le ricariche crypto

GET/v1/topups

Autenticazione: chiave API nell'intestazione Authorization: Bearer API_KEY.

Parametri

Nome	In	Tipo	Obbligatorio	Descrizione
`page`	query	integer	No	≥ 1, predefinito `1`
`perPage`	query	integer	No	1–100, predefinito `20`
`status`	query	`awaiting_payment` · `verifying` · `credited` · `rejected` · `expired`	No	`final` = accreditata, oppure scaduta / rifiutata dopo `txidDeadline`.

Risposta `200 OK`

{
  "data": [
    {
      "id": "top_7d2kq9x1",
      "status": "verifying",
      "final": false,
      "amountUsd": "25.00",
      "coin": "USDT",
      "network": "tron",
      "address": "DEPOSIT_ADDRESS",
      "amountCrypto": "25.000137",
      "rate": "1.00",
      "paymentUri": "PAYMENT_URI",
      "expiresAt": "2026-10-05T14:33:11Z",
      "txidDeadline": "2026-10-08T14:33:11Z",
      "confirmationsRequired": 20,
      "confirmations": 7,
      "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
      "txidSubmittedAt": "2026-10-05T14:09:42Z",
      "amountReceivedCrypto": "25.000137",
      "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
      "creditedUsd": null,
      "creditedAt": null,
      "rejection": null,
      "purchase": {
        "planId": "res-10",
        "planName": "Local team",
        "quantity": 1,
        "options": {},
        "promoCode": null,
        "total": "7.50",
        "status": "pending",
        "orderId": null,
        "failureReason": null
      },
      "createdAt": "2026-10-05T14:03:11Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 1,
    "totalPages": 1
  }
}

Esempi di codice

curl

curl -s "https://localserpproxy.com/api/v1/topups" \
  -H "Authorization: Bearer $API_KEY"

Python

import os
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/topups", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())

Node.js

// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/topups`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());

Criptovalute e reti accettate (con il relativo indirizzo di deposito fisso)

Risposta 200 OK

Esempi di codice

Avvia una ricarica del saldo in criptovaluta (indirizzo fisso, importo esatto)

Parametri

Corpo della richiesta

Risposta 201 Created

Esempi di codice

Segnala l'invio del pagamento (TXID facoltativo)

Parametri

Corpo della richiesta

Risposta 200 OK

Esempi di codice

Ricarica il saldo (controlla lo stato in tempo reale)

Parametri

Risposta 200 OK

Esempi di codice

Elenca le ricariche crypto

Parametri

Risposta 200 OK

Esempi di codice

Pagine correlate

Risposta `200 OK`

Risposta `201 Created`

Risposta `200 OK`

Risposta `200 OK`

Risposta `200 OK`