Règlements automatiques

En résumé
Les Règlements automatiques convertissent automatiquement les dépôts entrants vers l’actif de votre choix sur n’importe quelle blockchain. Définissez les règles une seule fois, et tous les dépôts correspondants sont échangés et acheminés vers votre chaîne de destination — sans aucune intervention manuelle.

Prérequis

Avant de configurer des règles de règlement automatique, assurez-vous de disposer des éléments suivants :

Clé API

Obtenez votre clé API depuis le tableau de bord Blockradar. Rendez-vous dans Developers pour en générer une.

Master Wallet créée

Créez une master wallet depuis le tableau de bord Blockradar. Les règles se configurent par wallet — consultez-en une avec Get Wallet.

Wallet de destination

Si vous effectuez un règlement cross-chain, assurez-vous d’avoir une wallet sur la blockchain de destination pour recevoir les actifs convertis.

Gas suffisant

Approvisionnez vos wallets en tokens natifs (ETH, BNB, MATIC, etc.) pour couvrir les frais de swap et de transfert.

Webhook configuré

Configurez des webhooks pour recevoir les notifications de règlement. La famille d’événements dépend du type de règlement exécuté : swap.*, withdraw.*, gateway-deposit.* ou reward-deposit.*. Consultez Notifications par webhook ci-dessous et le guide Webhooks pour plus de détails.

Fonctionnement

Les Règlements automatiques vous permettent de convertir automatiquement les dépôts entrants en n’importe quel actif de destination, sur n’importe quel réseau blockchain, en fonction des règles que vous configurez. Cela évite d’avoir à effectuer manuellement des swaps ou bridges d’actifs et garantit que votre trésorerie peut être convertie automatiquement vers vos actifs préférés sur plusieurs chaînes.

Gestion des règles

Créez et gérez des règles de règlement automatique pour automatiser les conversions d’actifs.

Conversion d'actifs

Convertissez automatiquement n’importe quel stablecoin vers tout autre actif selon vos règles.

Cross-Chain

Réglez vos actifs sur n’importe quel réseau blockchain de manière transparente.

Gestion du risque

Appliquez des tolérances de slippage et des règles pour vous protéger contre des exécutions défavorables.

Comment fonctionnent les Règlements automatiques

1. Création des règles

Définissez des règles de règlement précisant quand et comment les dépôts doivent être convertis automatiquement.

2. Détection des dépôts

Lorsque des fonds arrivent sur vos adresses, Blockradar détecte automatiquement les dépôts correspondant à vos règles.

3. Conversion d’actifs

Les dépôts sont automatiquement échangés vers votre actif de destination (typiquement USDC) sur la chaîne choisie.

4. Unification des soldes

Tous les actifs convertis sont consolidés en un solde unique et unifié sur votre chaîne de destination.

Types de règlement

Chaque règle se résout en l’un des quatre flux de règlement. Définissez-le explicitement avec le champ type :

Type	Ce que fait la règle	Champ associé obligatoire
`withdraw`	Transfère l’actif source tel quel vers `destination.address` sur la même blockchain. Sans conversion.	`destination.address`, et `destination.blockchain` doit être identique à la blockchain source
`swap`	Convertit vers un actif différent et/ou vers une autre blockchain.	Les actifs sources doivent différer de l’actif de destination lorsque les deux sont sur la même chaîne
`gateway`	Dépose des USDC dans le solde unifié Gateway de Circle.	`isGateway: true`
`earn`	Dépose dans une position Earn avec Fija ou Aave.	`isReward: true`

type est facultatif pour des raisons de rétrocompatibilité. Les règles créées avant l’existence de ce champ n’ont pas de type et conservent leur comportement déduit : Blockradar tranche entre withdraw et swap en comparant l’actif et la chaîne de source et de destination. Envoyez type sur chaque nouvelle règle pour rendre le flux explicite, et envoyez-le lors d’une mise à jour pour migrer une règle héritée vers le système explicite.

Sur une child address, type n’est pas qu’une indication. Si vous créez une règle sur une child address sans type, les champs étendus — isReward, rewardProvider, rewardType, useTransactionAmount et deductionPercentage — sont supprimés silencieusement et la règle est enregistrée au format hérité. Envoyez toujours type lors de la création de règles sur des child addresses.

Règles de validation par type

L’API rejette les combinaisons contradictoires :

type: gateway exige isGateway: true, et isGateway: true exige type: gateway
type: earn exige isReward: true, et isReward: true exige type: earn
Une règle ne peut jamais être à la fois gateway et earn
type: withdraw exige une destination.address, et la blockchain de destination doit être identique à celle de la source
type: swap rejette un actif source identique à l’actif de destination sur la même blockchain
Deux règles de la même wallet ne peuvent pas couvrir le même actif source sur la même blockchain

Les règles gateway peuvent basculer vers un swap

