API Ordres

Les ordres constituent le mécanisme d'échange principal. Les opérateurs passent des ordres au nom de leurs joueurs. Le moteur de correspondance associe automatiquement les ordres d'achat et de vente compatibles.

Authentification : Toutes les routes nécessitent l'en-tête X-Api-Key.

Passer un ordre

Soumet un nouvel ordre au moteur de correspondance.

POST /api/v1/orders

Corps de la requête :

Champ	Type	Requis	Description
`marketId`	string	Oui	UUID du marché
`outcomeId`	string	Oui	UUID du résultat
`playerId`	string	Oui	Identifiant du joueur défini par l'opérateur
`side`	string	Oui	`BUY` ou `SELL`
`type`	string	Oui	`MARKET` ou `LIMIT`
`shares`	number	Oui	Nombre de parts (min : 1, max : 100 000)
`price`	number	Conditionnel	Prix de la part (requis pour les ordres `LIMIT`, plage : 0,01–0,99)
`transactionId`	string	Non	Référence/clé d'idempotence fournie par l'opérateur
`expiresAt`	string (ISO 8601)	Non	Date d'expiration de l'ordre

Validation du solde du joueur

Le moteur de prédiction ne vérifie pas les soldes des joueurs. Votre backend doit vérifier que le joueur peut se permettre l'ordre avant de le soumettre. Le coût d'un ordre BUY est shares * price pour les ordres LIMIT.

Exemple — Ordre d'achat à cours limité :

curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/orders \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "marketId": "market-uuid",
    "outcomeId": "outcome-uuid",
    "playerId": "player-123",
    "side": "BUY",
    "type": "LIMIT",
    "shares": 50,
    "price": 0.65,
    "transactionId": "op-txn-001"
  }'

Réponse (201 Created) :

{
  "success": true,
  "data": {
    "order": {
      "id": "order-uuid",
      "marketId": "market-uuid",
      "outcomeId": "outcome-uuid",
      "operatorId": "operator-uuid",
      "playerId": "player-123",
      "side": "BUY",
      "type": "LIMIT",
      "shares": "50",
      "price": "0.65",
      "filledShares": "30",
      "avgFillPrice": "0.60",
      "remainingShares": "20",
      "status": "PARTIAL",
      "transactionId": "op-txn-001",
      "expiresAt": null,
      "createdAt": "2026-02-18T22:00:00.000Z",
      "updatedAt": "2026-02-18T22:00:00.000Z"
    },
    "trades": [
      {
        "id": "trade-uuid",
        "marketId": "market-uuid",
        "outcomeId": "outcome-uuid",
        "buyOrderId": "order-uuid",
        "sellOrderId": "counter-order-uuid",
        "buyerOperatorId": "operator-uuid",
        "sellerOperatorId": "other-operator-uuid",
        "price": "0.60",
        "shares": "30",
        "buyerFee": "0.36",
        "sellerFee": "0.36",
        "createdAt": "2026-02-18T22:00:00.000Z"
      }
    ],
    "status": "PARTIAL",
    "filledShares": "30",
    "avgFillPrice": "0.60",
    "remainingShares": "20"
  }
}

Comportement de correspondance des ordres

Lorsque vous passez un ordre :

LIMIT BUY — Correspond aux ordres de vente existants dont le prix est inférieur ou égal à votre prix limite, en commençant par le prix vendeur le plus bas. Les parts non appariées restent dans le carnet d'ordres.
LIMIT SELL — Correspond aux ordres d'achat existants dont le prix est supérieur ou égal à votre prix limite, en commençant par l'offre la plus haute. Les parts non appariées restent dans le carnet d'ordres.
MARKET BUY — Correspond aux meilleurs ordres de vente disponibles à n'importe quel prix jusqu'à ce que les parts demandées soient satisfaites ou que la liquidité soit épuisée.
MARKET SELL — Correspond aux meilleurs ordres d'achat disponibles à n'importe quel prix jusqu'à ce que les parts demandées soient satisfaites ou que la liquidité soit épuisée.

