Zerion: Wallet Intelligence for AI Agents

Zerion fournit des données de portefeuille crypto interprétées et enrichies sur 41+ chaînes incluant Ethereum, Base, Arbitrum, Optimism, Polygon, Solana, et plus.

Contrairement aux données RPC brutes, Zerion retourne :

• Valeurs en USD pour toutes les positions
• Labels de protocole (Uniswap, Aave, Lido, etc.)
• Types de transactions lisibles (swap, stake, bridge, mint, burn)
• Calculs de PnL (réalisé, non réalisé, par actif, méthode FIFO)
• Détails des positions DeFi (dépôts, emprunts, positions LP avec group_id)
• Portefeuilles NFT avec prix plancher et métadonnées de collection
• Filtrage de spam intégré

Deux façons d'accéder :

• x402 (aucun compte requis) : Payez 0,01 USDC par requête sur Base. Pas de clé API, pas d'inscription.
• Clé API : Obtenez une clé gratuite instantanément sur dashboard.zerion.io pour des limites de taux plus élevées.

Modèle Research → Execute

Zerion est la couche de recherche. Utilisez-la pour analyser les portefeuilles, trouver des opportunités, suivre le PnL. Puis confiez l'exécution à Bankr pour les transactions (swaps, stop-losses, DCA).

Zerion (Research)          Bankr (Execute)
─────────────────         ────────────────
Portfolio analysis   →    Rebalance trades
PnL tracking         →    Stop-loss orders
Position monitoring  →    Take-profit orders
Whale watching       →    Copy trades
Swap quotes          →    Execute best route
NFT floor tracking   →    Buy/sell NFTs

Démarrage rapide CLI

npm install -g zerion-cli

# Définir la clé API
export ZERION_API_KEY="zk_..."

# Ou utiliser x402 (aucune clé requise)
zerion-cli wallet portfolio 0x... --x402

# Commandes
zerion-cli wallet portfolio <address>      # Valeur USD totale
zerion-cli wallet positions <address>      # Toutes les positions de tokens
zerion-cli wallet transactions <address>   # Historique des transactions
zerion-cli wallet pnl <address>            # Profit & loss
zerion-cli wallet analyze <address>        # Analyse complète
zerion-cli chains list                     # Chaînes supportées

Endpoints Portefeuille

GET /v1/wallets/{address}/portfolio

Retourne la valeur du portefeuille agrégée sur toutes les chaînes.

curl "https://api.zerion.io/v1/wallets/0x.../portfolio?currency=usd" \
  -H "Authorization: Basic $(echo -n $ZERION_API_KEY: | base64)"

Réponse :

{
  "data": {
    "attributes": {
      "total": { "positions": 44469.60 },
      "positions_distribution_by_type": {
        "wallet": 40000,
        "deposited": 3000,
        "staked": 1469.60
      },
      "positions_distribution_by_chain": {
        "base": 27495.06,
        "ethereum": 6216.25,
        "arbitrum": 1234.56
      },
      "changes": {
        "absolute_1d": 305.86,
        "percent_1d": 0.69
      }
    }
  }
}

GET /v1/wallets/{address}/positions

Retourne tous les tokens fongibles et positions DeFi.

Paramètres de requête :

• filter[positions] : only_simple (tokens uniquement), only_defi (positions protocole), no_filter (tous)
• filter[chain_ids] : IDs de chaînes séparées par des virgules (ex. base,ethereum,arbitrum)
• filter[trash] : only_non_trash (exclure spam), only_trash, no_filter
• sort : value ou -value

Comprendre les positions LP : Les pools de liquidité retournent plusieurs positions (une par token) avec group_id partagé. Groupez par group_id pour afficher les holdings LP ensemble.

La réponse inclut :

• Symbole du token, nom, URL d'icône
• Quantité (int, float, décimales, numérique)
• Valeur en USD et prix
• Type de position : wallet, deposited, borrowed, staked, locked
• Nom du protocole et relation DApp
• group_id pour le regroupement de positions LP

GET /v1/wallets/{address}/transactions

Retourne l'historique des transactions interprétées.

Paramètres de requête :

• filter[chain_ids] : Filtrer par chaînes
• filter[asset_types] : fungible, nft
• filter[trash] : only_non_trash, no_filter
• page[size] : Résultats par page (défaut 20)
• page[after] : Curseur pour la pagination

Chaque transaction inclut :

• operation_type : trade, send, receive, approve, stake, unstake, borrow, repay, bridge, mint, burn, bid, execute
• Tableau transfers avec direction, infos token, quantités, valeurs USD
• fee avec coût gas en token natif et USD
• application_metadata avec adresse contrat et infos méthode
• Relations dapp et chain associées

GET /v1/wallets/{address}/pnl

Retourne Profit et Loss en utilisant la méthode FIFO.

Paramètres de requête :

• currency : usd (défaut)
• filter[chain_ids] : IDs de chaînes séparées par des virgules

Réponse :

