Passer au contenu principal

​
Vue d’ensemble

  • Chemin de base : /api/v1
  • Authentification : clé API via l’en-tête x-api-key
  • Idempotence : les opérations d’écriture requièrent l’en-tête Idempotency-Key (format UUID)
  • Format de réponse : toutes les réponses incluent l’en-tête x-request-id pour le suivi

​
Endpoints

  • GET /api/v1/wallets – Lister les portefeuilles
  • GET /api/v1/wallets/balances – Soldes du portefeuille de l’appelant (par chaîne ; portefeuille par défaut si non précisé)
  • GET /api/v1/wallets/:address/balances – Soldes pour une adresse de portefeuille détenue spécifique
  • GET /api/v1/tx/:id – Obtenir les détails d’une transaction
  • POST /api/v1/send – Envoyer des actifs natifs et des tokens (EVM + Solana)
  • POST /api/v1/token/approve – Approbation de tokens ERC20 (EVM uniquement)
  • POST /api/v1/contracts/send – Interaction générique avec des contrats (EVM uniquement)
  • POST /api/v1/trade/quote – Obtenir des cotations de swap (EVM + Solana)
  • POST /api/v1/trade/swap – Exécuter des swaps (EVM + Solana)

​
Chaînes

Voir la liste complète dans Chaînes supportées. Utilisez le slug chain (par exemple, base, solana-devnet).

​
Limitation de débit

  • Écritures (incluant POST /api/v1/trade/quote) : 15 requêtes par minute par utilisateur
  • Lectures : 60 requêtes par minute par utilisateur
  • Réponse : HTTP 429 en cas de dépassement
  • En-têtes : Retry-After (secondes restantes avant la prochaine fenêtre)

​
Idempotence (écritures)

  • Tous les endpoints mutateurs nécessitent Idempotency-Key.
  • Réutiliser une clé avec le même corps renvoie la réponse 200 originale.
  • Réutiliser une clé avec un corps différent renvoie HTTP 409 avec code: IDEMPOTENT_BODY_MISMATCH.
  • Réutiliser une clé sans succès stocké renvoie HTTP 409 avec code: IDEMPOTENT_REPLAY.
  • Les clés sont limitées à l’utilisateur authentifié ; le chemin d’endpoint est enregistré.
  • S’applique à : POST /api/v1/send, POST /api/v1/token/approve, POST /api/v1/contracts/send, POST /api/v1/trade/swap.

​
Gestion des erreurs

​
Format de réponse d’erreur

{
  "error": "Message d'erreur lisible",
  "code": "ERROR_CODE",
  "requestId": "unique-request-id"
}

​
Codes d’erreur

  • UNAUTHORIZED – Authentification manquante/invalide ou clé API (HTTP 401)
  • FORBIDDEN – Authentifié mais non autorisé à effectuer l’action (HTTP 403)
  • NOT_FOUND – Ressource introuvable (HTTP 404)
  • RATE_LIMITED – Limite de débit dépassée (HTTP 429)
  • INVALID_INPUT – Paramètres de requête invalides (HTTP 400)
  • WALLET_NOT_FOUND – Portefeuille spécifié introuvable
  • USER_NOT_LINKED – Utilisateur non lié à Privy
  • WALLET_NOT_DELEGATED – Portefeuille non délégué au signataire serveur
  • WALLET_ID_REQUIRED – ID de portefeuille Privy manquant
  • CHAIN_UNKNOWN – Chaîne inconnue ou non supportée
  • INSUFFICIENT_FUNDS – L’expéditeur manque de fonds pour la valeur/frais
  • IDEMPOTENT_BODY_MISMATCH – Corps de requête différent avec la même clé d’idempotence (HTTP 409)
  • IDEMPOTENT_REPLAY – Clé d’idempotence déjà utilisée (HTTP 409)
  • PRIVY_RPC_ERROR – Erreur du service RPC Privy
  • SEND_FAILED – Échec de soumission de transaction
  • SERVICE_UNAVAILABLE – Service requis non configuré
  • QUOTE_FAILED – Erreur du service de cotation (HTTP 400)
  • INTERNAL_ERROR – Erreur serveur
Détails QUOTE_FAILED :
  • Solana/Jupiter : Certains mints Solana ne sont pas échangeables sur Jupiter (liste autorisée). Dans ces cas, cette API renvoie HTTP 400 avec code: QUOTE_FAILED et un message d’erreur comme : “Token not tradable on Jupiter”.
  • EVM/1inch : Si un token n’est pas pris en charge par 1inch, l’API renvoie HTTP 400 avec code: QUOTE_FAILED et un message comme : “Token not tradable on 1inch”.
  • Ceci est attendu lorsque le token/mint de sortie demandé est marqué comme non échangeable par le fournisseur en amont, même si des pools existent ailleurs.

​
Validation

​
Formats d’adresse

  • EVM : doit correspondre à /^0x[a-fA-F0-9]{40}$/
  • Solana : doit être une clé publique base58 valide

​
Paramètres communs

  • Montants (EVM) : Chaînes entières uniquement (décimal ou 0x-hex). Doivent être non négatifs. Pour ERC20 et value, doivent tenir dans uint256.
  • Montants (Solana) : Chaînes entières en unités de base. Les montants SPL doivent tenir dans une plage non signée de 64 bits.
  • Expéditeur (from) : Optionnel. Si omis, le portefeuille par défaut de l’utilisateur pour la chaîne spécifiée est utilisé.
  • Idempotence : Tous les endpoints d’écriture nécessitent l’en-tête Idempotency-Key. Les répétitions avec le même corps renvoient la réponse originale.

​
Mot-clé de token natif

Les endpoints de trading (/api/v1/trade/quote, /api/v1/trade/swap) acceptent le mot-clé NATIVE (insensible à la casse) pour fromToken/toToken :
  • EVM : NATIVE se résout en 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
  • Solana : NATIVE se résout au mint SOL encapsulé So11111111111111111111111111111111111111112
  • Les réponses renvoient les adresses résolues (pas NATIVE)
  • L’endpoint d’envoi utilise asset: "native" au lieu des adresses de tokens pour les transferts natifs

​
Conventions

  • Sélection de chaîne : utilisez le slug chain (par ex., base, base-sepolia, solana-devnet).
  • Mappage sentinelle de Transaction.chainId (Solana) : 0 = mainnet, -2 = testnet, -3 = devnet.
  • Idempotence : unique par utilisateur et clé ; répétitions → réponse originale ; corps différent → 409.

​
Liens

Chaînes supportées

Politiques & sécurité