> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afkcrypto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AFK API v1

> Aperçu et conventions pour AFK Crypto API v1

## 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](/api-reference/supported-chains/). 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

```json theme={null}
{
  "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

<Note>
  **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.
</Note>

## 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

<CardGroup cols={2}>
  <Card title="Chaînes supportées" icon="link-simple" href="/api-reference/supported-chains/" />

  <Card title="Politiques & sécurité" icon="shield" href="/api-reference/policies-security/" />
</CardGroup>