Une règle gateway n’effectue un dépôt Gateway que lorsque la chaîne et l’actif source sont éligibles à Gateway. Dans le cas contraire, la règle bascule et s’exécute comme un swap vers destination.blockchain / destination.asset. Les fonds sont réglés malgré tout, mais vous recevez des webhooks swap.* plutôt que gateway-deposit.* ; prévoyez donc les deux lorsque vous configurez des règles gateway sur des chaînes hors du périmètre pris en charge par Gateway.

Règles de Règlement automatique

Composants d’une règle

Chaque règle de règlement automatique définit les paramètres suivants :

Composant	Description	Exemple
Type	Flux de règlement de la règle	withdraw, swap, gateway, earn
Nom de la règle	Nom descriptif pour votre règle de règlement	« Swap from USDC to Optimism USDC »
Order	Préférence de routage pour l’étape de swap. Ignoré pour les règles gateway et earn	FASTEST, CHEAPEST, RECOMMENDED, NO_SLIPPAGE
Tolérance de slippage	Écart de prix maximal acceptable (%). Utilisez `-1` pour un slippage illimité	5 ou -1
Actifs sources	Liste d’actifs à régler automatiquement	[“USDC”, “USDT”]
Montant min./max. source	Contrôle la taille du dépôt qui déclenche le règlement	Min : 1 $, Max : 1 000$
Blockchain de destination	Réseau blockchain cible	optimism, base, ethereum
Actif de destination	Actif cible pour la conversion	USDC, USDT, cNGN, DAI
Adresse de destination	(Facultatif sauf pour les règles withdraw) Adresse spécifique pour recevoir les actifs convertis. Si elle n’est pas fournie, la logique de fallback intelligente s’applique	0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22
Is Gateway	Achemine le règlement via Gateway de Circle	false
Is Reward	Achemine le règlement vers une position Earn	false
Use Transaction Amount	Régler le montant du dépôt déclencheur plutôt que le solde de l’adresse	false
Deduction Percentage	Pourcentage retenu sur le montant réglé	”0”
Inheritance	Les child addresses auxquelles une règle de la master wallet se propage	`{ "mode": "all_children" }`

Quel montant est réglé

Par défaut, le montant d’un règlement est calculé à partir du solde de l’adresse, et non du dépôt qui l’a déclenché. Utilisez useTransactionAmount pour choisir :

`useTransactionAmount`	Ce qui est réglé
`false` (par défaut)	Le solde actuel de l’actif source sur l’adresse, qui peut dépasser le dépôt ayant déclenché la règle, par exemple lorsque des dépôts antérieurs sont restés non réglés
`true`	Uniquement le montant du dépôt qui a déclenché la règle

Le montant est ensuite ajusté dans cet ordre :

Il est comparé à source.minAmount. En dessous, rien n’est réglé.
Il est plafonné à source.maxAmount ("-1" signifie sans plafond).
deductionPercentage est retenu sur le reste. "2.5" règle 97,5 % et laisse 2,5 % sur l’adresse.

Utilisez useTransactionAmount: true lorsque chaque dépôt doit correspondre exactement à un règlement, par exemple pour un rapprochement paiement par paiement. Laissez-le à false lorsque vous souhaitez vider l’adresse à chaque fois.

Règles de règlement vers Earn

Une règle earn dépose les fonds entrants dans une position de rendement au lieu de les transférer vers l’extérieur. C’est le point d’entrée du règlement automatique vers Earn.

Champ	Valeur
`type`	`earn`
`isReward`	`true`
`rewardProvider`	`fija` ou `aave`
`rewardType`	`regulated` pour `fija`, `defi` pour `aave`

Contraintes :

Mainnet uniquement. Les règles earn sont rejetées sur testnet.
Chaque actif de source.assets doit être pris en charge par le fournisseur choisi sur la blockchain de la wallet, sinon la règle est rejetée à la création.
rewardProvider et rewardType doivent concorder : fija est toujours regulated et aave est toujours defi.
Une règle ne peut pas être à la fois isGateway et isReward.

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "type": "earn",
    "name": "Earn on Base USDC deposits",
    "isReward": true,
    "rewardProvider": "aave",
    "rewardType": "defi",
    "source": {
        "assets": ["USDC"],
        "minAmount": "10",
        "maxAmount": "-1"
    },
    "destination": {
        "blockchain": "base",
        "asset": "USDC"
    }
}'

Les règlements vers Earn créent une transaction REWARD_DEPOSIT et émettent des webhooks reward-deposit.*.

Les règles earn basées sur le solde (useTransactionAmount: false) ignorent un nouveau règlement tant qu’un règlement est déjà en attente ou en cours pour la même adresse et le même actif, car le règlement en cours absorbera de toute façon les fonds nouvellement arrivés. Les règles earn basées sur le montant (useTransactionAmount: true) ne sont jamais ignorées.

