Crédits et rechargements

Utilisez un token write pour demander un brouillon de rechargement. Lisez le minimum actuel, les taux par actif, la disponibilité, le bonus et les plafonds dans pricing avant de payer. Le montant de l’exemple est d’au moins 10 000 crédits et jamais inférieur au minimum configuré de cette instance. Les crédits sont ancrés sur l’USD ; les montants en actifs sont cotés, pas fixes. Un brouillon est une instruction, pas une écriture de crédit.

curl -X POST 'https://ftso.app/api/x402/topup' \
  -H 'authorization: Bearer fbx_WRITE_TOKEN' \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: topup_20260930_001' \
  -d '{"credits":10000,"asset":"FBEST"}'
# asset: FBEST | WFLR | FXRP | FLR | XRP

Le brouillon renvoie l’adresse du PaymentRouter, asset, amountRaw, deadline, signedBy, typedData et signature. FXRP utilise six décimales ; ne le traitez pas comme un token à 18 décimales. Vérifiez le routeur et la treasury attendus par rapport à la configuration publique, lisez settlementSigner() et vérifiez cryptographiquement la signature EIP-712. Comparer signedBy seul ne vérifie pas une signature. Confirmez buyer, asset, amount, chaîne, deadline, feeBps=0 et mode=0 avant d’approuver et d’appeler pay().

// draft is response.topup; router and token are viem contract instances.
// Verify the complete authorization before approval or payment.
const m = draft.typedData.message;
await token.write.approve([draft.routerAddress, BigInt(draft.amountRaw)]);
const txHash = await router.write.pay([
  { ...m, amount: BigInt(m.amount), deadline: BigInt(m.deadline), nonce: m.nonce },
  draft.signature,
]);

curl -X POST 'https://ftso.app/api/x402/topup/HANDLE/confirm' \
  -H 'authorization: Bearer fbx_WRITE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"txHash":"0xPAY_TRANSACTION_HASH"}'

La confirmation vérifie le paiement avant de créditer. Un hachage de transaction seul ne prouve pas un rechargement payé. Le routeur transfère le montant autorisé ; une confirmation en double ne peut pas accorder les crédits deux fois.

Envoyez amountWei du brouillon à payTo sur la chaîne 14, en joignant son handle dataHex exact de 32 octets. Aucune approbation de token n’est nécessaire. Confirmez ensuite le hachage de transaction. Les crédits dépendent de la valeur livrée, arrondie vers le bas et limitée par les plafonds configurés.

await wallet.sendTransaction({
  to: draft.payTo,
  value: BigInt(draft.amountWei),
  data: draft.dataHex,
  chainId: 14,
});

Utilisez l’adresse XRPL et le destinationTag renvoyés, avec amountDrops. Le destination tag attribue le paiement au bon rechargement. Interrogez l’endpoint de statut avec un token read ; le worker crédite de manière asynchrone un paiement livré et vérifié. Il n’y a pas de délai d’achèvement garanti. L’attestation FDC optionnelle suit le crédit et ne le conditionne pas. verifiedByFdc peut rester à false.

curl 'https://ftso.app/api/x402/topup/HANDLE' \
  -H 'authorization: Bearer fbx_READ_TOKEN'

Respectez la deadline du brouillon. Les paiements proportionnels FLR/XRP tardifs utilisent le plus bas du taux gelé et du taux actuel ; sans prix actuel, le worker attend. Les plafonds par rechargement limitent les surpaiements crédités ; dépasser un plafond d’avoirs d’un actif met en pause les nouveaux brouillons. N’envoyez jamais sans l’ordre du routeur, dataHex ou destinationTag : l’application ne peut pas attribuer un tel paiement de manière fiable.

Les achats d’abonnement par Bearer requièrent un Idempotency-Key de 8 à 128 lettres, chiffres, tirets bas ou traits d’union. L’en-tête est aussi pris en charge pour la création de watches, les brouillons de rechargement, la création de destinataires et le PUT de canal. Réutilisez la même clé et le même corps après un timeout. Les réponses finales sont conservées 24 heures ; un corps modifié renvoie 409 idempotency_key_reused. Une réservation active renvoie 409 idempotency_in_progress avec Retry-After. Les échecs réessayables libèrent la clé ; les brouillons expirés renvoient 410 draft_expired. Les rejeux comptent dans les limites de débit. Les secrets renvoyés peuvent être récupérables par un rejeu du même wallet pendant 24 heures.

Les crédits gagnés sont comptabilisés séparément des crédits achetés. La conversion FBEST existante utilise une demande, une approbation admin et un claim du wallet sur le ConversionVault ; le versement automatisé n’est pas implémenté. Voir Crédits pour le parcours utilisateur.

Pour les taux, la disponibilité et la configuration actuellement actifs, utilisez /api/x402/pricing. Cette section lit la configuration de cette instance d’application ; elle n’interroge ni la treasury ni un serveur distant.

• Crédits minimum par rechargement: 10000
• USD pour 1 000 crédits: 1

• FBEST: Maximum par rechargement: Aucun plafond configuré; Seuil des avoirs de la treasury: Aucun plafond configuré.
• WFLR: Maximum par rechargement: Aucun plafond configuré; Seuil des avoirs de la treasury: Aucun plafond configuré.
• FXRP: Maximum par rechargement: 1000; Seuil des avoirs de la treasury: 5000.
• FLR: Maximum par rechargement: Aucun plafond configuré; Seuil des avoirs de la treasury: Aucun plafond configuré.
• XRP: Maximum par rechargement: 1000; Seuil des avoirs de la treasury: 5000.