Guida alla migrazione pUSD di Polymarket: da USDC.e a pUSD (aprile 2026)

Capitolo 36 di 36

La versione breve

Il 28 aprile 2026, Polymarket ha migrato la sua garanzia di regolamento su Polygon da USDC.e (il token USDC tramite bridge, contratto 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174) a pUSD, una stablecoin emessa da Polymarket riscattabile 1:1 in USDC nativo. I trader della web app non hanno fatto nulla - saldi e posizioni si sono convertiti automaticamente al blocco snapshot. Gli operatori di API e bot devono aggiornare: l'indirizzo dell'asset di garanzia all'interno di ogni firma di ordine CLOB è cambiato, i vecchi ordini firmati contro USDC.e sono stati annullati, ed è richiesto py-clob-client 0.40 o più recente. Questa guida illustra le modifiche esatte di codice, contratto e approvazioni necessarie per mantenere un bot in funzione durante e dopo il passaggio.

Parte 1: Tre stablecoin, un solo Polygon

Prima della migrazione, tre stablecoin USD esistevano nell'orbita di Polymarket su Polygon. Conoscere la differenza è il primo passo per capire perché Polymarket ha cambiato sede.

Polymarket scelse originariamente USDC.e perché era la variante USDC dominante su Polygon al lancio nel 2020. Circle ha poi emesso USDC nativo direttamente su Polygon e ha segnalato l'eventuale dismissione della variante tramite bridge. Continuare a regolare ogni mercato in USDC.e esponeva Polymarket al rischio di coda di una chiusura improvvisa del bridge. Migrare a una stablecoin controllata da Polymarket risolve questo e sblocca future funzioni di prodotto (es. margine dei perp, depositi in vault, ricevute cross-chain) che condividono la stessa unità di conto.

Parte 2: Cos'è pUSD (e cosa non è)

pUSD è un token ERC-20 standard su Polygon (chain id 137) con 6 decimali, la stessa precisione di USDC. È coniabile solo dal contratto della Tesoreria Polymarket ed è riscattabile 1:1 in USDC nativo in qualsiasi momento, senza commissioni sulla conversione (il gas di rete si applica comunque). La riserva a garanzia di pUSD è detenuta in conti segregati e rendicontata mensilmente con un'attestazione di terze parti.

pUSD non è una stablecoin algoritmica, non è sovra-collateralizzata con crypto e non è fruttifera. Se detieni pUSD al di fuori di Polymarket, dovresti considerarla un pagherò emesso da Polymarket per USDC nativo - utile dentro la piattaforma, riscattabile su richiesta, ma senza alcun vantaggio nel detenerla a lungo termine in un wallet esterno.

Parte 3: Cosa hanno visto i trader della web app

Se tradi solo tramite polymarket.com, la migrazione è stata invisibile. Al blocco snapshot del 28 aprile 2026:

• Ogni saldo USDC.e detenuto in un wallet proxy di Polymarket è stato convertito atomicamente in pUSD a 1:1.
• Le posizioni aperte hanno mantenuto lo stesso valore in dollari, le stesse quote di esito e la stessa scadenza. Gli ID dei token condizionali non sono cambiati.
• Gli ordini a riposo denominati in USDC.e sono stati annullati allo snapshot. I nuovi ordini post-migrazione firmano automaticamente contro pUSD.
• I prelievi verso wallet esterni sono passati dall'invio di USDC.e all'invio di USDC nativo (o, su richiesta, pUSD grezzo - la maggior parte degli utenti non ne ha mai bisogno).

Non è stata richiesta alcuna firma, transazione o modifica delle impostazioni. Gli ordini limite a riposo che ti interessavano dovrebbero essere ripiazzati manualmente dopo la migrazione; l'annullamento è stato un evento una tantum.

Parte 4: Operatori di API e bot - modifiche critiche

Questa è la parte che romperà un bot se non agisci.

Aggiorna py-clob-client

Polymarket ha pubblicato py-clob-client 0.40.0 due settimane prima del passaggio con pieno supporto a pUSD. La linea 0.34.x è stata ritirata il giorno dopo la migrazione.

# Passa a una release compatibile con pUSD
pip install --upgrade "py-clob-client>=0.40.0"

# Verifica l'asset di garanzia collegato
python -c "from py_clob_client.constants import POLYGON; \
print('pUSD address:', POLYGON.get('collateral'))"

Il nuovo SDK ricava l'indirizzo della garanzia dalla configurazione della chain all'avvio, quindi non hai bisogno di codificare nulla a mano. Se hai forkato o fissato una versione più vecchia, la mossa più sicura è eliminare il lockfile, reinstallare con l'ultimo modulo constants e rieseguire la tua suite di test.

Riapprova le allowance

Il tuo wallet proxy di Polymarket ha bisogno di un'allowance ERC-20 dal tuo account di trading → contratto CTF Exchange per il token pUSD. La vecchia allowance per USDC.e è ancora on-chain ma completamente inutile: il CLOB non la consumerà. Senza una nuova allowance pUSD, ogni ordine restituisce "INSUFFICIENT_ALLOWANCE".