Options de configuration de la règle

Seuils de montant

Montant minimum : Ne régler que lorsque le montant dépasse ce seuil
Montant maximum : Plafonner la taille des règlements individuels
Accumulation : Avec useTransactionAmount: false (la valeur par défaut), la règle règle l’intégralité du solde de l’actif source sur l’adresse, si bien que les dépôts individuellement inférieurs à minAmount sont repris ensemble dès que le solde le dépasse

Protection contre le slippage

Illimité : -1 (pas de limite de slippage)
Conservateur : 0,1 % - 0,5 % (impact minimal sur le prix)
Modéré : 0,5 % - 1,0 % (approche équilibrée)
Agressif : 1,0 % - 2,0 % (exécution plus rapide)

Avant l’exécution, le règlement récupère une cotation et compare son slippage à votre tolérance. Si la cotation dépasse la tolérance, le règlement échoue au lieu de s’exécuter à un cours moins favorable.

Envoyez toujours slippageTolerance explicitement sur les règles de swap. "-1" signifie illimité, et une valeur telle que "5" signifie 5 %. Une tolérance de "0" n’autorise qu’un règlement à slippage exactement nul, ce qui rejette la quasi-totalité des cotations réelles. Les règles gateway et earn n’utilisent pas la tolérance de slippage.

Adresse de destination (facultative)

Le champ destination.address est facultatif pour les règles swap, gateway et earn. Lorsqu’il n’est pas fourni, le système utilise une logique de fallback intelligente pour déterminer l’adresse destinataire :

Scénario	Comportement de fallback
Adresse explicite fournie	Utilise l’adresse spécifiée
Règlement sur la même chaîne	Utilise l’adresse de dépôt (adresse source)
Cross-chain entre EVM	Utilise la même adresse sur la chaîne de destination
Cross-chain (destination non EVM)	Utilise l’adresse de la master wallet sur la chaîne de destination

Pour la plupart des cas d’usage, vous pouvez omettre l’adresse de destination et laisser le système acheminer automatiquement les fonds vers l’adresse appropriée selon le type de règlement.

Les règles withdraw font exception : elles exigent une destination.address explicite, et destination.blockchain doit être la même blockchain que la source. destination.blockchain et destination.asset sont toujours obligatoires, quel que soit le type de règle.

Préférences d’exécution

Fastest : Privilégie la vitesse au détriment du coût
Cheapest : Optimise pour les frais les plus bas
Recommended : Équilibre vitesse, coût et fiabilité
No Slippage : N’exécute que lorsqu’il n’y a aucun écart de prix

Hiérarchie et précédence des règles

Comment les règles s’appliquent

Concept clé : Par défaut, les règles créées sur une master wallet s’appliquent à la master wallet et à toutes les child addresses qui en dépendent. Une règle posée sur une child address prime sur les règles de la master wallet pour le dépôt auquel elle correspond.

Niveau de la règle	Portée	Comportement
Règles de Master Wallet	La master wallet, plus les child addresses sélectionnées par le réglage `inheritance` de la règle (toutes par défaut)	Règles par défaut pour la hiérarchie de la wallet
Règles de Child Address	Uniquement cette adresse spécifique	Priment sur les règles de la master wallet pour tout dépôt auquel elles correspondent

Ordre d’application des règles

La précédence s’évalue par dépôt, et non par adresse :

Chercher une règle correspondante sur la child address. Une règle correspond lorsqu’elle est active et que ses champs source.assets et source.blockchain couvrent le dépôt.
Se rabattre sur les règles de la master wallet. Une règle de la master wallet n’est alors considérée que si son réglage inheritance lui permet de s’appliquer à l’adresse qui a reçu le dépôt.
Aucune correspondance à l’un ou l’autre niveau : aucun règlement automatique n’a lieu.

Le fait qu’une child address possède certaines règles ne désactive pas les règles de la master wallet pour cette adresse. Si aucune des règles de la child address ne correspond à l’actif et à la chaîne déposés, les règles de la master wallet sont évaluées ensuite. Pour empêcher une règle de la master wallet d’atteindre une adresse, définissez explicitement l’inheritance de cette règle, comme expliqué ci-dessous.

Héritage par règle

Chaque règle de la master wallet contrôle les child addresses auxquelles elle se propage via l’objet facultatif inheritance :

`mode`	La règle s’applique à
`all_children`	La master wallet et toutes les child addresses
`master_only`	La master wallet uniquement — cette règle ignore les dépôts sur les child addresses
`selected_children`	La master wallet plus les adresses précises listées dans `childAddressIds`

