Come estrarre la lista degli holder su Arc, sia di un token che di una collection

Prima di lanciare un airdrop, preparare una allowlist o chiudere l’accesso a chi è già dentro, c’è una domanda da risolvere: chi ha in mano il tuo token o la tua collection in questo momento. Per rispondere serve sapere come estrarre la lista degli holder su Arc in modo da scaricare un file con tutti gli holder di un token o NFT.

Che sia per un token o per un NFT, il processo è lo stesso. Quello che devi avere chiaro è quale snapshot ti serve e qual è il modo più semplice per sfruttarlo. In questa guida ti spiego come farlo. Partiamo subito.

Come estrarre la lista degli holder di un token su Arc passo dopo passo

Il Token Snapshot di Smithii per Arc effettua la query on-chain in modo diretto, senza dipendere da un indexer esterno né dal fatto che il token compaia in qualche elenco. Gli basta l’indirizzo del contratto, quindi funziona con qualsiasi ERC-20 della rete, che sia tuo o meno. Questa è l’interfaccia:

Individuato l’indirizzo del contratto, sono cinque passaggi:

1. Collega un wallet alla rete. Serve per pagare la fee e perché il tool possa salvarti lo storico.
2. Resta sulla scheda Token Snapshot, quella che lavora con gli ERC-20.
3. Inserisci il contratto: incolla l’indirizzo oppure cercalo per nome. Sotto il campo trovi le scorciatoie ai token più attivi sulla rete.
4. Premi Take Snapshot e approva il pagamento. L’importo compare appena sopra il pulsante prima che tu firmi.
5. Aspetta che la lettura finisca e scarica il CSV con gli indirizzi.

Come estrarre la lista degli holder di una collection su Arc senza scrivere codice

La seconda scheda è lo NFT Snapshot per collezioni di Arc, e si alterna con la precedente tramite le schede in alto. Chiede lo stesso unico dato, l’indirizzo del contratto, solo che qui parliamo di un ERC-721. Dato che la proprietà di un NFT è un’informazione pubblica, funziona con qualsiasi collezione presente su Arc. Ecco come si presenta:

La sequenza cambia poco rispetto alla precedente:

1. Collega il tuo wallet ad Arc. Senza, non c’è modo di saldare la fee né di registrare l’estrazione.
2. Posizionati sulla scheda NFT Snapshot, la seconda delle due. La prima legge ERC-20 e non riconosce le collezioni.
3. Incolla l’indirizzo del contratto ERC-721 nel campo di ricerca, oppure scrivi il nome della collezione per selezionarla dall’elenco.
4. Premi Take Snapshot e firma il pagamento. Il totale compare sotto il pulsante prima che tu confermi qualsiasi cosa.
5. Scarica il CSV quando la lettura è completata. Resta anche associato al wallet con cui hai pagato, nel caso ti serva recuperarlo.

Cosa ti restituisce ciascuna lista

Qui è dove le due schede smettono di assomigliarsi. Entrambe esportano indirizzi e nient’altro, ma il criterio con cui compongono le righe non è lo stesso, e questo determina a cosa ti serve il file.

Vale la pena capire bene la deduplicazione della seconda colonna, perché sorprende parecchia gente. Un wallet con quaranta pezzi della collezione occupa una riga, esattamente come uno che ne ha uno solo, e nel file non c’è nulla che ti dica quale dei due stai guardando.

Per una allowlist questa forma è quella giusta: l’obiettivo è riservare un posto a persona e chi ha accumulato quaranta unità non dovrebbe portarsi via quaranta slot. Per premiare in proporzione a quello che ciascuno possiede è un limite, e lo stesso ragionamento vale nella scheda dei token, dove non ci sono nemmeno saldi con cui graduare qualcosa.

I contratti escono senza etichetta in entrambe le liste

Detentore è, per la chain, l’indirizzo che risulta come tale. E dietro non sempre c’è qualcuno con cui puoi parlare.

Nella lista di un ERC-20 la liquidity pool appare come un indirizzo qualsiasi, e con essa qualunque contratto che custodisca token. In quella di una collezione il caso tipico è un altro: quando un pezzo è in vendita su un marketplace che lo custodisce durante l’annuncio, il proprietario in quel periodo è il contratto di custodia. Lo stesso succede con vault, staking e prestiti che accettano NFT come garanzia. La persona resta dietro l’operazione, ma chi compare nel file è il contratto.

Dato che nessuna delle due esportazioni include etichette, quelle righe sono indistinguibili a occhio. La verifica costa poco: cerca gli indirizzi che non ti suonano familiari nell’explorer di Arc e guarda se mostrano codice associato. Se lo mostrano, è un contratto. Vale la pena farlo prima di distribuire, perché un invio a un contratto che non sa cosa farsene di quello che riceve non lo annulla nessuno.

Decidi il cut-off prima di lanciare la lettura

Il file è una foto dello stato della chain nell’istante in cui la lanci. Non si aggiorna da solo: ogni trasferimento successivo cambia la realtà e il CSV resta com’era.

Questo pesa di più in una collezione che in un token, perché gli NFT non passano di mano a ritmo costante ma a ondate. Un annuncio, un rialzo di prezzo o un secondario che si risveglia muovono in poco tempo quello che in settimane tranquille non si muove, quindi due letture distanti un’ora possono non coincidere su una parte non trascurabile degli indirizzi.

Per questo l’ordine conta. Prima si fissa il momento del cut-off, poi si esegue la lettura. Annunciare «la foto si scatta venerdì alle 18:00» ti risparmia la lamentela prevedibile di chi ha venduto mezz’ora prima e non è entrato. E se quello che vuoi è premiare chi tiene, la via è ripetere la query: due esecuzioni distanti nel tempo, incrociate su un foglio di calcolo, ti danno la lista degli indirizzi che compaiono in entrambe.