from py_clob_client.client import ClobClient

client = ClobClient(
    host="https://clob.polymarket.com",
    chain_id=137,
    key=os.environ["POLY_PRIVATE_KEY"],
    funder=os.environ["POLY_FUNDER"],
    signature_type=1,  # POLY_PROXY per account Magic-link
)
client.set_api_creds(client.create_or_derive_api_creds())

# Una tantum: approva pUSD per il contratto CTF Exchange
# (Helper aggiunto in py-clob-client 0.40)
client.update_balance_allowance(asset_type="COLLATERAL")

Aggiorna le credenziali API

Le chiavi API esistenti continuano a funzionare, ma se hai derivato le credenziali prima del 1° aprile dovresti ruotarle per precauzione: la firma ECDSA L1 ora si lega a un dominio che include il nuovo indirizzo della garanzia. Il percorso più semplice:

creds = client.create_or_derive_api_creds()  # ri-derivazione idempotente
client.set_api_creds(creds)

# Salva nel tuo .env
print(creds.api_key, creds.api_secret, creds.api_passphrase)

Parte 5: Verificare il tuo bot dopo la migrazione

Esegui questo smoke test minimale prima di lasciare libera qualsiasi logica di dimensionamento su denaro reale:

# 1. Conferma il saldo pUSD sul wallet proxy
from py_clob_client.client import ClobClient
client = ClobClient(...)  # come sopra
balance = client.get_balance_allowance(params={"asset_type": "COLLATERAL"})
print("pUSD balance (raw):", balance["balance"])
print("Allowance to exchange:", balance["allowance"])

# 2. Piazza un ordine limite da $1 ben lontano dal touch
from py_clob_client.clob_types import OrderArgs
order = client.create_order(OrderArgs(
    token_id=test_token_id,
    price=0.05,        # per niente vicino al mercato
    size=20,           # $1 nozionale a $0,05
    side="BUY",
))
resp = client.post_order(order)
print(resp)

# 3. Annulla e conferma
client.cancel(order_id=resp["orderID"])

Se tutte e tre le chiamate hanno successo, il tuo collegamento è a posto: l'SDK ha firmato contro pUSD, l'allowance è riconosciuta e il registro degli ordini è coerente. Riscala gradualmente.

Parte 6: Errori comuni e soluzioni

Parte 7: Token condizionali, ID degli ordini e altre cose che non sono cambiate

Per mantenere onesto l'ambito del refactoring, ecco la lista degli identificatori che sono stabili attraverso la migrazione:

• Contratto dei token condizionali (CTF): indirizzo identico. Le tue posizioni ERC-1155 SÌ / NO non sono state toccate.
• condition_id e question_id: deterministici dai parametri del mercato; non influenzati dallo swap di garanzia.
• token_id (esito): derivato da condition_id + indice dell'esito; invariato.
• Indirizzo del wallet proxy di Polymarket: stesso indirizzo; stesso codice in stile Gnosis Safe.
• Chiave API, secret API, passphrase API: ancora valide (consigliata la rotazione; non richiesta).
• Schemi WebSocket: identici; il nuovo campo asset riporta "pUSD" invece di "USDC.e" negli eventi di esecuzione.
• Gamma e Data API: non autenticate, invariate. Non hanno mai fatto riferimento direttamente al token di garanzia.

Parte 8: Implicazioni fiscali e contabili

Per la maggior parte delle giurisdizioni la conversione automatica di USDC.e in pUSD è uno swap simile di stablecoin ancorate al dollaro a 1:1 e non produce alcun evento tassabile. Il tuo costo base e il periodo di detenzione si trasferiscono.

Detto ciò, due voci contabili meritano attenzione:

1. Aggiorna lo schema del tuo registro. Qualsiasi strumento fiscale, registro SQLite o export per il commercialista che filtra le transazioni Polygon in base al contratto USDC.e mancherà silenziosamente ogni transazione post-migrazione. Aggiungi l'indirizzo del contratto pUSD come alias.
2. Annota la conversione dello snapshot. Anche se non è tassabile nella maggior parte dei regimi, registra la conversione esplicitamente nei tuoi atti: importo, blocco, timestamp e una nota che si tratta di una migrazione di stablecoin a 1:1. Se la tua giurisdizione la indaga più avanti, vorrai una traccia di audit pulita.

I trader italiani dovrebbero consultare la Guida fiscale per la rendicontazione specifica; la migrazione in sé non cambia il trattamento standard ma il cambio dell'indirizzo del contratto conta per gli strumenti di rendicontazione automatica.

Parte 9: Consigli pro dagli operatori che hanno vissuto il passaggio

Cosa viene dopo?

• Guida all'API di Polymarket - la guida API completa, aggiornata per pUSD
• Guida al deposito - depositare USDC e ricevere pUSD dentro l'app
• Guida al prelievo - prelevare pUSD come USDC nativo verso un wallet esterno
• Strumenti e risorse - dashboard di terze parti ora aggiornate per pUSD
• Glossario - definizioni in parole semplici per ogni termine usato qui