Omettre entièrement inheritance conserve le comportement d’origine et équivaut à all_children.

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "type": "swap",
    "name": "Settle USDT deposits from partner addresses",
    "slippageTolerance": "1",
    "inheritance": {
        "mode": "selected_children",
        "childAddressIds": [
            "0f9a1c3e-58c2-4a1b-9f0d-6d5f2a7c1b34",
            "7b3d9e21-4f6a-4c0e-8a52-1c9b0e4d7f88"
        ]
    },
    "source": {
        "assets": ["USDT"],
        "minAmount": "1",
        "maxAmount": "-1"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC"
    }
}'

Règles applicables à selected_children :

childAddressIds doit être présent et non vide, faute de quoi la requête échoue avec At least one child address must be selected.
Chaque ID doit être une adresse active appartenant à votre entreprise sur le même réseau.
Les adresses doivent appartenir à la même famille de chaînes que la wallet. Une règle sur une wallet non EVM (Tron, Solana ou Stellar par exemple) n’accepte que des adresses de cette même chaîne ; une règle sur une wallet EVM accepte n’importe quelle adresse EVM. Une incohérence échoue avec One or more selected child addresses are not valid for this chain or are inactive.

inheritance n’existe que sur les règles de la master wallet. Une règle créée directement sur une child address n’a rien à quoi se propager : le champ est donc ignoré et n’y est jamais enregistré.

Règles spécifiques à une blockchain

Important : Les règles sont isolées et liées à chaque blockchain. Une règle configurée pour une blockchain (par exemple Ethereum) n’affectera PAS les dépôts sur une autre blockchain (par exemple Base ou Optimism).

Cela signifie que :

Vous devez créer des règles distinctes pour chaque blockchain source à régler automatiquement
Une règle pour « USDC sur Ethereum » ne se déclenchera pas pour « USDC sur Base »
Cela permet un contrôle granulaire du comportement de règlement par chaîne

Exemple : Si vous souhaitez régler automatiquement les dépôts USDC depuis Ethereum et Base vers Optimism, vous avez besoin de deux règles distinctes :

Règle pour Ethereum USDC → Optimism USDC
Règle pour Base USDC → Optimism USDC

Cas d’usage pour chaque niveau

Règles de Master Wallet

Stratégie cohérente : Même comportement de règlement sur toutes les child addresses
Gestion simplifiée : Un seul endroit pour configurer le comportement par défaut
Opérations en masse : Appliquer des règles à plusieurs adresses à la fois
Standardisation : Garantir conformité et cohérence

Règles de Child Address

Tests : Essayer différentes stratégies de règlement sur des adresses spécifiques
Exigences personnalisées : Besoins de règlement spécifiques à une adresse
Surcharger les valeurs par défaut : Modifier le comportement pour des cas d’usage particuliers
Contrôle granulaire : Affiner le règlement pour des adresses spécifiques

Création de règles de Règlement automatique

Via le tableau de bord

Rendez-vous dans la section Auto Settlements de votre wallet
Cliquez sur « Create New Rule »
Configurez les paramètres de la règle
Définissez les seuils de montant et la tolérance de slippage
Choisissez les actifs/chaînes source et de destination
Enregistrez et activez la règle

Via l’API

Créez des règles de règlement de manière programmatique grâce à l’API Auto Settlement Rules :

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "type": "swap",
    "name": "Swap from USDC to Optimism USDC",
    "order": "FASTEST",
    "slippageTolerance": "-1",
    "source": {
        "assets": [
            "USDC",
            "USDT"
        ],
        "minAmount": "1",
        "maxAmount": "1000"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC"
    }
}'

Dans cet exemple, slippageTolerance est défini à -1 pour un slippage illimité, et destination.address est omis. Le système utilisera automatiquement la logique de fallback intelligente pour déterminer l’adresse destinataire.

Avec une adresse de destination explicite :

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "type": "swap",
    "name": "Swap from USDC to Optimism USDC",
    "order": "FASTEST",
    "slippageTolerance": "5",
    "source": {
        "assets": [
            "USDC",
            "USDT"
        ],
        "minAmount": "1",
        "maxAmount": "1000"
    },
    "destination": {
        "blockchain": "optimism",
        "asset": "USDC",
        "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
    }
}'

Copier des règles entre wallets

Les règles sont propres à chaque blockchain : déployer une même stratégie sur toutes les chaînes que vous exploitez reviendrait à recréer la même règle de nombreuses fois. L’endpoint de copie le fait en un seul appel :

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/auto-settlements/rules/copy \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "rules": [
        {
            "type": "withdraw",
            "name": "Sweep USDC to treasury",
            "slippageTolerance": "0",
            "source": {
                "assets": ["USDC"],
                "minAmount": "1",
                "maxAmount": "-1"
            },
            "destination": {
                "blockchain": "base",
                "asset": "USDC",
                "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
            }
        }
    ],
    "targetWalletIds": [
        "3f6c9a11-9a7e-4a3c-8f2b-0d51e6c4a7b2",
        "c81e7d40-5b6a-4f9e-9c3d-2a7f10b8e654"
    ]
}'

