aeon-distribute-tokens

Paiements par lots de production. L'état est indexé sur (list, recipient, utc_date) donc toute réexécution le même jour ignore les lignes déjà complétées.

Phases

RESOLVE — charger la config, vérifier le scope BANKR_API_KEY (lecture-écriture requis), vérifier le solde du portefeuille, résoudre chaque @handle en adresse EVM via Bankr Agent, construire le plan. Avorte avant tout transfert si solde < total × 1.05.
EXECUTE — pour chaque ligne READY, appeler POST /wallet/transfer. Persister l'état sur disque après chaque ligne, pas à la fin.

Une dry-run exécute seulement RESOLVE et affiche le plan sans transferts.

Config

defaults:
  token: USDC
  amount: "5"
  chain: base

lists:
  contributors:
    description: "Weekly contributor rewards"
    token: USDC
    amount: "10"
    recipients:
      - handle: "@alice"
        amount: "15"
      - handle: "@bob"
      - address: "0x742d...5678"
        label: "Charlie"
        amount: "20"

Adresses de tokens sur Base :

USDC : 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
ETH natif : tokenAddress: 0x000...000, isNativeToken: true

Surface d'API

Endpoint	Objectif
`GET /wallet/me`	Préflight : vérification d'identité + scope. 403 → clé en lecture seule, avorter.
`GET /wallet/portfolio?chain=base`	Vérification du solde vs total × 1.05.
`POST /agent/prompt` + `GET /agent/job/{id}`	Résolution `@handle` → adresse. Jamais utilisé pour les transferts.
`POST /wallet/transfer`	Le seul endpoint de transfert autorisé.

curl -fsS -X POST "https://api.bankr.bot/wallet/transfer" \
  -H "X-API-Key: ${BANKR_API_KEY}" -H "Content-Type: application/json" \
  -d '{"recipientAddress":"0x...","tokenAddress":"0x8335...","amount":"15","isNativeToken":false}'

Fichier d'état

{
  "contributors|@alice|2026-05-12": {
    "list": "contributors", "recipient": "@alice", "address": "0x...",
    "amount": "15", "token": "USDC",
    "status": "completed", "txHash": "0x...",
    "timestamp": "2026-05-12T12:34:56Z"
  }
}

Lire avant d'envoyer ; persister après chaque ligne.

Gestion des résultats

Réponse	Action
`200` + `success: true`	Marquer complété, stocker txHash, persister immédiatement.
`200` + `success: false`	Marquer échoué avec raison de l'erreur.
`403`	Clé a perdu le scope en écriture — avorter les lignes restantes.
`429`	Attendre 60s, réessayer une fois ; si toujours 429 avorter les lignes restantes.
`5xx` / réseau	Réessayer une fois après 10s ; marquer échoué si toujours mauvais.

Sortie

Ligne de verdict d'abord : COMPLETE / PARTIAL / FAILED / DRY_RUN / NOTHING_TO_SEND. Puis détail par ligne avec liens tx basescan pour les succès et codes raison pour les échecs.

Règles

L'idempotence est non-négociable. Lire l'état avant d'envoyer, persister après chaque ligne.
Préflight avec 5% de marge — ne jamais démarrer une exécution partielle.
Wallet API pour les transferts seulement. Agent API résout les handles ; il ne déplace pas de tokens.
Rate limit Bankr (100/jour standard) est un plafond dur — diviser les listes de > 50.
Les handles non-résolubles sont ignorés avec RESOLVE_FAILED, pas échoués bruyamment — le reste du plan s'exécute.

Scope requis

BANKR_API_KEY avec Wallet API activée et accès lecture-écriture. Les clés en lecture seule retournent 403 au préflight.