Statuts des ordres

Statut	Description
`PENDING`	L'ordre est dans le carnet, aucune part n'a encore été appariée
`PARTIAL`	Certaines parts ont été appariées, le reste est toujours dans le carnet
`FILLED`	Toutes les parts ont été entièrement appariées
`CANCELLED`	Ordre annulé par l'opérateur ou le système
`EXPIRED`	Ordre expiré (date `expiresAt` dépassée)
`REJECTED`	Ordre rejeté (ex. : aucune liquidité pour un ordre au marché)

Annuler un ordre

Annule un ordre ouvert.

DELETE /api/v1/orders/{orderId}

Seuls les ordres avec le statut PENDING ou PARTIAL peuvent être annulés.

Exemple :

curl -X DELETE https://polymarket.sandbox.playbatman.com/api/v1/orders/{orderId} \
  -H "X-Api-Key: your-api-key"

Réponse :

{
  "success": true,
  "data": {
    "id": "order-uuid",
    "status": "CANCELLED",
    "remainingShares": "0",
    ...
  }
}

Obtenir un ordre

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

GET /api/v1/orders/{orderId}

Réponse : Même structure que l'objet order dans la réponse de passage d'ordre.

Lister les ordres

Liste les ordres de votre compte opérateur avec des filtres optionnels.

GET /api/v1/orders

Paramètres de requête :

Paramètre	Type	Description
`playerId`	string	Filtrer par identifiant de joueur
`marketId`	string	Filtrer par marché
`outcomeId`	string	Filtrer par résultat
`side`	string	Filtrer par sens (`BUY` ou `SELL`)
`type`	string	Filtrer par type (`MARKET` ou `LIMIT`)
`status`	string	Statuts séparés par des virgules
`cursor`	string	Curseur de pagination
`limit`	number	Taille de page

Exemple — Obtenir tous les ordres ouverts d'un joueur :

curl "https://polymarket.sandbox.playbatman.com/api/v1/orders?playerId=player-123&status=PENDING,PARTIAL" \
  -H "X-Api-Key: your-api-key"

Réponse :

{
  "success": true,
  "data": {
    "orders": [ ... ],
    "total": 5,
    "hasMore": false,
    "nextCursor": null
  }
}

Règles de validation

Règle	Détails
Le marché doit être `OPEN`	Les ordres sont rejetés si le marché a un autre statut
Fenêtre de trading active	L'heure actuelle doit être comprise entre `tradingStartsAt` et `tradingEndsAt`
Résultat valide	Le résultat doit appartenir au marché spécifié
Plage de parts	`1` à `100 000` (configurable)
Plage de prix	`0,01` à `0,99` (configurable, ordres LIMIT uniquement)
Vérification de position SELL	L'opérateur doit détenir suffisamment de parts pour vendre
`playerId` requis	Doit être une chaîne non vide

Codes d'erreur

Code	Description
`ORDER_NOT_FOUND`	L'ordre avec l'identifiant donné n'existe pas
`ORDER_INVALID_PRICE`	Prix hors de la plage autorisée
`ORDER_INVALID_SHARES`	Nombre de parts hors de la plage autorisée
`ORDER_CANNOT_CANCEL`	L'ordre n'est pas dans un statut annulable
`ORDER_NO_LIQUIDITY`	Aucun ordre correspondant disponible (ordres au marché)
`MARKET_NOT_OPEN`	Le marché n'est pas ouvert aux échanges
`POSITION_INSUFFICIENT_SHARES`	Pas assez de parts pour vendre

Passer un ordre​

Comportement de correspondance des ordres​

Statuts des ordres​

Annuler un ordre​

Obtenir un ordre​

Lister les ordres​

Règles de validation​

Codes d'erreur​