Les règles sont envoyées par valeur, et non par ID : la source peut donc être les règles d’une master wallet, celles d’une child address, ou un payload que vous composez vous-même. Le champ source.blockchain de chaque règle est réécrit avec la blockchain de la wallet cible avant enregistrement.

Le succès partiel est normal

L’appel renvoie 200 même lorsque certaines règles sont ignorées ou que certaines wallets échouent. Lisez toujours la réponse plutôt que de vous fier au code de statut :

{
  "data": {
    "summary": {
      "walletsTargeted": 2,
      "rulesRequested": 1,
      "applied": 1,
      "skipped": 1,
      "failed": 0
    },
    "results": [
      {
        "walletId": "3f6c9a11-9a7e-4a3c-8f2b-0d51e6c4a7b2",
        "walletName": "Base Mainnet Wallet",
        "chain": "base",
        "applied": [{ "name": "Sweep USDC to treasury" }],
        "skipped": []
      },
      {
        "walletId": "c81e7d40-5b6a-4f9e-9c3d-2a7f10b8e654",
        "walletName": "Optimism Mainnet Wallet",
        "chain": "optimism",
        "applied": [],
        "skipped": [
          {
            "name": "Sweep USDC to treasury",
            "reason": "A settlement rule for USDC already exists on the optimism wallet"
          }
        ]
      }
    ]
  },
  "message": "Settlement rules copied",
  "statusCode": 200
}

Résultat	Signification
`applied`	La règle a été écrite sur cette wallet
`skipped`	La règle a été rejetée pour cette wallet uniquement : l’actif n’y est pas activé, une règle couvre déjà cet actif sur cette chaîne, ou la règle n’a pas passé la validation pour cette wallet
`failed`	La wallet entière n’a pas pu être écrite, par exemple parce qu’elle n’existe pas ou est inactive sur ce réseau

Chaque wallet cible est verrouillée et écrite dans sa propre transaction : un échec sur l’une ne laisse jamais une autre à moitié écrite. Appliquer au moins une règle à une wallet active également le règlement automatique sur cette wallet.

La requête elle-même échoue avec 400 lorsque le tableau rules est mal formé, lorsque rules ou targetWalletIds est vide, ou lorsque la seule wallet indiquée comme cible est la wallet source (la source est toujours retirée de la liste des cibles).

Cas d’usage

Gestion de trésorerie

Conversion d’actifs flexible : Convertissez vers n’importe quel actif préféré (USDC, ETH, USDT, etc.)
Opérations cross-chain : Maintenez des soldes sur plusieurs réseaux
Consolidation automatisée : Aucune intervention manuelle requise
Stratégie multi-actifs : Prend en charge diverses préférences et stratégies d’actifs

Opérations métier

Traitement des paiements : Réglez automatiquement les paiements entrants vers les actifs préférés
Gestion des revenus : Convertissez diverses stablecoins vers l’actif de destination choisi
Atténuation des risques : Appliquez automatiquement la protection contre le slippage
Diversification d’actifs : Maintenez automatiquement les allocations d’actifs cibles

Intégration DeFi

Yield farming : Réglez automatiquement les récompenses vers l’actif préféré
Gestion de la liquidité : Consolidez les récompenses et frais de LP
Rééquilibrage de portefeuille : Maintenez les allocations d’actifs cibles

Bonnes pratiques

Configuration des règles

Commencez prudemment : Démarrez avec une faible tolérance de slippage
Suivez les performances : Surveillez les taux de succès des règlements
Ajustez progressivement : Affinez les règles selon les conditions du marché
Testez sur testnet : Validez les règles avant tout déploiement sur mainnet

Gestion du risque

Limites de slippage : Définissez des niveaux de tolérance appropriés
Plafonds de montant : Limitez la taille maximale des règlements
Sélection du réseau : Choisissez des chaînes de destination fiables
Règles de repli : Créez des options de règlement de secours

Efficacité opérationnelle

Traitement par lot : Regroupez les petits dépôts pour gagner en efficacité
Optimisation du timing : Tenez compte des schémas de congestion réseau
Analyse des coûts : Équilibrez les préférences vitesse vs. coût
Surveillance : Mettez en place des alertes pour les règlements échoués

Surveillance et alertes

Surveillance via le tableau de bord

Statut des règles : Indicateurs de règle active/inactive
Historique des règlements : Suivez les règlements réussis et échoués
Indicateurs de performance : Taux de succès et temps d’exécution
Soldes d’actifs : Surveillez la croissance du solde unifié

Notifications par webhook

Les règlements automatiques déclenchent des événements webhook lors de l’exécution. La famille d’événements que vous recevez dépend du type de règlement exécuté :