{
  "data": {
    "attributes": {
      "total_gain": -15076.15,
      "realized_gain": 45328.28,
      "unrealized_gain": -60404.44,
      "relative_total_gain_percentage": -5.65,
      "relative_realized_gain_percentage": 28.08,
      "relative_unrealized_gain_percentage": -57.36,
      "total_fee": 681.81,
      "total_invested": 266672.34,
      "realized_cost_basis": 161370.01,
      "net_invested": 105302.33,
      "received_external": 128217.01,
      "sent_external": 67415.77,
      "sent_for_nfts": 4333.36,
      "received_for_nfts": 423.01
    }
  }
}

GET /v1/wallets/{address}/chart

Retourne le graphique du solde du portefeuille dans le temps.

Paramètres de requête :

• currency : usd
• filter[chain_ids] : Filtrer par chaînes
• period : Période pour le graphique

GET /v1/wallets/{address}/nft-portfolio

Retourne l'aperçu du portefeuille NFT avec valeur estimée totale.

GET /v1/wallets/{address}/nft-positions

Retourne la liste des positions NFT détenues par le portefeuille.

Paramètres de requête :

• filter[chain_ids] : Filtrer par chaînes
• sort : Ordre de tri
• Pagination supportée

GET /v1/wallets/{address}/nft-collections

Retourne les collections NFT détenues par le portefeuille avec prix plancher.

Endpoints Fungibles (Token)

GET /v1/fungibles

Retourne la liste paginée des actifs fongibles. Supporte la recherche.

Paramètres de requête :

• filter[search_query] : Rechercher par nom ou symbole
• filter[implementation_chain_id] : Filtrer par chaîne
• filter[implementation_address] : Filtrer par adresse contrat
• sort : Ordre de tri

GET /v1/fungibles/{fungible_id}

Retourne un actif fongible unique par ID.

GET /v1/fungibles/implementation/{chain}:{address}

Retourne le fongible par paire chaîne:adresse (ex. ethereum:0xa5a4...).

GET /v1/fungibles/{fungible_id}/chart

Retourne le graphique de prix pour l'actif fongible.

Paramètres de requête :

• filter[period] : hour, day, week, month, year, max

Endpoints NFT

GET /v1/nfts

Retourne la liste des NFTs avec métadonnées.

Paramètres de requête :

• Filtrage et pagination supportés

GET /v1/nfts/{nft_id}

Retourne un NFT unique par ID avec métadonnées complètes, traits et infos collection.

Endpoints DApp

GET /v1/dapps

Retourne la liste des DApps (protocoles) indexés par Zerion.

GET /v1/dapps/{dapp_id}

Retourne une DApp unique avec métadonnées, chaînes supportées et catégories.

Endpoints Chaînes

GET /v1/chains

Retourne tous les 41+ chaînes supportées avec métadonnées.

GET /v1/chains/{chain_id}

Retourne une chaîne unique par ID.

Prix du Gas

GET /v1/gas-prices

Retourne les prix du gas en temps réel sur toutes les chaînes supportées.

Utile pour :

• Estimer les coûts de transaction
• Choisir la chaîne optimale pour l'exécution
• Chronométrer les transactions pour des frais réduits

Devis Swap & Bridge

GET /v1/swap/offers

Retourne les devis swap/bridge de plusieurs fournisseurs (agrégateur).

Paramètres de requête :

• Tokens d'entrée/sortie
• Montant
• Tolérance de slippage

Retourne des devis de 0x, 1inch, Uniswap, et plus. Zerion facture 0,5 % sur les trades L2/alt-L1 (renoncé avec NFT Genesis).

Note : Le temps de réponse est 5-10 secondes en raison de l'agrégation multi-fournisseur.

GET /v1/swap/fungibles

Retourne les fongibles disponibles pour l'échange bridge (swaps inter-chaînes).

Webhooks (Abonnements)

Notifications en temps réel pour l'activité du portefeuille.

POST /v1/subscriptions/wallet-transactions

Créer un abonnement pour les transactions du portefeuille.

{
  "data": {
    "type": "subscriptions",
    "attributes": {
      "wallet_addresses": ["0x...", "0x..."],
      "chain_ids": ["base", "ethereum"],
      "callback_url": "https://your-server/webhook"
    }
  }
}

GET /v1/subscriptions

Lister tous les abonnements.

GET /v1/subscriptions/{id}

Obtenir un abonnement par ID.

DELETE /v1/subscriptions/{id}

Supprimer un abonnement.

POST /v1/subscriptions/{id}/enable

Activer un abonnement désactivé.

POST /v1/subscriptions/{id}/disable

Désactiver l'abonnement (mettre en pause les notifications).

PATCH /v1/subscriptions/{id}/wallets

Ajouter/supprimer des portefeuilles de l'abonnement.

PUT /v1/subscriptions/{id}/wallets

Remplacer tous les portefeuilles dans l'abonnement.

PUT /v1/subscriptions/{id}/callback-url

Mettre à jour l'URL de callback.

PUT /v1/subscriptions/{id}/chain-ids