Quanto costa fare un snapshot su Arc

62,5 USDC per esecuzione, tariffa flat e identica in entrambe le schede, più il gas della transazione. Dato che Arc addebita il gas anche in USDC, l’esborso completo resta in una sola moneta e senza conversioni di mezzo. Se il wallet non ha ancora saldo, tocca portare il USDC sulla rete prima di lanciare la lettura.

Flat significa che la dimensione non entra nel calcolo: costa uguale un token con cinquanta wallet e uno con ventimila, e uguale una serie da duecento pezzi e una da diecimila. La conseguenza è doppia. Su una base grande, ogni indirizzo ottenuto esce a un costo bassissimo, il che ribalta l’intuizione di chi arriva da strumenti che fatturano a record. In un progetto piccolo succede il contrario, quindi conviene che ogni estrazione abbia già una destinazione decisa invece di lanciarla per curiosità.

Una nota sul budget prima di procedere: se l’unico scopo della lista è una distribuzione immediata, il multisender può estrarla direttamente allo stesso prezzo e ti risparmi un passaggio. Estrarla qui a parte ha senso quando ti serve il file da conservare, riutilizzare o confrontare più avanti.

A cosa serve esportare gli holder di un token su Arc

L’assenza di saldi e di conteggi sembra una mancanza finché non guardi a cosa serve il file nella pratica. Questi tre casi non hanno bisogno di altro se non dell’indirizzo:

• Una distribuzione uniforme, in cui tutti ricevono la stessa quantità. Il CSV entra dritto nell’invio massivo di token su Arc senza dover riformattare nulla.
• Una allowlist per un mint, una prevendita o un accesso anticipato, dove l’unica cosa che conta è se un indirizzo è dentro o fuori.
• Misurare l’evoluzione della tua base. Due letture distanziate nel tempo ti dicono quanti entrano, quanti se ne vanno e chi è ancora lì fin dall’inizio.

Questo terzo utilizzo è il più sottovalutato. Confrontare due file con un foglio di calcolo ti dà la lista di chi ha resistito e quella di chi se n’è andato, che è una segmentazione eccellente e non richiede nemmeno un saldo. Su una chain appena lanciata come Arc questo tracciamento vale ancora di più, perché la base è piccola e ogni ingresso o uscita pesa.

Per onestà conviene dire anche cosa resta fuori. Non potrai distribuire per fasce, né misurare la concentrazione della supply, né sapere quale wallet accumula mezza collection. A queste tre domande risponde l’explorer della rete, che i saldi li mostra e permette di ispezionare un singolo indirizzo. Il snapshot ti dà la portata; l’explorer, il dettaglio.

FAQ

Quanto costa un snapshot di holder su Arc?

62,5 USDC per ogni estrazione, con tariffa fissa, più il gas della rete, che si paga anch’esso in USDC. Il prezzo è lo stesso nella scheda dei token e in quella delle collection, e non cambia in base al numero di holder o alla dimensione della serie.

Il CSV include i saldi o il numero di NFT di ogni wallet?

No, in nessuno dei due casi. L’esportazione di un ERC-20 contiene indirizzi senza saldo né percentuale della supply, e quella di una collection non include nemmeno token ID né il conteggio dei pezzi per proprietario. Se la tua campagna deve ponderare la ricompensa, quel dato va raccolto per un’altra via prima di impostarla.

Posso estrarre gli holder di un token o di una collection che non sono miei?

Sì. Chi possiede cosa è un’informazione pubblica on-chain, quindi basta l’indirizzo del contratto e non serve alcuna relazione con il progetto. È la strada classica per arrivare con un airdrop alla community di un progetto affine, o per studiare la dimensione reale di una base di holder.

Quale scheda mi serve, quella di token o quella di NFT?

Quella che corrisponde al tipo di contratto. Se l’asset è fungibile e la gente ne possiede una certa quantità, è un ERC-20 e va in Token Snapshot. Se ogni unità è distinta e si possiede a pezzi, è un ERC-721 e va in NFT Snapshot. Mettere un contratto nella scheda sbagliata non restituisce risultati.

Serve per distribuire un airdrop tra gli holder?

Serve, a patto che tutti ricevano la stessa quantità. Con una riga per indirizzo, il file si incastra senza ritocchi nel multisender della rete. Quello che non permette è modulare la distribuzione in base a quanto possiede ciascuno, perché quel numero nel CSV non c’è.

Posso recuperare un snapshot vecchio?

Sì, il tool tiene uno storico delle estrazioni associato al tuo wallet, quindi collegandolo rivedi tutte quelle che hai fatto. Detto questo, conviene comunque conservare ogni CSV per conto tuo, soprattutto se pensi di confrontare due liste distanziate nel tempo.

Conclusione

Ora che sai come fare un snapshot su Arc, sia per token sia per collection NFT, resta solo da decidere cosa fare con quella lista. Se stai monitorando i wallet del tuo progetto, questa informazione ti sarà utile per capire se il numero di holder è cambiato o è cresciuto, oppure per fare un airdrop di ricompensa all’interno della tua community.

Con questa aspettativa calibrata, il file copre quello che davvero gli si chiede quasi sempre: filtrare un accesso, montare una allowlist o alimentare una distribuzione uguale per tutti. Fissa il blocco di riferimento, esegui la lettura e controlla la lista prima di firmare qualsiasi cosa con essa.

Jose Araujo

Content creator e contributore SEO in Smithii. Studente di Ingegneria dei Sistemi e appassionato di crypto e tecnologia.