Type de règlement	Événements
`swap`	`swap.success`, `swap.failed`, `swap.cancelled`, `swap.processing`
`withdraw`	`withdraw.success`, `withdraw.failed`, `withdraw.cancelled`, `withdraw.processing`
`gateway`	`gateway-deposit.success`, `gateway-deposit.failed`, `gateway-deposit.cancelled`, `gateway-deposit.processing`
`earn`	`reward-deposit.success`, `reward-deposit.failed`, `reward-deposit.cancelled`, `reward-deposit.processing`

Une règle gateway sur une chaîne non éligible à Gateway bascule vers un swap : elle émet donc des événements swap.* plutôt que gateway-deposit.*. Abonnez-vous aux deux si vous exploitez des règles gateway hors des chaînes prises en charge par Gateway.

Exemple de payload webhook

{
  "event": "swap.success",
  "data": {
    "id": "99a2b490-0798-460b-9265-4d99f182fe52",
    "reference": "ZMxcorDGtf",
    "senderAddress": "0xAA2d5fd5e7bE97E214f8565DCf3a4862719960b5",
    "recipientAddress": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43",
    "amount": "5",
    "status": "SUCCESS",
    "type": "SWAP",
    "network": "mainnet",
    "toAmount": "4.965398",
    "rate": "0.9930796000000001",
    "asset": {
      "name": "USD Coin",
      "symbol": "USDC",
      "network": "mainnet"
    },
    "toAsset": {
      "name": "Tether USD",
      "symbol": "USDT",
      "network": "mainnet"
    },
    "toBlockchain": {
      "name": "optimism",
      "slug": "optimism"
    },
    "toWallet": {
      "name": "Optimism Mainnet Wallet",
      "address": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43"
    },
    "metadata": {
      "swapAutoSettlement": {
        "rule": {
          "id": "rule-id-123",
          "name": "USDT to USDC on Base",
          "order": "RECOMMENDED",
          "slippageTolerance": 5,
          "source": {
            "assets": ["USDC", "USDT"],
            "minAmount": "1",
            "maxAmount": "1000"
          },
          "destination": {
            "blockchain": "optimism",
            "asset": "USDC",
            "address": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22"
          }
        },
        "settleAmount": "5"
      },
      "transactionId": "transaction-id"
    }
  }
}

Identifier les transactions de règlement automatique

La meilleure façon d’identifier les transactions de règlement automatique est d’examiner le champ metadata. Selon l’action, le metadata contiendra l’une des clés suivantes :

Clé de metadata	Description
`swapAutoSettlement`	Présent lorsque le règlement automatique a déclenché une opération de swap
`gatewayAutoSettlement`	Présent lorsque le règlement automatique a déclenché une opération Gateway
`withdrawAutoSettlement`	Présent lorsque le règlement automatique a déclenché une opération de retrait
`rewardAutoSettlement`	Présent lorsque le règlement automatique a déclenché un dépôt Earn

Les objets swap, gateway et retrait contiennent :

Champ	Description
`rule`	Payload complet de la règle de règlement automatique ayant déclenché cette transaction
`settleAmount`	Montant réglé conformément à la règle

rewardAutoSettlement a une forme différente : il porte l’ID de la règle plutôt que la règle complète :

Champ	Description
`ruleId`	ID de la règle earn ayant déclenché ce dépôt
`settleAmount`	Montant réglé conformément à la règle
`sourceTransactionId`	ID de la transaction de dépôt ayant déclenché le règlement

Lorsque l’une de ces clés de metadata est présente, la transaction a été déclenchée par une règle de règlement automatique. Pour les règlements swap, gateway et retrait, le champ rule contient la configuration complète de la règle, et non un simple ID ; pour les règlements earn, retrouvez la règle grâce à ruleId.

Champs clés des données du webhook

Champ	Description
`toAmount`	Montant final reçu après le swap (en tenant compte des frais et du slippage)
`rate`	Taux de change utilisé pour le swap
`toAsset`	Détails de l’actif de destination (USDT dans cet exemple)
`toBlockchain`	Réseau blockchain de destination (Optimism dans cet exemple)
`toWallet`	Wallet de destination ayant reçu les actifs convertis
`assetSwept`	Indique si les actifs d’origine ont été balayés après la conversion

Référence de l’API

Endpoints

Règlements automatiques de Master Wallet

Endpoint	Méthode	Description	Référence de l’API
`/v1/wallets/{walletId}/auto-settlements/rules`	GET	Lister toutes les règles de règlement de la master wallet	Get All Rules
`/v1/wallets/{walletId}/auto-settlements/rules`	POST	Créer une nouvelle règle de règlement pour la master wallet	Create Rule
`/v1/wallets/{walletId}/auto-settlements/rules/copy`	POST	Copier des règles de règlement vers d’autres master wallets	Copy Rules
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	GET	Récupérer les détails d’une règle spécifique de la master wallet	Get Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	PATCH	Mettre à jour une règle existante de la master wallet	Update Rule
`/v1/wallets/{walletId}/auto-settlements/rules/{id}`	DELETE	Supprimer une règle de règlement de la master wallet	Delete Rule
`/v1/wallets/{walletId}/auto-settlements`	GET	Récupérer l’historique des règlements de la master wallet	Get Settlement
`/v1/wallets/{walletId}/auto-settlements`	PATCH	Mettre à jour les paramètres de règlement de la master wallet	Update Settlement