Mettre à jour les chaînes surveillées.

GET /v1/subscriptions/{id}/wallets

Lister les portefeuilles dans l'abonnement.

GET /v1/subscriptions/{id}/wallets/count

Compter les portefeuilles dans l'abonnement.

Payload Webhook :

• Signé avec l'en-tête X-Signature (RSA, vérifier avec certificat)
• Inclut les en-têtes X-Timestamp et X-Certificate-URL
• Données de transaction avec interprétation complète
• Les prix sont null dans les webhooks (requêter l'endpoint transactions pour les prix)

Limites :

• Clé Dev : 1 abonnement, max 5 portefeuilles
• Production : Contacter api@zerion.io pour la liste blanche

Accès Clé API

Obtenez une clé API gratuite instantanément — sans carte de crédit requise :

1. Allez sur dashboard.zerion.io
2. Inscrivez-vous avec email ou connectez le portefeuille
3. Cliquez sur « Create API Key » — la clé commence par zk_...
4. Copiez et utilisez immédiatement

export ZERION_API_KEY="zk_your_api_key"

curl "https://api.zerion.io/v1/wallets/0x.../portfolio" \
  -H "Authorization: Basic $(echo -n $ZERION_API_KEY: | base64)"

Rate Limits

x402 n'a pas de limites de taux — payez par requête (0,01 USDC chacun).

Accès x402 (Recommandé pour les agents)

x402 permet aux agents de payer par requête sans clés API. Le paiement est 0,01 USDC sur Base.

// Utilisation du flux HTTP x402
const response = await fetch('https://api.zerion.io/v1/wallets/0x.../portfolio', {
  headers: {
    'X-402-Payment': signedPaymentHeader // Signature ERC-3009
  }
});

Avec zerion-cli :

zerion-cli wallet portfolio 0x... --x402

Support Testnet

Ajouter l'en-tête X-Env: testnet pour obtenir les données testnet :

curl "https://api.zerion.io/v1/wallets/0x.../portfolio" \
  -H "Authorization: Basic ..." \
  -H "X-Env: testnet"

Intégration avec Bankr

Exemple : PnL Guardian

Surveiller les positions et définir automatiquement les stop-losses :

#!/bin/bash
# Recherche avec Zerion
positions=$(zerion-cli wallet positions $WALLET --json)

# Trouver les tokens volatiles sur Base
risky=$(echo $positions | jq '[.data[] | select(.relationships.chain.data.id == "base") | select(.attributes.value > 500)]')

# Exécuter avec Bankr
for token in $(echo $risky | jq -r '.[].attributes.fungible_info.symbol'); do
  bankr "set stop loss on $token at -20%"
done

Exemple : Whale Copy Trading

Surveiller un portefeuille baleine et copier les trades :

// Gestionnaire webhook
app.post('/webhook/zerion', async (req, res) => {
  const { type, data } = req.body;

  if (type === 'transaction' && data.operation_type === 'trade') {
    const { transfers } = data;
    const bought = transfers.find(t => t.direction === 'in');

    if (bought && bought.value > 1000) {
      // Copier le trade via Bankr
      await bankr(`buy $100 of ${bought.fungible_info.symbol}`);
    }
  }
});

Exemple : Meilleure route de swap

Obtenir des devis de Zerion, exécuter via Bankr :

// Obtenir un devis de swap de Zerion
const quote = await zerion.get('/v1/swap/offers', {
  params: { from: 'USDC', to: 'ETH', amount: '1000' }
});

const bestRate = quote.data[0];
console.log(`Meilleur taux : ${bestRate.rate} de ${bestRate.provider}`);

// Exécuter via Bankr
await bankr(`swap $1000 USDC to ETH on base`);

Chaînes supportées

Tous les 41+ chaînes incluant :

Liste complète : https://developers.zerion.io/reference/supported-blockchains

MCP Server

Connectez Claude, Cursor, ou tout client MCP :

{
  "mcpServers": {
    "zerion": {
      "command": "npx",
      "args": ["zerion-mcp-server"],
      "env": {
        "ZERION_API_KEY": "zk_..."
      }
    }
  }
}

Gestion des erreurs

Note : Les réponses 202 signifient que les données sont en cours d'indexation. Réessayez toutes les quelques secondes jusqu'à 200. Arrêtez après 2 minutes si toujours 202.

Ressources

• Obtenir une clé API : https://dashboard.zerion.io (gratuit, instantané, pas de carte de crédit)
• Documentation API : https://developers.zerion.io
• Chaînes supportées : https://developers.zerion.io/reference/supported-blockchains
• Dépôt CLI : https://github.com/zeriontech/zerion-cli
• MCP Server : https://github.com/zeriontech/zerion-mcp-server
• Protocole x402 : https://developers.zerion.io/reference/x402
• Zerion pour agents : https://zerion.io/agents
• Filtrage de spam : https://developers.zerion.io/reference/token-spam-filtering
• FAQs : https://developers.zerion.io/reference/faqs