API Marchés

Les marchés sont l'entité centrale de la plateforme de prédiction. Chaque marché représente une question avec deux résultats possibles ou plus, qui peuvent faire l'objet d'échanges.

Authentification : Toutes les routes de marché nécessitent l'en-tête X-Api-Key, sauf mention contraire.

Créer un marché

Crée un nouveau marché de prédiction.

POST /api/v1/markets

Corps de la requête :

Champ	Type	Requis	Description
title	string	Oui	Question/titre du marché
description	string	Non	Description détaillée
categoryId	string	Non	UUID de la catégorie
imageUrl	string	Non	URL de l'image du marché
currency	string	Non	Code de devise (par défaut : USD). Doit être l'une des devises supportedCurrencies de l'opérateur.
tradingStartsAt	string (ISO 8601)	Non	Date d'ouverture des échanges
tradingEndsAt	string (ISO 8601)	Non	Date de clôture des échanges
outcomes	array	Non	Tableau d'objets résultat
metadata	object	Non	Métadonnées JSON arbitraires

Objet résultat :

Champ	Type	Requis	Description
name	string	Oui	Nom du résultat (ex. : "Yes", "No")
description	string	Non	Description du résultat

Exemple :

curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/markets \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Will Bitcoin exceed $100K by March 2026?",
    "description": "Resolves YES if BTC/USD exceeds $100,000 at any point before March 31, 2026",
    "categoryId": "uuid-of-crypto-category",
    "currency": "KES",
    "tradingStartsAt": "2026-02-20T00:00:00Z",
    "tradingEndsAt": "2026-03-31T23:59:59Z",
    "outcomes": [
      { "name": "Yes", "description": "Bitcoin exceeds $100K" },
      { "name": "No", "description": "Bitcoin does not exceed $100K" }
    ]
  }'

Réponse (201 Created) :

{
  "success": true,
  "data": {
    "id": "market-uuid",
    "operatorId": "operator-uuid",
    "categoryId": "category-uuid",
    "title": "Will Bitcoin exceed $100K by March 2026?",
    "description": "Resolves YES if BTC/USD exceeds $100,000...",
    "imageUrl": null,
    "status": "DRAFT",
    "currency": "KES",
    "tradingStartsAt": "2026-02-20T00:00:00.000Z",
    "tradingEndsAt": "2026-03-31T23:59:59.000Z",
    "resolvedAt": null,
    "winningOutcomeId": null,
    "resolutionSource": null,
    "resolutionNotes": null,
    "totalVolume": "0",
    "totalTrades": 0,
    "metadata": null,
    "createdAt": "2026-02-18T22:00:00.000Z",
    "updatedAt": "2026-02-18T22:00:00.000Z",
    "outcomes": [
      {
        "id": "outcome-uuid-1",
        "name": "Yes",
        "description": "Bitcoin exceeds $100K",
        "index": 0,
        "createdAt": "2026-02-18T22:00:00.000Z",
        "updatedAt": "2026-02-18T22:00:00.000Z"
      },
      {
        "id": "outcome-uuid-2",
        "name": "No",
        "description": "Bitcoin does not exceed $100K",
        "index": 1,
        "createdAt": "2026-02-18T22:00:00.000Z",
        "updatedAt": "2026-02-18T22:00:00.000Z"
      }
    ],
    "category": {
      "id": "category-uuid",
      "name": "Crypto",
      "slug": "crypto"
    }
  }
}

Validation de la devise

Le champ currency doit correspondre à l'une des devises configurées dans la liste supportedCurrencies de l'opérateur. Si le compte de l'opérateur est configuré avec ["KES", "USD"], seules ces devises sont autorisées. Soumettre une devise non prise en charge renvoie une erreur 400 :

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Currency 'EUR' is not allowed. Supported currencies: KES, USD"
  }
}

Obtenir un marché

Récupère un marché unique par son identifiant.

GET /api/v1/markets/{id}

Réponse : Même structure que la réponse de création de marché.

Lister les marchés

Liste les marchés associés à votre compte opérateur.

GET /api/v1/markets

Paramètres de requête :

Paramètre	Type	Description
categoryId	string	Filtrer par catégorie
status	string	Statuts séparés par des virgules (ex. : OPEN,CLOSED)
search	string	Rechercher par titre
cursor	string	Curseur de pagination
limit	number	Taille de page (par défaut : 20)

Exemple :

curl "https://polymarket.sandbox.playbatman.com/api/v1/markets?status=OPEN,UPCOMING&limit=10" \
  -H "X-Api-Key: your-api-key"

Réponse :

{
  "success": true,
  "data": {
    "markets": [ ... ],
    "total": 42,
    "hasMore": true,
    "nextCursor": "cursor-value"
  }
}

Mettre à jour un marché

Met à jour les détails d'un marché. Seuls les marchés ayant le statut DRAFT ou UPCOMING peuvent voir leur titre, leur description et leurs horaires de trading modifiés.

PATCH /api/v1/markets/{id}

Corps de la requête :

Champ	Type	Description
title	string	Titre mis à jour
description	string	Description mise à jour
imageUrl	string	URL d'image mise à jour
categoryId	string	Catégorie mise à jour
tradingStartsAt	string (ISO 8601)	Heure de début mise à jour
tradingEndsAt	string (ISO 8601)	Heure de fin mise à jour
metadata	object	Métadonnées mises à jour

Actions du cycle de vie d'un marché

Ouvrir un marché

Fait passer un marché de l'état DRAFT à OPEN (ou UPCOMING si tradingStartsAt est dans le futur).

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

Suspendre un marché

Suspend temporairement les échanges sur un marché ouvert.

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

Corps de la requête :

Champ	Type	Requis	Description
reason	string	Oui	Raison de la suspension

Reprendre un marché

Reprend les échanges sur un marché suspendu.

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

Clôturer un marché

Clôture un marché pour arrêter tous les échanges. Généralement effectué lorsque l'événement sous-jacent s'est produit.

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

Résoudre un marché

Déclare le résultat gagnant pour un marché clôturé.

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

Corps de la requête :

Champ	Type	Requis	Description
winningOutcomeId	string	Oui	UUID du résultat gagnant
resolutionSource	string	Oui	Source de référence (ex. : "Official FIFA results")
resolutionNotes	string	Non	Contexte supplémentaire

Exemple :

curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/markets/{marketId}/resolve \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "winningOutcomeId": "outcome-uuid-1",
    "resolutionSource": "CoinGecko BTC/USD price feed",
    "resolutionNotes": "BTC hit $105,432 on March 15, 2026"
  }'

Annuler un marché

Annule un marché. Tous les ordres ouverts sont annulés.

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

Corps de la requête :

Champ	Type	Requis	Description
reason	string	Oui	Raison de l'annulation

Transitions de statut valides

De	Vers
DRAFT	OPEN, UPCOMING, CANCELLED
UPCOMING	OPEN, CANCELLED
OPEN	SUSPENDED, CLOSED, CANCELLED
SUSPENDED	OPEN, CLOSED, CANCELLED
CLOSED	RESOLVED, CANCELLED
RESOLVED	SETTLED