Règlements automatiques de Child Address

Endpoint	Méthode	Description	Référence de l’API
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`	GET	Lister toutes les règles de règlement pour une adresse spécifique	Get All Rules
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules`	POST	Créer une nouvelle règle de règlement pour une adresse spécifique	Create Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	GET	Récupérer les détails de la règle d’une adresse spécifique	Get Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	PATCH	Mettre à jour une règle d’adresse existante	Update Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	DELETE	Supprimer une règle de règlement d’adresse	Delete Rule
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	GET	Récupérer l’historique de règlement de l’adresse	Get Settlement
`/v1/wallets/{walletId}/addresses/{addressId}/auto-settlements`	PATCH	Mettre à jour les paramètres de règlement de l’adresse	Update Settlement

Il n’existe pas d’endpoint de copie pour les child addresses : la copie vise toujours des master wallets, même si les règles que vous copiez peuvent provenir d’une child address.

La sémantique de mise à jour diffère selon le niveau

Endpoint	Traitement du body
`PATCH /wallets/{walletId}/auto-settlements/rules/{id}`	Fusion partielle. N’envoyez que les champs que vous modifiez ; tout le reste conserve sa valeur actuelle. Les objets imbriqués comme `source` et `destination` sont remplacés en bloc : envoyez-les complets lorsque vous les envoyez
`PATCH /wallets/{walletId}/addresses/{addressId}/auto-settlements/rules/{id}`	Règle complète. `source` et `destination` sont obligatoires, et tout champ facultatif omis revient à sa valeur par défaut : `order` à `RECOMMENDED`, `slippageTolerance` et `deductionPercentage` à `"0"`, `useTransactionAmount` à `false`, `isActive` à `true`, `source.minAmount` à `"0"` et `source.maxAmount` à `"-1"`

Lisez d’abord la règle et renvoyez l’objet complet lors de la mise à jour d’une règle de child address. N’envoyer que le champ à modifier réinitialise silencieusement le reste de la règle aux valeurs par défaut.

Dans les deux cas, la règle fusionnée est revalidée : une mise à jour peut donc être rejetée à cause d’un champ que vous n’avez pas envoyé.

Paramètres de la règle

Paramètre	Type	Requis	Description
`type`	string	Non	Flux de règlement : `withdraw`, `swap`, `gateway` ou `earn`. À envoyer sur chaque nouvelle règle
`name`	string	Non	Nom de la règle pour identification
`isActive`	boolean	Non	Indique si la règle est activée. `true` par défaut
`order`	string	Non	Préférence de routage (FASTEST/CHEAPEST/RECOMMENDED/NO_SLIPPAGE). `RECOMMENDED` par défaut ; ignoré pour les règles gateway et earn
`slippageTolerance`	string	Non	Slippage maximal acceptable (%). Utilisez `-1` pour illimité. À envoyer explicitement sur les règles de swap
`isGateway`	boolean	Non	Achemine via Gateway de Circle. Obligatoire avec `type: gateway`
`isReward`	boolean	Non	Achemine vers une position Earn. Obligatoire avec `type: earn`. Mainnet uniquement
`rewardProvider`	string	Conditionnel	`fija` ou `aave`. Obligatoire lorsque `isReward` vaut `true`
`rewardType`	string	Conditionnel	`regulated` pour `fija`, `defi` pour `aave`. Obligatoire lorsque `isReward` vaut `true`
`useTransactionAmount`	boolean	Non	`false` (par défaut) règle le solde de l’adresse ; `true` ne règle que le dépôt déclencheur
`deductionPercentage`	string	Non	Pourcentage retenu sur le montant réglé. `"0"` par défaut
`inheritance.mode`	string	Non	`master_only`, `all_children` ou `selected_children`. Règles de la master wallet uniquement
`inheritance.childAddressIds`	array	Conditionnel	Obligatoire et non vide lorsque le mode est `selected_children`
`source.assets`	array	Oui	Liste d’actifs sources à régler automatiquement
`source.minAmount`	string	Non	Montant minimum déclenchant le règlement. `"0"` par défaut
`source.maxAmount`	string	Non	Montant maximum par règlement. Utilisez `-1` pour illimité (par défaut)
`source.blockchain`	string	Non	Ignoré à la création : toujours défini sur la blockchain de la wallet elle-même
`destination.blockchain`	string	Oui	Réseau blockchain cible. Doit être identique à la source pour les règles `withdraw`
`destination.asset`	string	Oui	Actif cible pour la conversion. Forcé à USDC pour les règles gateway
`destination.address`	string	Conditionnel	Obligatoire pour les règles `withdraw`. Sinon facultatif : la logique de fallback intelligente s’applique (voir ci-dessus)

