Comment vérifier le solde du jeton par adresse de portefeuille ?

Requêtes de solde directes spécifiques à la chaîne

1. Les utilisateurs peuvent récupérer les soldes de jetons en soumettant une requête GET à /balance/{chain}/{address} , où {chain} est l'une des sept blockchains prises en charge et {address} est la chaîne hexadécimale du portefeuille.

2. Le point de terminaison renvoie le solde de jetons natif et les avoirs en jetons ERC-20/BEP-20/SPL, en fonction des normes contractuelles spécifiques à la chaîne et de la couverture de l'indexeur.

3. Les réponses de Solana incluent les comptes de jetons SPL mappés au portefeuille, tandis qu'Ethereum et Base renvoient les soldes d'ETH et de jetons via l'agrégation multiappel.

4. Les requêtes Hedera renvoient uniquement le solde HBAR natif ; Les jetons HTS nécessitent une interaction contractuelle distincte non couverte par ce point de terminaison.

5. Les réponses Bitcoin reflètent l'équilibre BTC basé sur UTXO sans prise en charge du RVB ou d'autres couches de tokenisation.

Exigences d'authentification

1. Chaque demande de solde doit inclure un en-tête X-API-Key contenant un identifiant valide délivré par AgentHustle AI.

2. Les clés sont limitées à des chaînes et à des autorisations spécifiques : tenter d'interroger BSC avec une clé Ethereum uniquement aboutit à HTTP 403.

3. Des limites de débit s'appliquent par clé : 60 requêtes par minute sur tous les points de terminaison, appliquées au niveau de la passerelle API.

4. Les clés invalides ou expirées déclenchent HTTP 401 avec un corps JSON indiquant « invalid_api_key » ou « key_expired ».

5. Aucun cookie de session ou flux OAuth n'est impliqué ; l'authentification est sans état et basée sur l'en-tête.

Structure de réponse et champs de données

1. Les réponses réussies utilisent HTTP 200 et contiennent un champ d'équilibre de niveau supérieur exprimé sous la forme d'un entier chaîne en unités de base (par exemple, wei pour ETH, lamports pour SOL).

2. Un tableau de jetons répertorie les actifs non natifs, chacun avec contractAddress , symbol , decimals et rawBalance .

3. Le champ lastUpdated indique l'horodatage Unix en millisecondes, aligné sur le dernier bloc synchronisé de l'indexeur de blockchain sous-jacent.

4. Pour les portefeuilles ne contenant aucun jeton au-delà de la devise native, le tableau des jetons reste présent mais vide.

5. Toutes les valeurs numériques sont fournies sous forme de chaînes pour éviter toute perte de précision en virgule flottante lors de la sérialisation JSON.

Intégration de la résolution de noms ENS

1. Les noms ENS comme vitalik.eth peuvent être utilisés directement à la place des adresses hexadécimales lorsque le service de résolution est activé.

2. L'API effectue automatiquement une recherche inversée via le registre ENS du réseau principal Ethereum avant de transmettre la requête au point de terminaison de solde spécifique à la chaîne.

3. La résolution échoue silencieusement si le nom ne se résout pas en une adresse ou pointe vers un format de somme de contrôle non valide.

4. Les TLD ENS pris en charge incluent .eth, .xyz et .luxe ; .com et .org ne sont pas traités sauf s'ils sont enregistrés dans des résolveurs compatibles ENS.

5. Les intégrations PayPal et Venmo autorisent les transferts PYUSD en utilisant les noms ENS, mais les vérifications de solde restent natives de la chaîne et ne reflètent pas les soldes de paiement hors chaîne.

Foire aux questions

Q : Puis-je vérifier les soldes des portefeuilles sur des chaînes non prises en charge comme Cardano ou Avalanche ? R : Non. Le point de terminaison prend uniquement en charge Solana, Ethereum, Base, BSC, Polygon, Hedera et Bitcoin. Les requêtes pour d'autres chaînes renvoient HTTP 400 avec le code d'erreur « unsupported_chain ».

Q : L'API détecte-t-elle les jetons enveloppés comme wBTC ou wETH dans les portefeuilles Ethereum ? R : Oui. Les jetons emballés adhérant aux normes ERC-20 apparaissent dans le tableau des jetons avec leur symbole, leurs décimales et leur solde brut corrects.

Q : Que se passe-t-il si un portefeuille a un solde nul sur tous les actifs ? R : La réponse inclut le solde : « 0 » et un tableau de jetons vide. Le statut HTTP reste 200.

Q : Existe-t-il un moyen de vérifier par lots plusieurs adresses en une seule demande ? R : Pas nativement. Chaque adresse nécessite une requête HTTP distincte. Les clients doivent implémenter une logique de parallélisation ou de file d’attente en externe.