API des Règlements

Les règlements enregistrent les montants de versement des positions après la résolution d'un marché. Le moteur de prédiction crée les enregistrements de règlement — les opérateurs interrogent ces enregistrements pour déterminer le montant à créditer sur le portefeuille de chaque joueur.

Authentification : en-tête X-Api-Key requis.

Flux de Règlement

Market RESOLVED → Trigger Settlement → Settlement Records Created → Operator Queries Payouts → Operator Credits Players

Étape 1 : Déclencher le Règlement

Après la résolution d'un marché, déclenchez le processus de règlement :

POST /api/v1/markets/{id}/settle

Cela va :

1. Annuler toutes les ordres ouverts restants dans le marché
2. Calculer les versements pour chaque position
3. Créer les enregistrements de règlement

Réponse :

{
  "success": true,
  "data": {
    "marketId": "market-uuid",
    "totalPositions": 25,
    "successCount": 25,
    "failedCount": 0,
    "totalPayout": "1250.00",
    "cancelledOrders": 3,
    "settlements": [
      {
        "id": "settlement-uuid",
        "positionId": "position-uuid",
        "marketId": "market-uuid",
        "outcomeId": "outcome-uuid",
        "operatorId": "operator-uuid",
        "shares": "100",
        "payoutPerShare": "1",
        "totalPayout": "100",
        "transactionId": null,
        "status": "COMPLETED",
        "errorMessage": null,
        "settledAt": "2026-02-18T23:00:00.000Z",
        "createdAt": "2026-02-18T23:00:00.000Z",
        "updatedAt": "2026-02-18T23:00:00.000Z"
      }
    ],
    "errors": []
  }
}

Étape 2 : Consulter le Statut du Règlement

Vérifiez la progression du traitement du règlement :

GET /api/v1/markets/{id}/settlement-status

Réponse :

{
  "success": true,
  "data": {
    "marketId": "market-uuid",
    "totalPositions": 25,
    "pendingCount": 0,
    "processingCount": 0,
    "completedCount": 25,
    "failedCount": 0,
    "totalPayout": "1250.00",
    "completedPayout": "1250.00"
  }
}

Étape 3 : Consulter les Versements de Règlement

Récupérez les enregistrements de règlement pour déterminer les versements des joueurs :

GET /api/v1/settlements

Paramètres de requête :

Paramètre	Type	Description
marketId	string	Filtrer par marché

Exemple :

curl "https://polymarket.sandbox.playbatman.com/api/v1/settlements?marketId=market-uuid" \
  -H "X-Api-Key: your-api-key"

Réponse :

{
  "success": true,
  "data": [
    {
      "id": "settlement-uuid",
      "positionId": "position-uuid",
      "marketId": "market-uuid",
      "outcomeId": "winning-outcome-uuid",
      "operatorId": "operator-uuid",
      "shares": "100",
      "payoutPerShare": "1",
      "totalPayout": "100",
      "transactionId": null,
      "status": "COMPLETED",
      "errorMessage": null,
      "settledAt": "2026-02-18T23:00:00.000Z",
      "createdAt": "2026-02-18T23:00:00.000Z",
      "updatedAt": "2026-02-18T23:00:00.000Z"
    },
    {
      "id": "settlement-uuid-2",
      "positionId": "position-uuid-2",
      "marketId": "market-uuid",
      "outcomeId": "losing-outcome-uuid",
      "operatorId": "operator-uuid",
      "shares": "50",
      "payoutPerShare": "0",
      "totalPayout": "0",
      "transactionId": null,
      "status": "COMPLETED",
      "errorMessage": null,
      "settledAt": "2026-02-18T23:00:00.000Z",
      "createdAt": "2026-02-18T23:00:00.000Z",
      "updatedAt": "2026-02-18T23:00:00.000Z"
    }
  ]
}

Étape 4 : Relancer les Règlements Échoués

Si des règlements ont échoué, vous pouvez les relancer :

POST /api/v1/markets/{id}/retry-settlements

Réponse : Même structure que la réponse de règlement.

Calcul des Versements

• Issue gagnante : payoutPerShare = 1.00 — chaque part verse 1 unité de la devise du marché
• Issue perdante : payoutPerShare = 0.00 — aucun versement

Exemple :

• Le joueur a acheté 100 parts de « Oui » à 0,65 $ → coût : 65,00 $
• Le marché résout « Oui » → versement : 100 parts × 1,00 $ = 100,00 $
• Bénéfice : 100,00 $ - 65,00 $ = 35,00 $

Champs de Règlement

Champ	Type	Description
id	string	UUID du règlement
positionId	string	Position en cours de règlement
marketId	string	UUID du marché
outcomeId	string	UUID de l'issue
operatorId	string	UUID de l'opérateur
shares	string (decimal)	Nombre de parts dans la position
payoutPerShare	string (decimal)	Versement par part (1 pour la gagnante, 0 pour la perdante)
totalPayout	string (decimal)	Montant total du versement (shares * payoutPerShare)
transactionId	string | null	Référence de transaction assignée par l'opérateur
status	string	PENDING, PROCESSING, COMPLETED, ou FAILED
errorMessage	string | null	Détails de l'erreur si le règlement a échoué
settledAt	string (ISO 8601) | null	Moment où le règlement a été complété
createdAt	string (ISO 8601)	Heure de création de l'enregistrement
updatedAt	string (ISO 8601)	Heure de la dernière mise à jour

Responsabilités de l'Opérateur

important

Le moteur de prédiction enregistre les montants de règlement mais n'effectue pas de transfert de fonds. En tant qu'opérateur, vous devez :

1. Interroger les enregistrements de règlement après le règlement du marché
2. Associer les règlements à vos joueurs en utilisant les données des ordres (les ordres contiennent playerId)
3. Créditer les portefeuilles de vos joueurs avec les montants totalPayout
4. Suivre les règlements que vous avez traités de votre côté

Codes d'Erreur

Code	Description
SETTLEMENT_FAILED	Le traitement du règlement a rencontré une erreur
SETTLEMENT_ALREADY_COMPLETED	Le règlement a déjà été complété