Pour commencer

1. Activer les Règlements automatiques

Rendez-vous dans les paramètres de votre wallet
Activez la fonctionnalité de règlement automatique
Configurez les préférences par défaut

2. Créer votre première règle

Commencez par une règle simple USDT vers ETH (ou tout autre actif de votre choix)
Définissez une tolérance de slippage prudente
Choisissez votre chaîne et votre actif de destination préférés

3. Tester et surveiller

Déployez d’abord sur testnet
Surveillez les taux de succès des règlements
Ajustez les paramètres si nécessaire

4. Monter en charge progressivement

Ajoutez des règles pour des actifs supplémentaires
Mettez en place le traitement par lot
Optimisez selon votre cas d’usage

Support et ressources

Obtenir de l’aide

E-mail : [email protected]
Référence de l’API : Auto Settlement Rules
Documentation : Configuration de Gateway

Les règlements automatiques sont un moyen puissant d’automatiser la gestion de votre trésorerie. Commencez par des règles simples et ajoutez progressivement de la complexité au fur et à mesure que vous vous familiarisez avec le système.

​Prérequis

​Fonctionnement

Gestion des règles

Conversion d'actifs

Cross-Chain

Gestion du risque

​Comment fonctionnent les Règlements automatiques

​1. Création des règles

​2. Détection des dépôts

​3. Conversion d’actifs

​4. Unification des soldes

​Types de règlement

​Règles de validation par type

​Les règles gateway peuvent basculer vers un swap

​Règles de Règlement automatique

​Composants d’une règle

​Quel montant est réglé

​Règles de règlement vers Earn

​Options de configuration de la règle

​Seuils de montant

​Protection contre le slippage

​Adresse de destination (facultative)

​Préférences d’exécution

​Hiérarchie et précédence des règles

​Comment les règles s’appliquent

​Ordre d’application des règles

​Héritage par règle

​Règles spécifiques à une blockchain

​Cas d’usage pour chaque niveau

​Règles de Master Wallet

​Règles de Child Address

​Création de règles de Règlement automatique

​Via le tableau de bord

​Via l’API

​Copier des règles entre wallets

​Le succès partiel est normal

​Cas d’usage

​Gestion de trésorerie

​Opérations métier

​Intégration DeFi

​Bonnes pratiques

​Configuration des règles

​Gestion du risque

​Efficacité opérationnelle

​Surveillance et alertes

​Surveillance via le tableau de bord

​Notifications par webhook

​Exemple de payload webhook

​Identifier les transactions de règlement automatique

​Champs clés des données du webhook

​Référence de l’API

​Endpoints

​Règlements automatiques de Master Wallet

​Règlements automatiques de Child Address

​La sémantique de mise à jour diffère selon le niveau

​Paramètres de la règle

​Pour commencer

​1. Activer les Règlements automatiques

​2. Créer votre première règle

​3. Tester et surveiller

​4. Monter en charge progressivement

​Support et ressources

​Obtenir de l’aide

Prérequis

Fonctionnement

Comment fonctionnent les Règlements automatiques

1. Création des règles

2. Détection des dépôts

3. Conversion d’actifs

4. Unification des soldes

Types de règlement

Règles de validation par type

Les règles gateway peuvent basculer vers un swap

Règles de Règlement automatique

Composants d’une règle

Quel montant est réglé

Règles de règlement vers Earn

Options de configuration de la règle

Seuils de montant

Protection contre le slippage

Adresse de destination (facultative)

Préférences d’exécution

Hiérarchie et précédence des règles

Comment les règles s’appliquent

Ordre d’application des règles

Héritage par règle

Règles spécifiques à une blockchain

Cas d’usage pour chaque niveau

Règles de Master Wallet

Règles de Child Address

Création de règles de Règlement automatique

Via le tableau de bord

Via l’API

Copier des règles entre wallets

Le succès partiel est normal

Cas d’usage

Gestion de trésorerie

Opérations métier

Intégration DeFi

Bonnes pratiques

Configuration des règles

Gestion du risque

Efficacité opérationnelle

Surveillance et alertes

Surveillance via le tableau de bord

Notifications par webhook

Exemple de payload webhook

Identifier les transactions de règlement automatique

Champs clés des données du webhook

Référence de l’API

Endpoints

Règlements automatiques de Master Wallet

Règlements automatiques de Child Address

La sémantique de mise à jour diffère selon le niveau

Paramètres de la règle

Pour commencer

1. Activer les Règlements automatiques

2. Créer votre première règle

3. Tester et surveiller

4. Monter en charge progressivement

Support et ressources

Obtenir de l’aide